# ACP Registry is stabilized Source: https://agentclientprotocol.com/announcements/acp-agent-registry-stabilized Announcement that the ACP Registry RFD has been completed and the registry is stabilized. **Published:** March 9, 2026 The ACP Registry RFD has moved to Completed and the initial version of the registry is stabilized. The registry gives ACP clients a standard way to discover, install, and configure compatible agents. It introduces a curated catalog and a shared manifest format so editors and other clients do not need to invent their own integration metadata. If you want to explore the shipped experience, start with [ACP Registry](/get-started/registry). For the design history and rationale, see the [ACP Agent Registry RFD](/rfds/acp-agent-registry). # ACP v2 is available in Draft Source: https://agentclientprotocol.com/announcements/acp-v2-draft The ACP v2 protocol documentation and schema are published in draft form for review and testing. **Published:** July 20, 2026 Today is a day the ACP team has been working towards for months, and we are excited to share the **first Draft of version 2 of the Agent Client Protocol**. Since releasing v1, we have been able to leverage the future-compatible nature of the protocol and our [RFD process](/rfds) to ship **15+ RFDs** and their related features. A huge thank you to everyone who made this possible, and also proof that we can evolve the protocol rapidly without needing a huge migration every few months. However, it also became clear while working with v1 that **some** breaking changes would unlock new use cases and features that are hard to express in the protocol as it is today. v2 is all about making it possible to express more session states, consolidating on patterns we have found useful, and overall making everything more consistent. The goal was to avoid cramming as much as possible into a v2 and it never landing. So we are relying on our [RFD process](/rfds), that already worked so well in v1, to guide new features landing in both v1 and v2 as we move forward, and keep this release tightly focused on changing several core behaviors. If there is a new feature you really want, but don't see here, that doesn't mean it won't be added. We just wanted to decouple the release cadence for features that would remain optional or additive anyway. Our core design goal remains to provide as much freedom as possible to both agents and clients in their implementations, and agree on the semantically meaningful parts we need in order to do so. v2 enables allows even more flexibility in how an agent is able to work during a session, and also paves the way for new client patterns as well. ## The Big Themes of v2 ### Moving beyond the turn When we launched ACP v1, most agents happily emitted events only after a user-initiated message and usually stopped once they finished generating. But these days, agents are able to work longer and even orchestrate more and more work in the background. While the ACP v1 spec didn't *prohibit* `session/update` notifications from coming outside of the turn, it was a common point of confusion for implementers, who usually wanted to guarantee interaction patterns around the idea of a user-initiated turn, but it is clear that enforcing this actually prevents useful behavior. An agent could be ready to receive new input while background events are happening, but it still wants to provide real-time updates for those as well. If we stick with a turn-focused orientation for prompts, neither side is happy. If we want to allow for queueing, steering, or receiving updates from work that isn't necessarily initiated by the user, we need to make it clearer that the prompt request/response doesn't own the entire lifecycle of work being done. Now `session/update` notifications can proceed freely at any point in the session, and a prompt response returns the `messageId` of the user message inserted into the conversation, not the end of the turn. The agent reports that user message through the update stream with the same ID, which also makes it easier for both replay of retained history and the potential for multiple clients observing the same session. The agent can indicate when it is "idle", or ready to receive new inputs, allowing the client to indicate readiness, and agents can continue to update the session state in the meantime. You can read more about this in the [new prompt lifecycle RFD](/rfds/v2/prompt). ### Updating Messages and Streaming Tool Calls User and agent messages, tool calls, and terminal output are patched by stable IDs with uniform semantics: omitted fields stay unchanged, `null` clears, values replace, and chunks append. Message IDs are required as well so that messages can not only stream, but also update and replace in case of redaction or other needs. This was a pattern that was only available for tool calls before, but now is uniformly used across these session item types to make things more consistent and flexible. We also applied the message streaming pattern to tool call content, so that tool calls can be streamed in without buffering and resending the entire content over and over. ### Diff Overhaul The `oldText`/`newText` diff is replaced by structured file changes. You can now express add, delete, modify, move, copy, plus binary and non-text cases. Some of these could be inferred in the old structure, but not all, so we've hopefully made it possible to report all changes the agent makes on the filesystem. The agent can also provide an optional `git_patch` for rendering the changes. This can be shown as is, but is also structured enough for clients to do nice diff rendering for text changes as well. ### More flexible permission requests Permission prompts carry their own required `title` and optional `description`, with an extensible `subject` instead of a hard-wired tool call. This already allows a dedicated `command` subject for terminal commands, and leaves room for other subjects in the future. And decoupling the `title` and `description` from the tool call's title and content makes it possible to provide more context to the user making the decision without accidentally overriding the tool call itself. ### Forward compatibility by default One of the big goals in v1 was to make ACP extensible, which has been hugely successful. So many of you have built amazing features using these mechanisms, several of which have been upstreamed to the protocol itself. v2 now makes it possible to extend at just about every layer you can think of to allow for more experimentation or extension points when building tooling on top. Enum-like values across the schema accept unknown variants with a `_` prefix for implementation-specific extensions. This builds on the successful pattern we added for session config options and embeds it right in the schema. This makes sure new features don't cause older client and agents to choke on unknown nested data, and provides patterns for extending even more parts of the protocol where needed. ## Draft status **v2 is a Draft**. I personally went through every single line of the schema at least once, if not more, and I think it is in a solid state to start testing. **However, various pieces can, and will, change before stabilization.** That is the point of the draft stage: to receive feedback before we stabilize it. As you start implementing it, gate your implementation behind the version negotiation **AND** feature flags. Don't ship it by default in production until we are closer to stabilization. If we're lucky, not much will need to change between now and then. But we also want to avoid causing pain for users while we all navigate the necessary changes. Adding v2 support should not mean dropping v1. v1-only peers will remain common for some time, so implementers should support both versions side by side. We are working on making this easier to express in the various SDKs. A majority of the types haven't changed between versions, but if you maintain an Agent, Client, or SDK, the [migration guide](/protocol/v2/migration) walks through the key changes you need to know with before/after examples. ## Where to start * Read the [v2 protocol docs](/protocol/v2/overview) and the [migration guide](/protocol/v2/migration). * SDK authors can generate against the v2 JSON schemas, published in the repository releases tagged `schema-v2.0.0-alpha.N` alongside v1. * The [v2 RFD collection](/rfds/v2/overview) records the key decisions behind the larger changes. ## We want your feedback This is exactly the moment where feedback has the most leverage. If something in v2 doesn't work for your implementation, tell us before it stabilizes: open an issue or discussion on [GitHub](https://github.com/agentclientprotocol/agent-client-protocol), or engage with the individual RFDs through the [RFD process](/rfds). I firmly believe v2 provides a much better foundation for us to build on. It incorporates all of the learnings we've gained in the past year, consolidates on some common patterns, and allows for much more flexibility as we all build our agentic future together. Overall, I am astounded by how many of you have been using ACP to build your agents, clients, and just about everything else you can imagine. It is a big tent, and every new use case or app that adopts it brings me joy. Your creativity keeps us going, and I am excited to see what you all can do with v2. [Ben Brandt](https://github.com/benbrandt) Zed Industries / ACP Lead Maintainer # Additional Workspace Roots are stabilized Source: https://agentclientprotocol.com/announcements/additional-directories-stabilized Announcement that additional workspace roots are now part of the stable ACP protocol. **Published:** June 1, 2026 The [Additional Workspace Roots RFD](/rfds/additional-directories) has moved to Completed and `additionalDirectories` is stabilized for session lifecycle requests. Clients can provide an ordered list of absolute additional workspace roots when the Agent advertises support. The existing `cwd` remains the primary working directory, while the additional roots expand the session's filesystem scope. For the protocol documentation, see [Additional Workspace Roots](/protocol/v1/session-setup#additional-workspace-roots). # Boolean Config Options are stabilized Source: https://agentclientprotocol.com/announcements/boolean-config-option-stabilized Announcement that boolean session configuration options are now part of the stable ACP protocol. **Published:** July 6, 2026 The [Boolean Config Option Type RFD](/rfds/boolean-config-option) has moved to Completed and boolean session configuration options are stabilized. Agents can expose native on/off controls using `type: "boolean"`. In v1, Clients explicitly opt in through the `session.configOptions.boolean` capability, allowing Agents to preserve compatibility with Clients that only understand select options. For the protocol documentation, see [Boolean Config Options](/protocol/v1/session-config-options#boolean-config-options). # Client-provided system prompts are stabilized Source: https://agentclientprotocol.com/announcements/client-system-prompt-stabilized Clients can send system-level instructions on session setup in the stable ACP protocol surfaces. **Published:** November 6, 2026 The [Client-Provided System Prompt RFD](/rfds/client-system-prompt) has moved to Completed, stabilizing the `systemPrompt` field on session setup requests and the `systemPrompt` session capability. For protocol details, see [v1 Session Setup](/protocol/v1/session-setup#system-prompt) and [v2 Session Setup](/protocol/v2/session-setup#system-prompt). # Elicitation is stabilized Source: https://agentclientprotocol.com/announcements/elicitation-stabilized Announcement that structured elicitation is now part of the stable ACP protocol. **Published:** July 24, 2026 The [Elicitation RFD](/rfds/elicitation) has moved to Completed, stabilizing `elicitation/create` and the optional `elicitation/complete` notification. Agents can now ask users for structured, non-sensitive information through form mode or direct them to secure out-of-band interactions through URL mode. Clients advertise each supported mode explicitly during initialization. The protocol also defines explicit session, tool-call, and request scopes. For the protocol documentation, see [Elicitation](/protocol/v1/elicitation). # Implementation information for agents and clients Source: https://agentclientprotocol.com/announcements/implementation-information Protocol update introducing optional implementation metadata during initialization. **Published:** October 24, 2025 ACP now allows agents and clients to provide information about themselves to the other party during initialization. The [InitializeRequest](/protocol/v1/schema#initializerequest) message now includes an optional clientInfo field, and the [InitializeResponse](/protocol/v1/schema#initializeresponse) message includes an optional agentInfo field. This information can be used by clients to show users which agent is running and what version, by both sides to track usage metrics for which agents and clients are most popular among their users, and to help track down issues tied to particular implementation versions. This follows the existing pattern laid out in the [Model Context Protocol](https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle#initialization). This is being introduced as an optional field for now for backwards compatibility. It is possible it will be made required in a future version of the protocol, like MCP, so that both sides can count on this information being available. For the user-facing protocol guide, see [Implementation Information](/protocol/v1/initialization#implementation-information). # Logout Method is stabilized Source: https://agentclientprotocol.com/announcements/logout-method-stabilized Announcement that the logout method is now part of the stable ACP protocol. **Published:** May 21, 2026 The [Logout Method RFD](/rfds/logout-method) has moved to Completed and the `logout` method is stabilized. When advertised via `agentCapabilities.auth.logout`, Clients can now ask Agents to end the current authenticated state and return the connection to a state where future authentication-gated requests require `authenticate` again. For the protocol documentation, see [Logging Out](/protocol/v1/authentication#logging-out). # Message IDs are stabilized Source: https://agentclientprotocol.com/announcements/message-id-stabilized Announcement that optional Agent-generated message IDs are now part of the stable ACP v1 protocol. **Published:** June 5, 2026 The [Message ID RFD](/rfds/message-id) has moved to Completed and optional Agent-generated `messageId` fields are stabilized in ACP v1. Agents can attach opaque, unique IDs to streamed message chunks. Chunks with the same ID belong to the same message, while a changed ID marks a new message, giving Clients a reliable boundary beyond changes in chunk type. For the protocol documentation, see [Message IDs](/protocol/v1/prompt-turn#message-ids). # Model Config Category is stabilized Source: https://agentclientprotocol.com/announcements/model-config-category-stabilized Announcement that the model_config session configuration category is now part of the stable ACP protocol. **Published:** June 24, 2026 The [Model Config Option Category RFD](/rfds/model-config-category) has moved to Completed and the `model_config` category is stabilized. Agents can use the category for model-related parameters such as context size or speed and quality trade-offs. Clients can then group those options near the primary model selector without depending on Agent-specific option IDs. For the protocol documentation, see [Option Categories](/protocol/v1/session-config-options#option-categories). # Request Cancellation is stabilized Source: https://agentclientprotocol.com/announcements/request-cancellation-stabilized Announcement that protocol-level request cancellation is now part of the stable ACP protocol. **Published:** June 29, 2026 The [Request Cancellation RFD](/rfds/request-cancellation) has moved to Completed and the `$/cancel_request` notification is stabilized. Either side can use the optional notification to request cancellation of an outstanding JSON-RPC request by ID. Implementations can return a valid partial result or the standard `-32800` Request Cancelled error, while feature-specific mechanisms such as `session/cancel` remain available for richer semantics. For the protocol documentation, see [Cancellation](/protocol/v1/cancellation). # Rust and TypeScript SDKs reach 1.0 Source: https://agentclientprotocol.com/announcements/sdk-1-0-releases Announcement that the Rust and TypeScript ACP SDKs have reached version 1.0.0. **Published:** June 25, 2026 The [Rust SDK based on SACP RFD](/rfds/rust-sdk-v1) has moved to Completed after both the Rust and TypeScript ACP SDKs reached version 1.0.0. The Rust SDK's component-based architecture provides explicit message ordering and composable handlers for clients, agents, and protocol adapters. The matching TypeScript milestone demonstrates that the SDK design goals apply across language ecosystems. The releases are available as [`agent-client-protocol` v1.0.0](https://crates.io/crates/agent-client-protocol/1.0.0) and [`@agentclientprotocol/sdk` v1.0.0](https://www.npmjs.com/package/@agentclientprotocol/sdk/v/1.0.0). # Sergey Ignatov joins ACP as Lead Maintainer Source: https://agentclientprotocol.com/announcements/sergey-ignatov-lead-maintainer Governance announcement about Sergey Ignatov joining ACP as a Lead Maintainer. **Published:** February 18, 2026 It is with great pleasure that I announce that Sergey Ignatov, from JetBrains, will be joining me as a Lead Maintainer for ACP. Agus Zubiaga will remain a key part of the leadership group as a Core Maintainer. This is in recognition of Sergey’s many contributions to the protocol. We would not be where we are today without his efforts. In the past few months, Zed and JetBrains have been able to collaborate closely on the protocol, and it is time to reflect that fact more formally in our governance structure. I have enjoyed the chance to work with Sergey and the entire JetBrains team. There is still much work to be done, but with all of the agent and client teams working together, I am confident we can continue to make the ACP vision a reality: allowing you to collaborate with the agent or agents you love wherever you are already working. [Ben Brandt](https://github.com/benbrandt) Zed Industries / ACP Lead Maintainer # Session Close is stabilized Source: https://agentclientprotocol.com/announcements/session-close-stabilized Announcement that the session/close method is now part of the stable ACP protocol. **Published:** April 23, 2026 The [Session Close RFD](/rfds/session-close) has moved to Completed and the `session/close` method is stabilized. When advertised via `sessionCapabilities.close`, Clients can now ask Agents to cancel any ongoing work for a session and free the resources associated with it, without having to terminate the whole ACP process. This lets long-running Clients keep memory, threads, and subprocesses under control as users accumulate sessions over time. For the protocol documentation, see [Closing Active Sessions](/protocol/v1/session-setup#closing-active-sessions). # Session Config Options are stabilized Source: https://agentclientprotocol.com/announcements/session-config-options-stabilized Announcement that session-level configuration selectors are now part of the stable ACP protocol. **Published:** February 4, 2026 The Session Config Options RFD has moved to Completed and is stabilized. Session Config Options give agents a flexible way to expose session-level configuration such as models, modes, reasoning levels, and other selectors. Instead of hard-coding a small set of protocol-level controls, clients can render the options an agent provides and keep them in sync as they change. The stable protocol documentation is available in [Session Config Options](/protocol/v1/session-config-options), and the design history remains in the [Session Config Options RFD](/rfds/session-config-options). # Session Delete is stabilized Source: https://agentclientprotocol.com/announcements/session-delete-stabilized Announcement that the session/delete method is now part of the stable ACP protocol. **Published:** June 5, 2026 The [Session Delete RFD](/rfds/session-delete) has moved to Completed and the `session/delete` method is stabilized. Clients can use this capability-gated method to remove sessions from future `session/list` results. ACP standardizes the user-facing behavior while leaving soft deletion, hard deletion, and retention policy to the Agent. For the protocol documentation, see [Session Delete](/protocol/v1/session-delete). # Session Info Update is stabilized Source: https://agentclientprotocol.com/announcements/session-info-update-stabilized Announcement that the session_info_update notification is now part of the stable ACP protocol. **Published:** March 9, 2026 The Session Info Update RFD has moved to Completed and the session\_info\_update notification is stabilized. This lets agents push session metadata updates to clients in real time, including generated titles and related metadata, so session lists can stay current without polling. The stable protocol behavior is documented in [Session List](/protocol/v1/session-list#updating-session-metadata), and the design history remains in the [Session Info Update RFD](/rfds/session-info-update). # Session List is stabilized Source: https://agentclientprotocol.com/announcements/session-list-stabilized Announcement that the session/list method is now part of the stable ACP protocol. **Published:** March 9, 2026 The Session List RFD has moved to Completed and the session/list method is stabilized. This gives clients a standard way to discover sessions known to an agent, making features like session history, session switching, and cleanup much easier to implement consistently across ACP clients. For the shipped protocol, see [Session List](/protocol/v1/session-list). For the design history, see the [Session List RFD](/rfds/session-list). # Session Resume is stabilized Source: https://agentclientprotocol.com/announcements/session-resume-stabilized Announcement that the session/resume method is now part of the stable ACP protocol. **Published:** April 22, 2026 The Session Resume RFD has moved to Completed and the `session/resume` method is stabilized. Unlike `session/load`, `session/resume` reconnects clients to an existing session without replaying the conversation history. This is a simpler primitive for agents that can restore context but don't implement full history replay, and it gives proxies and adapters a foundation they can build `session/load` semantics on top of. For the shipped protocol, see [Resuming Sessions](/protocol/v1/session-setup#resuming-sessions). For the design history, see the [Session Resume RFD](/rfds/session-resume). # Session Usage Updates are stabilized Source: https://agentclientprotocol.com/announcements/session-usage-stabilized Announcement that session context and cumulative cost updates are now part of the stable ACP protocol. **Published:** June 5, 2026 The [Session Context Size and Cost RFD](/rfds/session-usage) has moved to Completed and `usage_update` session notifications are stabilized. Agents can report the current context token count and context-window size, along with optional cumulative session cost. This lets Clients keep context and cost displays current throughout the session lifecycle. For the protocol documentation, see [Session Usage Updates](/protocol/v1/prompt-turn#session-usage-updates). # Tool Call Names are stabilized Source: https://agentclientprotocol.com/announcements/tool-call-name-stabilized Optional programmatic tool-call names are now part of the stable ACP protocol surfaces. **Published:** September 17, 2026 The [Tool Call Name RFD](/rfds/tool-call-name) has moved to Completed, stabilizing the optional `name` field on tool calls. For protocol details, see [v1 Tool Calls](/protocol/v1/tool-calls) and [v2 Tool Calls](/protocol/v2/tool-calls). # Transports Working Group Source: https://agentclientprotocol.com/announcements/transports-working-group Announcing the new Transports Working Group, to stabilize new transport formats. **Published:** April 22, 2026 I'm excited to announce that we have a new Transports working group! Remote Agent support is a key focus of ACP, and in order to make this more of a reality, we need to standardize all of the approaches to transports people have been trying. We have started work on a Draft RFD for how this could work both via WebSockets and HTTP. Anna Zhdan will be representing from the Core Maintainers along with Alex Hancock from the Goose team who has been spearheading the RFD effort. A big thanks to both of you for starting this and I look forward to seeing what is next! [Ben Brandt](https://github.com/benbrandt) Zed Industries / ACP Lead Maintainer # Brand Source: https://agentclientprotocol.com/brand Assets for the Agent Client Protocol brand. Following these guidelines helps maintain brand integrity while supporting ACP's mission to standardize communication between code editors and coding agents. [Download all of the assets here](https://cdn.agentclientprotocol.com/acp-brand.zip) ## Logo The ACP logo can be used with the "ACP" logomark with or without a gradient. We provide a vertical and horizontal variant for display flexibility. ![Agentic Client Protocol Logo](https://mintcdn.com/zed-685ed6d6/0gwpXYa47bQsPCSW/assets/acp-docs-logo.webp?fit=max\&auto=format\&n=0gwpXYa47bQsPCSW\&q=85\&s=7b195e919dc200238c6029eb190235c0) ## Logomark The logomark has a variation that includes a slight gradient on the bottom right part of it. We don't enforce the use of one version over the other, meaning you can choose to use either of them as you wish, as long as you respect using it in pure white or pure black. ![Agentic Client Protocol Logomark](https://mintcdn.com/zed-685ed6d6/0gwpXYa47bQsPCSW/assets/acp-docs-logo-mark.webp?fit=max\&auto=format\&n=0gwpXYa47bQsPCSW\&q=85\&s=3ab81fb3792f3c613bcecafec5da05cf) # Code of Conduct Source: https://agentclientprotocol.com/community/code-of-conduct ## Our Pledge We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. ## Our Standards Examples of behavior that contributes to a positive environment for our community include: * Demonstrating empathy and kindness toward other people * Being respectful of differing opinions, viewpoints, and experiences * Giving and gracefully accepting constructive feedback * Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience * Focusing on what is best not just for us as individuals, but for the overall community Examples of unacceptable behavior include: * The use of sexualized language or imagery, and sexual attention or advances of any kind * Trolling, insulting or derogatory comments, and personal or political attacks * Public or private harassment * Publishing others' private information, such as a physical or email address, without their explicit permission * Other conduct which could reasonably be considered inappropriate in a professional setting ## Enforcement Responsibilities Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. ## Scope This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [hi@zed.dev](mailto:hi@zed.dev). All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the reporter of any incident. ## Enforcement Guidelines Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: ### 1. Correction **Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. **Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. ### 2. Warning **Community Impact**: A violation through a single incident or series of actions. **Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. ### 3. Temporary Ban **Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. **Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. ### 4. Permanent Ban **Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. **Consequence**: A permanent ban from any sort of public interaction within the community. ## Attribution [homepage]: https://www.contributor-covenant.org This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at [https://www.contributor-covenant.org/version/2/0/code\_of\_conduct.html](https://www.contributor-covenant.org/version/2/0/code_of_conduct.html). Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). For answers to common questions about this code of conduct, see [the Contributor Covenant FAQ](https://www.contributor-covenant.org/faq). For translations, see [Contributor Covenant Translations](https://www.contributor-covenant.org/translations). # Contributor Communication Source: https://agentclientprotocol.com/community/communication Communication methods for Agent Client Protocol contributors This document explains how to communicate and collaborate within the Agent Client Protocol (ACP) project. ## Communication Channels In short: * **[Zulip](https://agentclientprotocol.zulipchat.com/)**: For real-time or ad-hoc discussions. * **[RFDs](https://agentclientprotocol.com/rfds/about)**: For proposed changes to the specification. * **[GitHub Discussions](https://github.com/orgs/agentclientprotocol/discussions)**: For structured, longer-form discussions. * **[GitHub Issues](https://github.com/agentclientprotocol/agent-client-protocol/issues)**: For actionable tasks, bug reports, and feature requests. All communication is governed by our [Code of Conduct](https://agentclientprotocol.com/community/code-of-conduct). We expect all participants to maintain respectful, professional, and inclusive interactions across all channels. ### Zulip For real-time contributor discussion and collaboration. The server is designed around **ACP contributors** and is not intended to be a place for general ACP support. The Zulip server will have both public and private channels. [Join the Zulip here](https://agentclientprotocol.zulipchat.com/). #### Public Channels (Default) * **Purpose**: Open community engagement, collaborative development, and transparent project coordination. * Primary use cases: * **Public SDK and tooling development** * **Community onboarding** and contribution guidance. * **Community feedback** and collaborative brainstorming. * Avoid: * ACP user support: participants are expected to read official documentation and start new GitHub Discussions for questions or support. * Service or product marketing: interactions on this Zulip are expected to be vendor-neutral and not used for brand-building or sales. Mentions of brands or products are discouraged outside of being used as examples or responses to conversations that start off focused on the specification. #### Private channels (Exceptions) * **Purpose**: Confidential coordination and sensitive matters that cannot be discussed publicly. Access will be restricted to designated maintainers. * **Strict criteria for private use**: * **Security incidents** (CVEs, protocol vulnerabilities). * **People matters** (maintainer-related discussions, code of conduct policies). * Select channels will be configured to be **read-only**. This can be good for example for maintainer decision making. * Coordination requiring **immediate** or otherwise **focused response** with a limited audience. * **Transparency**: * **All technical and governance decisions** affecting the community **must be documented** in RFDs, GitHub Discussions and/or Issues. * **Some matters related to individual contributors** may remain private when appropriate (e.g., personal circumstances, disciplinary actions, or other sensitive individual matters). * Private channels are to be used as **temporary "incident rooms,"** not for routine development. Any significant discussion on Zulip leads to a potential decision or proposal must be moved to an RFD, GitHub Discussion, or GitHub Issue to create a persistent, searchable record. Proposals will then be promoted to full-fledged PRs with associated work items as needed. ### RFDs Please refer to the [RFD process](https://agentclientprotocol.com/rfds/about) for how this is managed. This is the primary way to actually create changes to the protocol. Conversation about a given RFD can take place within the relevant PRs created to move the RFD forward. Or, a discussion within Zulip can be created in the `rfds` channel to discuss in real-time with other contributors. ### GitHub Discussions For structured, long-form discussion and debate on project direction, features, improvements, and community topics. When to use: * Announcements and release communications * Community polls and consensus-building processes * Feature requests with context and rationale * If a particular repository does not have GitHub Discussions enabled, feel free to open a GitHub Issue instead. ### GitHub Issues For bug reports, feature tracking, and actionable development tasks. When to use: * Bug reports with reproducible steps * Documentation improvements with specific scope * CI/CD problems and infrastructure issues * Release tasks and milestone tracking ### Security Issues **Do not post security issues publicly.** Instead: 1. Contact lead and/or core maintainers, or [hi@zed.dev](mailto:hi@zed.dev) directly. 2. Follow responsible disclosure guidelines. # Contributing Source: https://agentclientprotocol.com/community/contributing How to participate in the development of ACP We welcome contributions from the community! All contributors must adhere to our [Code of Conduct](./code-of-conduct). For questions and discussions, please use GitHub Discussions. # Governance Source: https://agentclientprotocol.com/community/governance How the ACP project is governed > [!NOTE] > > The following is an interim governance model to provide clearer roles and > responsibilities between the various parties collaborating on ACP. > > ACP is jointly governed by Zed and JetBrains, who collaborate to ensure the > protocol serves the broader ecosystem. We aim to operate transparently and > make decisions in the best interests of ACP and its community, while working > toward transitioning to an independent foundation. This document describes the governance model for the Agent Client Protocol (ACP). It defines the roles, responsibilities, and processes that guide how the project operates and makes decisions. ## Principles We aim to operate transparently and make decisions in the best interests of ACP and its community. ## Technical Governance The ACP project adopts a hierarchical structure, similar to MCP, Rust Foundation projects, and other open source projects: * A community of **contributors** who file issues, make pull requests, and contribute to the project. * A small set of **maintainers** drive components within the ACP project, such as SDKs, documentation, and others. * Contributors and maintainers are overseen by **core maintainers**, who drive the overall project direction. * The core maintainers have two **lead core maintainers** who are the catch-all decision makers. * Maintainers, core maintainers, and lead core maintainers form the **ACP steering group**. All maintainers are expected to have a strong bias towards ACP's design philosophy. ### Channels Technical Governance is facilitated through shared [communication channels](/community/communication) of all **maintainers, core maintainers** and **lead maintainers**. Each maintainer group can choose additional communication channels, but all decisions and their supporting discussions must be recorded and made transparently available in one of the main communication channels. ### Contributors Anyone who submits code, documentation or other improvements is counted as a contributor. Contributors do not have formal decision-making power, but are encouraged to participate in discussions about project direction and propose changes. ### Maintainers Maintainers are responsible for [Working or Interest Groups](/community/working-interest-groups) within the ACP project. These generally are independent repositories such as language-specific SDKs, but can also extend to subdirectories of a repository, such as the ACP documentation. Maintainers may adopt their own rules and procedures for making decisions. Maintainers are expected to make decisions for their respective projects independently, but can defer or escalate to the core maintainers when needed. Maintainers are responsible for the: * Thoughtful and productive engagement with community contributors, * Maintaining and improving their respective area of the ACP project, * Supporting documentation, roadmaps and other adjacent parts of the ACP project, * Present ideas from community to core. New maintainers are added by a consensus or majority vote of the current core maintainers, based on sustained and high-quality contributions to the project, alignment with its goals, and a demonstrated commitment to community standards. Prospective maintainers should have a track record of participation in discussions, issue triage, and code or documentation improvements. Maintainers have write and/or admin access to their respective repositories. A maintainer may step down at any time by notifying the other maintainers. In rare cases, a maintainer may be removed by a consensus or a two-thirds supermajority vote of the other maintainers if they are inactive for an extended period, violate the Code of Conduct, or act against the project’s interests. Maintainers can be removed by core maintainers or lead core maintainers at any time and without reason. ### Core Maintainers Core maintainers are contributors who have write access to ACP’s source code. They review and merge contributions, participate in project decision-making, and help to onboard and mentor new contributors. The core maintainers are expected to have a deep understanding of the Agent Client Protocol and its specification. Their responsibilities include: * Designing, reviewing and steering the evolution of the ACP specification, as well as all other parts of the ACP project, such as documentation, * Articulating a cohesive long-term vision for the project, * Mediating and resolving contentious issues with fairness and transparency, seeking consensus where possible while making decisive choices when necessary, * Appoint or remove maintainers, * Stewardship of the ACP project in the best interest of ACP. The core maintainers as a group have the power to veto any decisions made by maintainers by majority vote. The core maintainers have power to resolve disputes as they see fit. The core maintainers should publicly articulate their decision-making. The core group is responsible for adopting their own procedures for making decisions. New core maintainers are added by a consensus or majority vote of the current core and lead maintainers, based on sustained and high-quality contributions to the project, alignment with its goals, and a demonstrated commitment to community standards. Prospective maintainers should have a track record of participation in discussions, issue triage, and code or documentation improvements. Core maintainers generally have write and admin access to all ACP repositories, but should use the same contribution (usually pull-requests) mechanism as outside contributors. Exceptions can be made based on security considerations. A core maintainer may step down at any time by notifying the other core maintainers. In rare cases, a core maintainer may be removed by a consensus or a two-thirds supermajority vote of the other core maintainers if they are inactive for an extended period, violate the Code of Conduct, or act against the project’s interests. ### Lead Maintainers (BDFL) ACP has two lead maintainers: Ben Brandt (Zed Industries) and Sergey Ignatov (JetBrains). Lead Maintainers can veto any decision by core maintainers or maintainers. This model is also commonly known as Benevolent Dictator for Life (BDFL) in the open source community. The Lead Maintainers should publicly articulate their decision-making and give clear reasoning for their decisions. Lead maintainers are part of the core maintainer group. Lead Maintainers are administrators on all infrastructure for the ACP project where possible. This includes but is not restricted to all communication channels, GitHub organizations and repositories. The Lead Maintainers are the primary contacts, and responsible for: * Representing ACP in official matters. * Coordinating major decisions about project direction. * Signing off project expenses. A lead maintainer may step down by notifying the other lead maintainer(s). They may recommend a replacement, but it is the remaining lead maintainer(s) responsibility to select a replacement. If all lead maintainers step down, the core maintainers will select new lead maintainers by consensus or majority vote. ### Decision Process The core maintainer group meets every two weeks to discuss and vote on proposals, as well as discuss any topics needed. The [ACP RFD process](https://agentclientprotocol.com/rfds/about) and Zulip chat can be used to discuss and vote on smaller proposals as needed. ## Processes Core and lead maintainers are responsible for all aspects of Agent Client Protocol, including documentation, issues, suggestions for content, and all other parts under the [ACP project](https://github.com/agentclientprotocol). Maintainers are responsible for documentation, issues, and suggestions of content for their area of the ACP project, but are encouraged to partake in general maintenance of the ACP projects. Maintainers, core maintainers, and lead maintainers should use the same contribution process as external contributors, rather than making direct changes to repos. This provides insight into intent and opportunity for discussion. ### Working and Interest Groups ACP collaboration and contributions are organized around two structures: [Working Groups and Interest Groups](/community/working-interest-groups). Interest Groups are responsible for identifying and articulating problems that ACP should address, primarily by facilitating open discussions within the community. In contrast, Working Groups focus on developing concrete solutions by collaboratively producing deliverables, such as RFDs or community-owned implementations of the specification. While input from Interest Groups can help justify the formation of a Working Group, it is not a strict requirement. Similarly, contributions from either Interest Groups or Working Groups are encouraged, but not mandatory, when submitting RFDs or other community proposals. We strongly encourage all contributors interested in working on a specific RFD to first collaborate within an Interest Group. This collaborative process helps ensure that the proposed RFD aligns with protocol needs and is the right direction for its adopters. ### Governance Principles All groups are self-governed while adhering to these core principles: 1. Clear contribution and decision-making processes 2. Open communication and transparent decisions They must: * Document their contribution process * Maintain transparent communication * Make decisions publicly (groups must publish meeting notes and proposals) Projects and working groups without specified processes default to: * GitHub pull requests and issues for contributions * A public channel in the official [ACP Contributor Zulip](/community/communication#zulip) ### Maintenance Responsibilities Components without dedicated maintainers (such as documentation) fall under core maintainer responsibility. These follow standard contribution guidelines through pull requests, with maintainers handling reviews and escalating to core maintainer review for any significant changes. Core maintainers and maintainers are encouraged to improve any part of the ACP project, regardless of formal maintenance assignments. ## Communication ### Core Maintainer Meetings The core maintainer group meets on a bi-weekly basis to discuss proposals and the project. Notes on proposals should be made public. The meetings themselves are invite-only. If you have a topic for the Core Maintainers and want to be added to the agenda, let the core maintainers know what you want to discuss in advance in Zulip, and you will be invited to join the next meeting. ### Public Chat The ACP project maintains a [public Zulip Chat](/community/communication#zulip) with open chats for different groups. The ACP project may have private channels for certain communications. ## Nominating, Confirming and Removing Maintainers ### The Principles * Membership in module maintainer groups is given to individuals on merit basis after they demonstrated strong expertise of their area of work through contributions, reviews, and discussions and are aligned with the overall ACP direction. * For membership in the maintainer group the individual has to demonstrate strong and continued alignment with the overall ACP principles. * No term limits for module maintainers or core maintainers * Light criteria of moving sub-project maintenance to 'emeritus' status if they don't actively participate over long periods of time. Each maintainer group may define the inactive period that's appropriate for their area. ### Nomination and Removal * Core Maintainers are responsible for adding and removing maintainers. They will take the consideration of existing maintainers into account. * The lead maintainers are responsible for adding and removing core maintainers. #### Nomination Process If a Maintainer (or Core / Lead Maintainer) wishes to propose a nomination for the Core / Lead Maintainers’ consideration, they should follow the following process: 1. Collect evidence for the nomination. This will generally come in the form of a history of merged PRs on the repositories for which maintainership is being considered. 2. Discuss among maintainers of the relevant group(s) as to whether they would be supportive of approving the nomination. 3. DM a Core Maintainer to create a private channel in Zulip, in the format `nomination-{name}-{group}`. Add all core maintainers, lead maintainers, and co-maintainers on the relevant group. 4. Provide context for the individual under nomination. See below for suggestions on what to include here. 5. Create a Zulip topic and ask Core / Lead Maintainers to vote Yes / No on the nomination. Reaching consensus is encouraged though not required. 6. After Core / Lead Maintainers discuss and/or vote, if the nomination is favorable, relevant members with permissions to update GitHub and Zulip roles will add the nominee to the appropriate groups. The nominator should announce the new maintainership in the relevant Zulip channel. 7. The temporary Zulip channel will be deleted a week later. Suggestions for the kind of information to share with core maintainers when nominating someone: * GitHub profile link, LinkedIn profile link, Zulip username * For what group(s) are you nominating the individual for maintainership * Whether the group(s) agree that this person should be elevated to maintainership * Description of their contributions to date (including links to most substantial contributions) * Description of expected contributions moving forward (e.g. Are they eager to be a maintainer? Will they have capacity to do so?) * Other context about the individual (e.g. current employer, motivations behind ACP involvement) * Anything else you think may be relevant to consider for the nomination ## Current Maintainers Refer to [the maintainer list](https://github.com/agentclientprotocol/agent-client-protocol/blob/main/MAINTAINERS.md). ## Security Policy and Vulnerability Disclosure * Zed will triage all potential security and vulnerability issues between the Zed team and other maintainers * Reports can be submitted to [security@zed.dev](mailto:security@zed.dev) ## Legal, Licensing, and Contributor Terms * All repositories in the ACP organization should be licensed under the Apache 2.0 License. * This project does not require a Contributor License Agreement (CLA). Instead, contributions are accepted under the following terms: > By contributing to this project, you agree that your contributions will be licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0). You affirm that you have the legal right to submit your work, that you are not including code you do not have rights to, and that you understand contributions are made without requiring a Contributor License Agreement (CLA). # Working and Interest Groups Source: https://agentclientprotocol.com/community/working-interest-groups Learn about the two forms of collaborative groups within the Agent Client Protocol's governance structure - Working Groups and Interest Groups. Within the ACP contributor community we maintain two types of collaboration formats - **Interest** and **Working** groups. **Interest Groups** are responsible for identifying and articulating problems that ACP should address, primarily by facilitating open discussions within the community. In contrast, **Working Groups** focus on developing concrete solutions by collaboratively producing deliverables, such as RFDs or community-owned implementations of the specification. While input from Interest Groups can help justify the formation of a Working Group, it is not a strict requirement. Similarly, contributions from either Interest Groups or Working Groups are encouraged, but not mandatory, when submitting RFDs or other community proposals. We strongly encourage all contributors interested in working on a specific RFD to first collaborate within an Interest Group. This collaborative process helps ensure that the proposed RFD aligns with community needs and is the right direction for the protocol. Long-term projects in the ACP ecosystem, such as SDKs or other components are maintained by dedicated Working Groups. ## Purpose These groups exist to: * **Facilitate high-signal spaces for focused discussions** - contributors who opt into notifications, expertise sharing, and regular meetings can engage with topics that are highly relevant to them, enabling meaningful contributions and opportunities to learn from others. * **Establish clear expectations and leadership roles** - guide collaborative efforts and ensure steady progress toward concrete deliverables that advance ACP evolution and adoption. ## Mechanisms ## Meeting Calendar All Interest Group and Working Group meetings are published on the public ACP community calendar (work in progress). Facilitators are responsible for posting their meeting schedules to this calendar in advance to ensure discoverability and enable broader community participation. ### Interest Groups (IGs) **Goal:** Facilitate discussion and knowledge-sharing among ACP contributors who share interests in a specific ACP sub-topic or context. The primary focus is on identifying and gathering problems that may be worth addressing through RFDs or other community artifacts, while encouraging open exploration of protocol issues and opportunities. **Expectations**: * Regular conversations in the Interest Group Zulip channel * **AND/OR** a recurring live meeting regularly attended by Interest Group members * Meeting dates and times published in advance on the ACP community calendar when applicable, and tagged with their primary topic and interest group Zulip channel name * Notes publicly shared after meetings, and submitted to the [meetings repository](https://github.com/agentclientprotocol/meetings) **Lifecycle**: * Creation begins by proposing a new Interest Group to the core/lead maintainers with the template below * Majority positive vote by core maintainers over a 72h period approves creation of the group. * The creation of the group can be reversed at any time (e.g., after new information surfaces). Core and lead maintainers can veto. * Facilitator(s) and Maintainer(s) responsible for organizing IG into meeting expectations * Facilitator is an informal role responsible for shepherding or speaking for a group * Maintainer is an official representative from the ACP steering group. A maintainer is not required for every group, but can help advocate for specific changes or initiatives. * IG is retired only when Core or Lead Maintainers determine it's no longer active and/or needed * Successful IGs do not have a time limit or expiration date - as long as they are active and maintained, they will remain available **Creation Template**: * Facilitator(s) * Maintainer(s) (optional) * IGs with potentially similar goals/discussions * How this IG differentiates itself from the related IGs * First topic you to discuss within the IG Participation in an Interest Group (IG) is not required to start a Working Group (WG) or to create a RFD. However, building consensus within IGs can be valuable when justifying the formation of a WG. Likewise, referencing support from IGs or WGs can strengthen a RFD and its chances of success. ### Working Groups (WG) **Goal:** Facilitate collaboration within the ACP community on a RFD, a themed series of RFDs, or an otherwise officially endorsed project. **Expectations**: * Meaningful progress towards at least one RFD or spec-related implementation **OR** hold maintenance responsibilities for a project (e.g., SDKs) * Facilitators are responsible for keeping track of progress and communicating status when appropriate * Meeting dates and times published in advance on the ACP community calendar when applicable, and tagged with their primary topic and working group Zulip channel name * Notes publicly shared after meetings, and submitted to the [meetings repository](https://github.com/agentclientprotocol/meetings) **Lifecycle**: * Creation begins by proposing a new Interest Group to the core/lead maintainers with the template below * Majority positive vote by core maintainers over a 72h period approves creation of the group. * The creation of the group can be reversed at any time (e.g., after new information surfaces). Core and lead maintainers can veto. * Facilitator(s) and Maintainer(s) responsible for organizing WG into meeting expectations * Facilitator is an informal role responsible for shepherding or speaking for a group * Maintainer is an official representative from the ACP steering group. A maintainer is not required for every group, but can help advocate for specific changes or initiatives * WG is retired when either: * Community moderators or Core and Lead Maintainers decide it is no longer active and/or needed * The WG no longer has an active Issue/PR for a month or more, or has completed all Issues/PRs it intended to pursue. **Creation Template**: * Facilitator(s) * Maintainer(s) (optional) * Explanation of interest/use cases, ideally originating from an IG discussion; however that is not a requirement * First Issue/PR/RFD that the WG will work on ## WG/IG Facilitators A **Facilitator** role in a WG or IG does *not* result in a [maintainership role](https://github.com/agentclientprotocol/agent-client-protocol/blob/main/MAINTAINERS.md) across the ACP organization. It is an informal role into which anyone can self-nominate. A Facilitator is responsible for helping shepherd discussions and collaboration within an Interest or Working Group. Lead and Core Maintainers reserve the right to modify the list of Facilitators and Maintainers for any WG/IG at any time. ## FAQ ### How do I get involved contributing to ACP? These IG and WG abstractions help provide an elegant on-ramp: 1. [Join the Zulip](/community/communication#zulip) and follow conversations in IGs relevant to you. Attend live calls. Participate. 2. Offer to facilitate calls. Contribute your use cases in RFD proposals and other work. 3. When you're comfortable contributing to deliverables, jump in to contribute to WG work. 4. Active and valuable contributors will be nominated by WG maintainers as new maintainers. ### Where can I find a list of all current WGs and IGs? On the [ACP Zulip Chat](/community/communication#zulip) there is a section of channels for each Working and Interest Group. # Agents Source: https://agentclientprotocol.com/get-started/agents Agents implementing the Agent Client Protocol. The following agents can be used with an ACP Client: * [acp-llm-adapter](https://github.com/euri10/acp-llm-adapter) (DeepSeek, GLM, Groq) * [AgentPool](https://phil65.github.io/agentpool/advanced/acp-integration/) * [Augment Code](https://docs.augmentcode.com/cli/acp) * [AutoDev](https://github.com/phodal/auto-dev) * [Blackbox AI](https://docs.blackbox.ai/features/blackbox-cli/introduction) * [Bub](https://github.com/bubbuild/bub) (via [bub-acp-server](https://github.com/bubbuild/bub-contrib/tree/main/packages/bub-acp-server)) * [Claude Agent](https://platform.claude.com/docs/en/agent-sdk/overview) (via [Zed's SDK adapter](https://github.com/zed-industries/claude-agent-acp)) * [Claw Orchestrator](https://github.com/Enderfga/claw-orchestrator/blob/main/skills/references/acp.md) * [Cline](https://cline.bot/) * [Codex CLI](https://developers.openai.com/codex/cli) (via [ACP's adapter](https://github.com/agentclientprotocol/codex-acp)) * [Code Assistant](https://github.com/stippi/code-assistant?tab=readme-ov-file#configuration) * [Command Code](https://commandcode.ai/docs/acp) * [Construct](https://github.com/construct-worlds/construct#acp-agent-client-protocol-server) * [crow-cli](https://crow-ai.dev) * [CUGA](https://github.com/cuga-project/cuga-agent/tree/main/docs/examples/acp_stdio) (`cuga-acp`) * [Cursor](https://cursor.com/docs/cli/acp) * [Docker's cagent](https://github.com/docker/cagent) * [fast-agent](https://fast-agent.ai/acp) * [Factory Droid](https://factory.ai/) * [fount](https://github.com/steve02081504/fount) * [Gemini CLI](https://github.com/google-gemini/gemini-cli) * [GitHub Copilot](https://github.com/features/copilot) (in [public preview](https://github.blog/changelog/2026-01-28-acp-support-in-copilot-cli-is-now-in-public-preview/)) * [Goose](https://block.github.io/goose/docs/guides/acp-clients) * [Hermes Agent](https://hermes-agent.nousresearch.com/docs/user-guide/features/acp) * [Imagera Code](https://imagera.ai/code) (`imagera-code acp`) * [Inferpal](https://github.com/EstaxNet/Inferpal/blob/master/docs/acp.md) (`Inferpal.Host --acp`) * [Junie by JetBrains](https://junie.jetbrains.com) * [Kaagum](https://git.systemreboot.net/kaagum/about/) * [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) * [Kiro CLI](https://kiro.dev/docs/cli/acp/) * [localharness](https://github.com/compusophy/localharness#quickstart) * [Mercury CLI](https://github.com/Whq02/MercuryCLI/blob/main/docs/AUTOMATION.md) (`mercury acp`) * [Minion Code](https://github.com/femto/minion-code) * [Mistral Vibe](https://github.com/mistralai/mistral-vibe) * [Muse Spark Code](https://github.com/RandyNorthrup/muse-spark-code/blob/main/docs/acp.md) (unofficial agent for Meta's Muse Spark) * [Octomind](https://github.com/muvon/octomind/blob/master/doc/integration/02-acp-protocol.md) (`octomind acp`) * [OpenClaw](https://docs.openclaw.ai/cli/acp) * [OpenCode](https://github.com/sst/opencode) * [OpenHands](https://docs.openhands.dev/openhands/usage/run-openhands/acp) * [Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) (via [pi-acp adapter](https://github.com/svkozak/pi-acp)) * [Poolside](https://github.com/poolsideai/pool) * [Qoder CLI](https://docs.qoder.com/cli/acp) * [Qwen Code](https://github.com/QwenLM/qwen-code) * [Raven](https://evermind-ai.github.io/Raven/agent-protocols/) (`raven acp`) * [Raxol](https://github.com/DROOdotFOO/raxol/blob/master/docs/features/CODING_AGENT.md) (`raxol acp`) * [siGit Code](https://github.com/getsigit/sigit) * [Stakpak](https://github.com/stakpak/agent?tab=readme-ov-file#agent-client-protocol-acp) * [stdio Bus](https://github.com/stdiobus/stdiobus) * [VT Code](https://github.com/vinhnx/vtcode/blob/main/README.md#zed-ide-integration-agent-client-protocol) * [ZenCODE](https://github.com/gerardogrisolini/ZenCODE/blob/main/Docs/xcode.md) (`zen --acp`) * [zycode](https://zycode.dev) (`pi-agent-cli-lc`) # Architecture Source: https://agentclientprotocol.com/get-started/architecture Overview of the Agent Client Protocol architecture. The Agent Client Protocol defines a standard interface for communication between AI agents and client applications. The architecture is designed to be flexible, extensible, and platform-agnostic. ## Design Philosophy The protocol architecture follows several key principles: 1. **MCP-friendly**: The protocol is built on JSON-RPC, and re-uses MCP types where possible so that integrators don't need to build yet-another representation for common data types. 2. **UX-first**: It is designed to solve the UX challenges of interacting with AI agents; ensuring there's enough flexibility to render clearly the agents intent, but is no more abstract than it needs to be. 3. **Trusted**: ACP works when you're using a code editor to talk to a model you trust. You still have controls over the agent's tool calls, but the code editor gives the agent access to local files and MCP servers. ## Setup When the user tries to connect to an agent, the editor boots the agent sub-process on demand, and all communication happens over stdin/stdout. Each connection can support several concurrent sessions, so you can have multiple trains of thought going on at once. ![Server Client setup](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/images/server-client.svg?fit=max\&auto=format\&n=ZwvtxaoaZwBJrK5s\&q=85\&s=336b604262b9b61ece9fc402774185bf) ACP makes heavy use of JSON-RPC notifications to allow the agent to stream updates to the UI in real-time. It also uses JSON-RPC's bidirectional requests to allow the agent to make requests of the code editor: for example to request permissions for a tool call. ## MCP Commonly the code editor will have user-configured MCP servers. When forwarding the prompt from the user, it passes configuration for these to the agent. This allows the agent to connect directly to the MCP server. ![MCP Server connection](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/images/mcp.svg?fit=max\&auto=format\&n=ZwvtxaoaZwBJrK5s\&q=85\&s=87650126080bf3bb4d983f447889ab86) The code editor may itself also wish to export MCP based tools. Instead of trying to run MCP and ACP on the same socket, the code editor can provide its own MCP server as configuration. As agents may only support MCP over stdio, the code editor can provide a small proxy that tunnels requests back to itself: ![MCP connection to self](https://mintcdn.com/zed-685ed6d6/ZwvtxaoaZwBJrK5s/images/mcp-proxy.svg?fit=max\&auto=format\&n=ZwvtxaoaZwBJrK5s\&q=85\&s=dd128411c4be5945e131596190b41cb8) # Clients Source: https://agentclientprotocol.com/get-started/clients Clients, frameworks, connectors, and related tools around the Agent Client Protocol. The following projects implement ACP directly, connect ACP agents to other environments, or support adjacent coding-agent workflows. ## Editors and IDEs * [Anycode](https://github.com/anycode-ade/anycode) — web-based IDE with Rust backend and React frontend * [Athas](https://athas.dev) — lightweight open-source code editor (Tauri, Rust + React) with built-in ACP agent sessions and one-click agent install from the ACP Registry * [Chrome ACP](https://github.com/Areo-Joe/chrome-acp) (Chrome extension / PWA) * [ACP Sidebar](https://github.com/aganhui/acp-sidepanel) (Chrome extension) — side-panel chat with your local Claude Code, with one-click quoting of selections and full pages * Emacs via [agent-shell.el](https://github.com/xenodium/agent-shell) * [Exo for VSCode](https://marketplace.visualstudio.com/items?itemName=AntonSubbotin.exo) — A typography-first VS Code client featuring parallel sessions isolated in Git worktrees, native Diff Editor approvals, and a distraction-free, highly polished UI. * [JetBrains](https://www.jetbrains.com/help/ai-assistant/acp.html) * [necoder](https://necoder.com/en/) — GPUI-native code editor (Rust) that runs ACP agents as color-coded threads tied to a project and branch, with destination chips, an always-visible token meter, and a Fleet view for running several agents in parallel Git worktrees * [neovim](https://neovim.io) * through the [CodeCompanion](https://github.com/olimorris/codecompanion.nvim) plugin * through the [carlos-algms/agentic.nvim](https://github.com/carlos-algms/agentic.nvim) plugin * through the [yetone/avante.nvim](https://github.com/yetone/avante.nvim) plugin * through the [hermes.nvim](https://github.com/Ruddickmg/hermes.nvim) plugin * [Obsidian](https://obsidian.md) * through the [Agent Client](https://github.com/RAIT-09/obsidian-agent-client) plugin * through the [Agent Console](https://github.com/donivatamazondotcom/obsidian-agent-console) plugin — a tabbed multi-session workspace: run several ACP agents in parallel with restorable, searchable sessions and quick prompts * through the [Copilot for Obsidian](https://github.com/logancyang/obsidian-copilot) plugin — runs OpenCode and Codex through ACP with vault context, projects, and shared skills * through the [Obsidian Harness](https://github.com/vlln/obsidian-harness) plugin — Obsidian as a cockpit for ACP agents (Claude Code, Codex, Gemini CLI, Pi); every agent session is a first-class `.session` vault file with Codex-style Session and Turn navigators * [Oleafly](https://oleafly.com) — LaTeX, Typst and Markdown editor for research writing (Tauri, Rust + React) that runs Claude Code, Codex and other ACP agents next to the source, the PDF and Git history * [Open Knowledge](https://openknowledge.ai) — local-first Markdown knowledge base with built-in ACP agent threads and one-click agent install from the ACP Registry * [Pulsar](https://pulsar-edit.dev) — through the [pulsar-acp-agent](https://github.com/hovancik/pulsar-acp-agent) package * [Qt Creator](https://www.qt.io/development/tools/qt-creator-ide) — through the [ACP Client Plugin](https://doc.qt.io/qtcreator/creator-how-to-use-acp-client.html) * [Sublime Text](https://www.sublimetext.com) - through the [ACP plugin](https://github.com/debjan/sublime-acp) * [Unity ACP Client](https://github.com/3DLabInstruments/UnityACPClient)(Unity plugin) * [Unity Agent Client](https://github.com/nuskey8/UnityAgentClient) (Unity editor) * Visual Studio — through the [Poolside Assistant](https://marketplace.visualstudio.com/items?itemName=poolside-ai.vs-acp-assistant) * Visual Studio Code * [ACP Client](https://github.com/formulahendry/vscode-acp) extension * [ACP Patchbay](https://github.com/solutionsunity/acp-patchbay) extension * [ACP Pro Extension](https://marketplace.visualstudio.com/items?itemName=duclvz.acp-pro) * VS Code–compatible IDEs (Cursor, Windsurf, Trae,..): [ACP Pro Extension](https://open-vsx.org/extension/duclvz/acp-pro) * [Multicoder](https://marketplace.visualstudio.com/items?itemName=multicoder.multicoder) extension * [Poolside Assistant](https://marketplace.visualstudio.com/items?itemName=poolside-ai.acp-assistant) * [Volt](https://github.com/LeulAria/volt) — open-source (MIT) agent workspace built on the VS Code core; runs Claude Code, Codex, OpenCode and other ACP agents next to the editor, Git, terminal and an in-app browser, with hunk-by-hunk keep/undo of agent edits and a Git checkpoint every turn (macOS, Windows, Linux) * [Zed](https://zed.dev/docs/ai/external-agents) ## CLI and TUI * [acpx (CLI)](https://github.com/openclaw/acpx) * [Hash (shell)](https://github.com/tfcace/hash) * [Hydra](https://github.com/smagnuso/hydra-acp) * [Martty](https://github.com/openma-ai/Martty) — extensible Rust/ratatui terminal client for DeepSeek Harness and other ACP-compatible agents * [Nori CLI](https://github.com/tilework-tech/nori-cli) * [Orca CLI](https://github.com/stablyai/orca) — CLI and daemon (`orcad`) for orchestrating parallel ACP and terminal coding agents across Git worktrees, task DAGs, and remote WSL/SSH hosts * [pool](https://github.com/poolsideai/pool) * [Raven](https://github.com/EverMind-AI/Raven) — host agent (CLI, terminal UI and web UI) that plans a task as a DAG and runs each node on a built-in agent or on an ACP agent it launches * [Toad](https://www.batrachian.ai/) * [Intelligent Terminal](https://github.com/microsoft/intelligent-terminal) — Windows Terminal fork with native agent integration, driving ACP-compatible agent CLIs over stdio * [SpurCode](https://github.com/getspur/SpurCode) — Rust-native terminal orchestrator that runs a mixed fleet of ACP agents (Claude Code, Codex, Gemini, Kimi, OpenCode and more) in parallel across Git worktrees, from one TUI * [acp-runner](https://github.com/ranvirsingh/acp-runner) — CLI that runs multi-step agent workflows from one `agent.yaml`: each step sends a prompt to Claude Code, Codex or any ACP agent, runs a shell command as a check, and can loop back to an earlier step on failure, with per-step MCP tool scoping ## Desktop and Web * [ACP UI](https://github.com/formulahendry/acp-ui) (Windows, macOS, Linux, iOS, Android, Web) * [AcpAgent Client](https://github.com/ClickPM/AcpAgentClient) — open-source (GPL-3.0) multi-agent desktop client built on the official Rust SDK: one-click agent install from the ACP Registry, Agent Auth and Terminal Auth, file browser, embedded terminals, and an ACP traffic inspector (Windows) * [Acpira](https://acpira.com) ([GitHub](https://github.com/hotic/acpira)) — open-source (MIT) workbench with a Rust engine that runs Claude Code, Codex and other ACP agents on their own login and harness, plus a built-in agent for any OpenAI- or Anthropic-compatible API; agents call each other with @name, and a context report maps what filled the context window (macOS, Windows, Linux; also VS Code, IntelliJ and iOS) * [Agent Studio](https://github.com/sxhxliang/agent-studio) * [AgentConnect](https://github.com/agentconnect-md/agentconnect) — open-source multi-agent platform that brings ACP agents into team workflows across Slack, Telegram, Discord, Lark, GitHub, and GitLab, managed from a web console * [AgentRQ](https://github.com/agentrq/agentrq) — Human-in-the-loop realtime task management and collaboration (Web) * [AionUi](https://github.com/iOfficeAI/AionUi) — open-source desktop client that runs several ACP agents side by side in one window, each in its own session, with MCP support, file preview, scheduled tasks, and a WebUI for reaching the same sessions from another device (Windows, macOS, Linux) * [AiRC Orchestration](https://github.com/AiRC-ai/AiRC-Orchestration) — desktop ACP client and agent orchestrator with configurable parallel model teams, MCP tools, persistent project goals and plans, approval controls, and optional supervision across supported local and hosted providers (Windows, macOS, Linux) * [aizen](https://aizen.win) * [Alchemist Coder](https://github.com/Alekla0126/alchemist-coder) — open-source (AGPL-3.0) desktop app that runs Claude Code and Codex as ACP agents, with a live tree of agents and subagents, inline permissions and diffs, an organization of agents working in their own git worktrees, an Arena where several agents solve the same task, and a searchable history of past sessions (macOS, Windows, Linux) * [Bellows](https://bellowsai.app) — desktop workspace for ACP agents with live session sharing: send someone a link to a running session and they watch, suggest or type from a browser, with suggestions held until the host accepts them; shared permission rules and a hash-linked audit trail (Windows, macOS, Linux) * [Braide](https://braide.dev) - Parallel sessions, worktrees, personas and interactive agent responses (supports macOS, Windows, Linux) * [Capsule](https://github.com/realbakari/Capsule-App) — local-first macOS desktop workspace for ACP coding agents and harnesses (Claude Code, Codex, Grok), with projects, conversations, diffs, and approvals * [Casper](https://github.com/joeyshi12/casper) - A web client for kiro-cli that talks to it over the Agent Client Protocol (ACP), giving you a browser-based chat UI with live streaming, session history, and rich per-tool-call rendering. * [Clover](https://github.com/zhangcongmr/clover) * [CallBro](https://callbro.ai) — local-first meeting-notes app that uses ACP agents for meeting chat and note generation (macOS, Windows, Linux) * [Codeg](https://github.com/xintaofei/codeg) — collaborative multi-agent coding workbench that unifies ACP agents (Claude Code, Codex, Gemini CLI, OpenCode, and more) with session aggregation; desktop app, self-hosted server, or Docker (macOS, Windows, Linux, Web) * [Coincide](https://coincide.dev) ([GitHub](https://github.com/apoorvdarshan/coincide)) — open-source (MIT) native macOS app (AppKit) that runs Cursor, Grok Build and Antigravity over ACP alongside Claude Code, Codex and OpenCode in one window, and lets a thread switch agents mid-conversation with a recap of the turns the next agent missed * [CompozyOS](https://github.com/compozy/compozy) — open-source agent OS: runs ACP agents as a team on loops and schedules, with shared memory and approvals (Web, CLI) * [Daruda](https://github.com/daruda-ai/daruda) — open-source (AGPL-3.0) native Rust/GPUI desktop app that runs Claude Code, Codex, Gemini and other ACP agents side by side, each in its own git worktree, with tool-call cards, inline permission approvals, word-level diffs, YAML flows and Ghostty terminals (macOS, Windows, Linux) * [DeepChat](https://github.com/ThinkInAIXYZ/deepchat) * [Devin Desktop](https://devin.ai/desktop) * [Eleven](https://github.com/Zfinix/eleven) — open-source reverse-engineering app where any ACP agent reads, renames and patches binaries, Android apps and GPU kernels next to you (macOS, Windows, Linux) * [fabriqa.ai](https://fabriqa.ai) * [gemini-cli-desktop](https://github.com/Piebald-AI/gemini-cli-desktop) * [Ghosty Teams](https://ghosty.studio) — multi-tenant team workspace where ACP agents work alongside chat, collaborative documents, artifacts, forms, and live calls (Web) * [Gold Band](https://github.com/diodeme/Gold-Band) — open-source, local-first ACP desktop client supporting direct agent conversations, DSL-based workflow orchestration, AI-generated dynamic workflows, and unified context management (Windows, macOS, Linux) * [Harnss](https://github.com/OpenSource03/harnss) * [Jockey](https://github.com/recailai/jockey) — open-source multi-agent orchestrator (Tauri + Rust + SolidJS) that coordinates Claude Code, Gemini CLI, and Codex CLI via ACP * [Kepler](https://www.gitkraken.com/kepler) — GitKraken’s agentic development environment (ADE) giving you full clarity and control to run parallel agents at scale * [Kronos](https://github.com/Reqeique/Kronos) — self-hosted scheduler and orchestration dashboard that runs ACP agent tasks on schedules via a bridge CLI, with Slack channel delivery and a real-time dashboard * [littleguys](https://www.littleguys.dev) ([GitHub](https://github.com/herval/littleguys)) — WhatsApp-style app for talking to your agents: each ACP agent, added in one click from the ACP Registry, is a contact with its own chats, streaming replies, tool calls and approve/deny cards for permission requests (macOS) * [Lody](https://lody.ai) * [Minion Mind](https://minion-mind.nebulame.com/) — through the [Agent Client](https://github.com/RAIT-09/obsidian-agent-client) plugin * [Mitto](https://github.com/inercia/mitto) * [Ngent](https://github.com/beyond5959/ngent) * [OctoShell](https://github.com/savvasioakeim/OctoShell) — Rust/Tauri terminal workspace that runs ACP agents in git worktrees, one per task, each with its own shell and managed dev server, plus a planning round before any code is written and a QA pass over the running app (Windows, macOS) * [Open Walnut](https://github.com/EvanZhang008/open-walnut) - open-source (MIT), self-hosted web console that runs Codex, Gemini CLI, OpenCode, Goose and other ACP agents next to Claude Code from one browser page, with every session's status and your tasks and notes alongside (Web; server on macOS or Linux) * [Orca](https://onorca.dev) ([GitHub](https://github.com/stablyai/orca)) — open-source (AGPL-3.0) multi-agent coding workbench that runs OpenCode, Antigravity, Grok, OMP, Claude Code, Codex and Gemini CLI across isolated Git worktrees, with native ACP sessions, inline permission approvals, multi-agent DAG orchestration, embedded terminals, diffs, and in-app browser (macOS, Windows, Linux) * [Outmake](https://outmake.app) - free native Mac app that runs Claude Code, Codex, Gemini CLI and OpenCode over ACP, next to open models running on the Mac itself (macOS) * [oxi](https://github.com/maziluiosif/oxi) — native Rust/egui coding-agent desktop app that drives Claude Code, Cursor and Codex over ACP alongside local GGUF models and hosted APIs, with a built-in editor, Git panel and terminal (macOS, Windows, Linux) * [Panda](https://github.com/lukaisluka/Panda) — a ready-made UI for your ACP agent: you implement the agent side, Panda ships the streaming chat, tool-call cards, inline permission prompts, diffs and session history (Web with scripted demo; macOS/Windows desktop) * [Perch](https://github.com/chenweigao/perch) — native macOS workspace for remote coding agents over SSH; drives ACP agents such as DeepSeek Harness with approval cards, stop, model and reasoning pickers, and session resume through a remote loopback broker (macOS) * [Pilion Browser](https://github.com/echoVic/pilion-browser) — desktop browser that connects any ACP agent, local or over SSH, and hands its own tabs to the agent through MCP with approvals, human takeover, and session resume (macOS, Windows, Linux) * [Poolside Desktop Assistant](https://poolside.ai/get-started) - An agent agnostic worktree native macOS desktop app. * [PrismaLens](https://github.com/prismalens/prismalens) - Open-source incident investigator that runs locally with a web UI and hands each alert to your ACP coding agent to read a snapshot of the service's code and write a ranked, evidence-backed report (Web; macOS, Linux) * [qwen-audio-agent](https://github.com/QwenAudio/qwen-audio-agent) — realtime full-duplex voice client for ACP agents, with wake word and barge-in (macOS desktop, TUI, Web) * [RayClaw](https://github.com/rayclaw/rayclaw?tab=readme-ov-file#acp-agent-client-protocol) * [Reemoat](https://github.com/rends-east/reemoat) — self-hosted remote control for any coding agent: run coding agents on your own machines and supervise them from anywhere, end-to-end encrypted * [Remote Agent Server](https://github.com/ma-pony/remote-agent-server) — self-hosted ACP agent execution gateway for external systems that runs Codex and Claude Code through an asynchronous Task API, with isolated workspaces, persistent sessions, per-agent MCP and Skills, event history, SSE, and signed Webhooks * [RLM Code](https://github.com/SuperagenticAI/rlm-code) * [Rovai AI](https://github.com/murray17/rovai-ai) — open-source desktop and web workspace for coding-agent teams, connecting ACP agents such as OpenCode with shared conversations, task handoffs, and execution inspection. * [Shellular](https://shellular.dev) ([GitHub](https://github.com/shellular-org)) * [Sidequery](https://sidequery.dev) * [Skylands](https://skylands.ai) ([GitHub](https://github.com/skylands-ai/skylands)) — One self-hosted 3D world of all your machines: run Claude Code, Codex, Goose, and other ACP agents on each, see which files every session is working on, and approve their actions with a unified rule set (Web; Linux, macOS, Windows) * [Superlite](https://superlite.dev) - blazing-fast Rust-native desktop client for ACP coding agents with parallel sessions, browser remote, and push notifications (macOS, Windows, Linux, Web) * [Tidewave](https://tidewave.ai/) * [tlbx](https://github.com/tlbx-ai/tlbx) — self-hosted browser control station for persistent ACP agent and terminal sessions on Windows, macOS, and Linux, supervised from desktop, tablet, or phone browsers * [Vibex](https://github.com/vibex-ai/vibex) — A native, local-first AI coding workbench for Agent-powered software development. Powered by GPUI and ACP. Your agents. Your workspace. Your control—from prompt to commit, desktop to mobile. Works with Codex, Claude Code, OpenCode, Pi, Grok, DeepSeek Harness, Antigravity, and many more through ACP. * [VibeAround](https://github.com/jazzenchen/VibeAround) — all-in-one hub for ACP coding agents (Claude Code, Codex CLI, Gemini CLI, Pi, OpenCode): launch with any model provider, continue the same session across desktop, CLI/TUI, web, mobile browser, and messaging apps, with local and time-scoped remote preview (macOS, Windows, Linux) * [Volant](https://usevolant.com) ([GitHub](https://github.com/mysticcoders/volant)) — open-source (MIT) macOS launcher that starts Claude Code, Codex and OpenCode conversations over ACP from one shortcut, with replies, tool status and permission choices in the launcher, alongside app search, notes and clipboard history (macOS) * [Web Browser with AI SDK](https://github.com/mcpc-tech/ai-elements-remix-template) (powered by [@mcpc/acp-ai-provider](https://github.com/mcpc-tech/mcpc/tree/main/packages/acp-ai-provider)) * [Kangaroo](https://github.com/dbkangaroo/kangaroo) — database IDE with Agent Client Protocol support * [ACP Components](https://github.com/zvzuola/acp-components) - A universal frontend component library for building AI Agent interfaces based on the ACP * [ACP Inspector](https://github.com/newioapp/acp-inspector) — desktop debugger/inspector for the ACP protocol (macOS, Linux) * [Newio](https://newio.app) — a multi-channel, multi-player agent native messaging app * [ClawX](https://github.com/ValueCell-ai/ClawX) — desktop GUI for OpenClaw agents, with a chat UI that talks to them over ACP * [OmniGet](https://github.com/tonhowtf/omniget) — desktop app for local coding agents with permissions, undo, jobs, and a built-in MCP server (Windows, macOS, Linux) * [Paca](https://github.com/Paca-AI/paca) — self-hosted, AI-native project management where humans and ACP agents share the same board and sprints * [Threadlines](https://github.com/Threadlines/threadlines) - open-source desktop app for coding agents, with a live browser, terminal, and source control beside each thread. Runs Cursor, Antigravity and fx over ACP, plus agents from the ACP registry, alongside Codex and Claude Code, and several agents can share one thread (macOS, Windows, Linux) * [Fello](https://github.com/Zythum/fello) — open-source, agent-neutral desktop AI workspace for ACP agents and OpenAI-compatible APIs, with chat, files, terminals, diffs, project memory, MCP tools, WebUI remote access, and WeChat iLink (macOS, Windows, Linux) * [Happier](https://github.com/happier-dev/happier) - open-source, end-to-end encrypted, cross-device app to orchestrate Claude Code, Codex and other ACP agents on your own machines from desktop, phone and web ## Notebook and data tools * [agent-client-kernel](https://github.com/wiki3-ai/agent-client-kernel) (Jupyter notebooks) * [Alchemy](https://github.com/thrashr888/alchemy) — local-first research notebook for macOS: run your own coding agent inside a notebook, with that notebook's sources reachable over the app's built-in MCP server * DuckDB — through the [sidequery/duckdb-acp](https://github.com/sidequery/duckdb-acp) extension * [marimo notebook](https://github.com/marimo-team/marimo) * [SpurLab](https://getspur.dev/spurlab) — Jupyter-style notebook for data exploration with DuckDB-powered SQL cells alongside Python, charts and notes, where you and your ACP-compatible coding agent work the same analysis ## Mobile clients These mobile-first tools bring ACP and related coding-agent workflows to phones and tablets: * [acpantenna](https://github.com/fboldo/acpantenna) ([latch.im](https://latch.im)) (Web) — one command connects a running Claude Code, Codex or OpenCode session to a one-time link and QR code you open on a phone or another browser; the relay forwards ciphertext it cannot read, and permission requests are answered on the device you moved to * [AgentDeck](https://github.com/mantou132/AgentDeck) (Android) — start, steer and approve ACP agents running on your own computer from your phone: a background daemon (`agentdeckd`) pairs by QR code over an end-to-end encrypted, self-hostable relay, with a built-in free agent that needs no login * [Agmente](https://agmente.halliharp.com) ([GitHub](https://github.com/rebornix/Agmente)) (iOS) * [Ferngeist](https://github.com/arafatamim/Ferngeist) (Android) * [GetPullRequest](https://www.getpullrequest.com) (Android) — picks up tasks from GitHub, GitLab, Jira, and Slack, runs them through ACP agents on your machine, and lets you monitor everything from your phone * [Happy](https://happy.engineering/) ([GitHub](https://github.com/slopus/happy)) (iOS, Android, Web) * [Mobvibe](https://github.com/Eric-Song-Nop/mobvibe) (iOS, Android, Web) * [Open Walnut](https://github.com/EvanZhang008/open-walnut) (iOS, built from source) — beta SwiftUI companion for a self-hosted Open Walnut server: follow and reply to its sessions, including ACP agents such as Codex, OpenCode and Goose; pairs by QR code over the same Wi-Fi or Tailscale * [Orca Mobile](https://onorca.dev) ([GitHub](https://github.com/stablyai/orca)) (iOS, Android) — mobile companion that pairs with a desktop Orca host to start, steer, and approve ACP and terminal agent sessions across Git worktrees * [Reemoat](https://github.com/rends-east/reemoat) — Android app for Reemoat's self-hosted daemon: follow ACP agent sessions running on your own machines and answer their permission requests and questions, over an end-to-end encrypted relay * [Runmote](https://runmote.dev) ([GitHub](https://github.com/Raza-learner/Runmote)) (Android, Linux, macOS, Windows) — Run any ACP agent on your PC from your phone via QR code or 8-digit pairing; no SSH/VPN * [Shellular](https://shellular.dev) ([GitHub](https://github.com/shellular-org)) (iOS, Android, [Web](https://app.shellular.dev)) * [TermFold](https://github.com/Bibarud/TermFold) (Android) — runs ACP agents on the device itself: a bundled Debian environment with a native chat for Claude, Codex, OpenCode, Cursor, Pi and more, with permissions, plans, model and reasoning pickers, and session resume; no PC or server needed * [VACP](https://play.google.com/store/apps/details?id=com.intellexie.vacp) (Android) — voice control for AI coding agents (OpenCode, KiloCode, and any ACP-compatible agent over TCP) ## Messaging * [ACP Discord](https://github.com/broven/acp-discord) (Discord) * [acp-connector](https://github.com/galiprandi/acp-connector) (Telegram, Discord) — thin, agent-agnostic bridge with cron jobs, routines, HTTP API, session management, and webhook callbacks * [duckdb-claude-slack](https://github.com/sidequery/duckdb-claude-slack) (Slack) * [Juan](https://github.com/DiscreteTom/juan) (Slack) * [OpenACP](https://github.com/Open-ACP/OpenACP) (Telegram, Discord, Slack) — self-hosted bridge for ACP agents; streams tool calls and responses in real time * [Telegram ACP Bot](https://github.com/mgaitan/telegram-acp-bot) (Telegram) — through the [`telegram-acp-bot`](https://github.com/mgaitan/telegram-acp-bot) connector * [Telegram-ACP](https://github.com/SuperKenVery/Telegram-ACP/) (Telegram) — Supports multi-thread chat and message streaming * [ACP Router](https://github.com/vcoderun/acprouter) (Telegram) - an ACP client surface for driving ACP agents from Telegram, with rich diffs, approvals and many more. * [WeChat ACP](https://github.com/formulahendry/wechat-acp) (WeChat) * [qq-ai-bot](https://github.com/happysnaker/qq-ai-bot) (QQ / OneBot 11) — self-hosted bridge for OneBot 11 / NapCat / LLOneBot that connects QQ messaging to ACP-compatible agents with persistent sessions and progress streaming * [Sniptail](https://github.com/Justkog/sniptail) (Discord, Slack) - self-hosted chat bridge for running coding agents across your team’s repositories * [Lark ACP](https://github.com/4t145/lark-acp) (Lark/飞书) * [Zooid](https://github.com/zooid-ai/zooid) (Matrix) - coding agent runtime paired with a Matrix client/ACP bridge for interacting with agents * [Pomerium AgentOps](https://github.com/pomerium/agentops) (Slack) * [VibeAround](https://github.com/jazzenchen/VibeAround) (Telegram, Feishu/Lark, Discord, Slack, WeChat, WhatsApp, DingTalk, WeCom, QQ) — continue desktop/CLI agent sessions from messaging apps through channel plugins * [cc-connect](https://github.com/chenhg5/cc-connect) (Feishu/Lark, DingTalk, Slack, Telegram, Discord, LINE, WeCom) — bridges local coding agents to messaging platforms * [Gonggong Space](https://github.com/yoqu/gonggong-space) (self-hosted web chat, Feishu/Lark) — group chat where teammates @ each other's Claude Code / Codex agents running on their own machines, with live process, diffs, owner approvals and in-chat previews of the apps they start * [acpantenna](https://github.com/fboldo/acpantenna) (Matrix, Discord, Telegram, IRC, webhooks) — the same session driven from a chat platform through channel plugins, with permission requests answered in the chat ## Frameworks These frameworks add ACP support through dedicated integrations or adapters: * [AgentPool](https://phil65.github.io/agentpool/) — with built-in ACP integration for IDEs and external ACP agents * [fast-agent](https://fast-agent.ai/acp/) — through [`fast-agent-acp`](https://fast-agent.ai/acp/) * [ACP Kit](https://github.com/vcoderun/acpkit/) - adapter toolkit for exposing existing [Pydantic AI](https://pypi.org/project/pydantic-acp/) / [LangChain](https://pypi.org/project/langchain-acp/) agent runtimes through ACP. * [Koog](https://docs.koog.ai/agent-client-protocol/) — through the [`agents-features-acp`](https://github.com/JetBrains/koog/tree/develop/examples/notebooks/acp) integration * [LangChain / LangGraph](https://docs.langchain.com/oss/python/deepagents/acp) — through [Deep Agents ACP](https://docs.langchain.com/oss/python/deepagents/acp) * [LlamaIndex](https://github.com/AstraBert/workflows-acp) — through the [`workflows-acp`](https://github.com/AstraBert/workflows-acp) adapter for Agent Workflows * [LLMling-Agent](https://github.com/phil65/llmling-agent) — with built-in ACP support for running agents through ACP clients * [Mastra](https://mastra.ai/docs/agents/acp) — through the [`@mastra/acp`](https://mastra.ai/docs/agents/acp) package for wrapping external ACP agents as tools or subagents * [AgentOS](https://github.com/rivet-dev/agentos) — with built-in ACP agents, and sessions created, managed, and resumed over ACP ## Connectors These connectors bridge ACP into other environments and transport layers: * [acp\_rpc\_bridge](https://github.com/Intellexie/acp_rpc_bridge) — terminal binary that bridges stdio-based agents to HTTP, giving non-network agents network capability; supports ACP and Pi RPC protocols with ACP Streamable HTTP and OpenCode REST API endpoints * [ACP to AG-UI](https://github.com/namanrajpal/acp-to-agui) — bridges any ACP agent to web frontends via [AG-UI](https://docs.ag-ui.com) events over SSE; works with CopilotKit, AG-UI HttpAgent, or custom UIs (Web) * [AgentRQ](https://github.com/agentrq/acp-gateway) — bridges stdio-based ACP agents to the AgentRQ - Human-in-the-loop task collaboration service using MCP server. * [AHP-ACP Gateway](https://github.com/formulahendry/ahp-acp-gateway) — bridges AHP clients to configured ACP agents through a persistent WebSocket host, with model and configuration mapping, replay and reconnect, permission handling, and cross-platform lazy agent startup * [Aptove Bridge](https://github.com/aptove/bridge) — bridges stdio-based ACP agents to the Aptove mobile client over WebSocket * [ACP Remote](https://github.com/vcoderun/acpkit/tree/main/packages/transports/acpremote) - remote WebSocket transport for ACP agents and clients. * [OpenClaw](https://docs.openclaw.ai/cli/acp) — through the [`openclaw acp`](https://docs.openclaw.ai/cli/acp) bridge to an OpenClaw Gateway * [stdio Bus](https://stdiobus.com) – deterministic stdio-based kernel providing transport-level routing for ACP/MCP-style agent protocols. * [acpdbg](https://github.com/phimage/acpdbg) — bridges LLDB crashes (C/C++/Rust/Swift) to any ACP coding agent for root-cause analysis and live debugging * [Octop](https://github.com/TencentCloud/Octop) — self-hosted multi-user AI assistant with bidirectional ACP support for IDE and terminal agents * [a2acode](https://github.com/kanywst/a2acode) — serves any ACP agent over the [A2A](https://a2aprotocol.ai/) protocol so other agents can delegate coding work to it, carrying tool calls, diffs, plans and cost across, and turning `session/request_permission` into an A2A `input-required` pause the remote caller answers * [Remote ACP Bridge](https://github.com/brstic/remote-acp) — desktop app (Tauri, Rust) that lets websites you approve send tasks to your local ACP agents such as Codex and Claude Code over an outbound-only relay, with per-site consent, local permission prompts and a project-folder firewall; includes a TypeScript SDK for websites # Introduction Source: https://agentclientprotocol.com/get-started/introduction Get started with the Agent Client Protocol. The Agent Client Protocol (ACP) standardizes communication between code editors/IDEs and coding agents and is suitable for both local and remote scenarios. ## Why ACP? AI coding agents and editors are tightly coupled but interoperability isn't the default. Each editor must build custom integrations for every agent they want to support, and agents must implement editor-specific APIs to reach users. This creates several problems: * Integration overhead: Every new agent-editor combination requires custom work * Limited compatibility: Agents work with only a subset of available editors * Developer lock-in: Choosing an agent often means accepting their available interfaces ACP solves this by providing a standardized protocol for agent-editor communication, similar to how the [Language Server Protocol (LSP)](https://microsoft.github.io/language-server-protocol/) standardized language server integration. Agents that implement ACP work with any compatible editor. Editors that support ACP gain access to the entire ecosystem of ACP-compatible agents. This decoupling allows both sides to innovate independently while giving developers the freedom to choose the best tools for their workflow. ## Overview ACP assumes that the user is primarily in their editor, and wants to reach out and use agents to assist them with specific tasks. ACP is suitable for both local and remote scenarios: * **Local agents** run as sub-processes of the code editor, communicating via JSON-RPC over stdio. * **Remote agents** can be hosted in the cloud or on separate infrastructure, communicating over HTTP or WebSocket > [!NOTE] > > Full support for remote agents is a work in progress. We are actively > collaborating with agentic platforms to ensure the protocol addresses the > specific requirements of cloud-hosted and remote deployment scenarios. The protocol re-uses the JSON representations used in MCP where possible, but includes custom types for useful agentic coding UX elements, like displaying diffs. The default format for user-readable text is Markdown, which allows enough flexibility to represent rich formatting without requiring that the code editor is capable of rendering HTML. # ACP Registry Source: https://agentclientprotocol.com/get-started/registry The easiest way to find and install ACP-compatible agents. ## Overview The ACP Registry is an easy way for developers to distribute their ACP-compatible agents to any client that speaks the protocol. This is a curated set of agents, including only the ones that [support authentication](/protocol/v1/authentication). Visit [the registry repository on GitHub](https://github.com/agentclientprotocol/registry) to learn more about it. ## Available Agents > [card] [Agoragentic](https://agoragentic.com) > > Agent marketplace with 174+ AI capabilities. Browse, invoke, and pay for agent services settled in USDC on Base L2. > > [https://github.com/rhein1/agoragentic-integrations](https://github.com/rhein1/agoragentic-integrations) > [card] [Amp](https://github.com/tao12345666333/amp-acp) > > ACP wrapper for Amp - the frontier coding agent > > [https://github.com/tao12345666333/amp-acp](https://github.com/tao12345666333/amp-acp) > [card] [Auggie CLI](https://www.augmentcode.com/) > > Augment Code's powerful software agent, backed by industry-leading context engine > > [https://github.com/augmentcode/auggie](https://github.com/augmentcode/auggie) > [card] [Autohand Code](https://github.com/autohandai/code-cli/blob/main/docs/guides/ACP.md) > > Autohand Code CLI with native ACP support > > [https://github.com/autohandai/code-cli](https://github.com/autohandai/code-cli) > [card] [Bob](https://bob.ibm.com) > > IBM Bob is your AI-Powered Development Partner > [card] [Claude Agent](https://github.com/agentclientprotocol/claude-agent-acp) > > ACP wrapper for Anthropic's Claude > > [https://github.com/agentclientprotocol/claude-agent-acp](https://github.com/agentclientprotocol/claude-agent-acp) > [card] [Cline](https://cline.bot/cli) > > Autonomous coding agent CLI - capable of creating/editing files, running commands, using the browser, and more > > [https://github.com/cline/cline](https://github.com/cline/cline) > [card] [Codebuddy Code](https://www.codebuddy.cn/cli/) > > Tencent Cloud's official intelligent coding tool > [card] [Codex](https://github.com/agentclientprotocol/codex-acp) > > ACP adapter for OpenAI's coding assistant > > [https://github.com/agentclientprotocol/codex-acp](https://github.com/agentclientprotocol/codex-acp) > [card] [Cortex Code](https://docs.snowflake.com/en/user-guide/cortex-code/cortex-code) > > Snowflake's Cortex Code coding agent > > [https://docs.snowflake.com/en/user-guide/cortex-code/cortex-code](https://docs.snowflake.com/en/user-guide/cortex-code/cortex-code) > [card] [Corust Agent](https://corust.ai/) > > Co-building with a seasoned Rust partner. > > [https://github.com/Corust-ai/corust-agent-release](https://github.com/Corust-ai/corust-agent-release) > [card] [crow-cli](https://crow-ai.dev) > > Minimal ACP Native Coding Agent > > [https://github.com/crow-cli/crow-cli](https://github.com/crow-cli/crow-cli) > [card] [Cursor](https://cursor.com/docs/cli/acp) > > Cursor's coding agent > [card] [DeepAgents](https://docs.langchain.com/oss/javascript/deepagents/overview) > > Batteries-included AI coding and general purpose agent powered by LangChain. > > [https://github.com/langchain-ai/deepagentsjs](https://github.com/langchain-ai/deepagentsjs) > [card] [Devin](https://docs.devin.ai/cli) > > Devin CLI coding agent by Cognition > > [https://github.com/CognitionAI/devin-cli](https://github.com/CognitionAI/devin-cli) > [card] [DimCode](https://dimagent.cn/) > > A coding agent that puts leading models at your command. > [card] [Dirac](https://dirac.run) > > Reduces API costs by more than 50%, produces better and faster work. Uses Hash anchored parallel edits, AST manipulation and a whole lot of neat optimizations. Fully Open Source. > > [https://github.com/dirac-run/dirac](https://github.com/dirac-run/dirac) > [card] [Factory Droid](https://factory.ai/product/cli) > > Factory Droid - AI coding agent powered by Factory AI > [card] [fast-agent](https://fast-agent.ai) > > Code and build agents with comprehensive multi-provider support > > [https://github.com/evalstate/fast-agent](https://github.com/evalstate/fast-agent) > [card] [Gemini CLI](https://geminicli.com) > > Google's official CLI for Gemini > > [https://github.com/google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli) > [card] [GitHub Copilot](https://github.com/features/copilot/cli/) > > GitHub's AI pair programmer > > [https://github.com/github/copilot-cli](https://github.com/github/copilot-cli) > [card] [GLM Agent](https://github.com/stefandevo/glm-acp-agent) > > ACP agent powered by Zhipu AI's GLM Coding Plan models (glm-5.1, glm-5-turbo, glm-4.7, glm-4.5-air). Supports streaming, tool calls, mid-session model switching, image input via Z.AI Coding Plan Vision MCP, and session load/fork/resume with on-disk persistence. > > [https://github.com/stefandevo/glm-acp-agent](https://github.com/stefandevo/glm-acp-agent) > [card] [Google Antigravity](https://antigravity.google/docs/ide/extensions) > > Google’s AI coding agent > [card] [goose](https://block.github.io/goose/) > > A local, extensible, open source AI agent that automates engineering tasks > > [https://github.com/block/goose](https://github.com/block/goose) > [card] [Grok Build](https://x.ai/cli) > > xAI's coding agent and CLI > [card] [Harn](https://harnlang.com) > > Harn runs .harn agent pipelines as a native ACP coding agent over stdio. > > [https://github.com/burin-labs/harn](https://github.com/burin-labs/harn) > [card] [Junie](https://junie.jetbrains.com) > > AI Coding Agent by JetBrains > > [https://github.com/JetBrains/junie-acp-release](https://github.com/JetBrains/junie-acp-release) > [card] [Kilo](https://kilo.ai/) > > The open source coding agent > > [https://github.com/Kilo-Org/kilocode](https://github.com/Kilo-Org/kilocode) > [card] [Kimchi](https://kimchi.dev) > > Coding agent powered by multi-model orchestration > > [https://github.com/getkimchi/kimchi](https://github.com/getkimchi/kimchi) > [card] [Kimi CLI (Legacy)](https://moonshotai.github.io/kimi-cli/) > > Archived by Moonshot AI. Use Kimi Code instead > > [https://github.com/MoonshotAI/kimi-cli](https://github.com/MoonshotAI/kimi-cli) > [card] [Kimi Code](https://moonshotai.github.io/kimi-code/) > > Moonshot AI's next-gen coding agent > > [https://github.com/MoonshotAI/kimi-code](https://github.com/MoonshotAI/kimi-code) > [card] [Kiro CLI](https://kiro.dev/docs/cli/acp/) > > The Kiro coding agent > > [https://github.com/kirodotdev/Kiro](https://github.com/kirodotdev/Kiro) > [card] [MiniMax Code](https://agent.minimax.io) > > MiniMax Code is an AI coding agent with Agent Client Protocol support. > [card] [Minion Code](https://github.com/femto/minion-code) > > An enhanced AI code assistant built on the Minion framework with rich development tools > > [https://github.com/femto/minion-code](https://github.com/femto/minion-code) > [card] [Mistral Vibe](https://mistral.ai/products/vibe) > > Mistral's open-source coding assistant > > [https://github.com/mistralai/mistral-vibe](https://github.com/mistralai/mistral-vibe) > [card] [Nova](https://www.compassap.ai/portfolio/nova.html) > > Nova by Compass AI - a fully-fledged software engineer at your command > > [https://github.com/Compass-Agentic-Platform/nova](https://github.com/Compass-Agentic-Platform/nova) > [card] [OpenCode](https://opencode.ai) > > The open source coding agent > > [https://github.com/anomalyco/opencode](https://github.com/anomalyco/opencode) > [card] [OpenCode V2](https://opencode.ai) > > The open source coding agent, version 2 > > [https://github.com/anomalyco/opencode](https://github.com/anomalyco/opencode) > [card] [pi ACP](https://github.com/svkozak/pi-acp) > > ACP adapter for pi coding agent > > [https://github.com/svkozak/pi-acp](https://github.com/svkozak/pi-acp) > [card] [Poolside](https://poolside.ai) > > Poolside's coding agent > > [https://github.com/poolsideai/pool](https://github.com/poolsideai/pool) > [card] [Qoder CLI](https://qoder.com) > > AI coding assistant with agentic capabilities > [card] [Qwen Code](https://qwenlm.github.io/qwen-code-docs/en/users/overview) > > Alibaba's Qwen coding assistant > > [https://github.com/QwenLM/qwen-code](https://github.com/QwenLM/qwen-code) > [card] [siGit Code](https://github.com/getsigit/sigit) > > Local-first coding agent. Runs entirely on your machine with optional on-device LLM inference via Onde. > > [https://github.com/getsigit/sigit](https://github.com/getsigit/sigit) > [card] [Stakpak](https://stakpak.dev) > > Open-source DevOps agent in Rust with enterprise-grade security > > [https://github.com/stakpak/agent](https://github.com/stakpak/agent) > [card] [VT Code](https://github.com/vinhnx/VTCode/blob/main/docs/guides/zed-acp.md) > > An open-source coding agent with LLM-native code understanding and robust shell safety. Supports multiple LLM providers with automatic failover and efficient context management. > > [https://github.com/vinhnx/VTCode](https://github.com/vinhnx/VTCode) ## Using the Registry Clients can fetch the registry programmatically: ```bash theme={null} curl https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json ``` The registry JSON contains all agent metadata including distribution information for automatic installation. ## Submit your Agent To add your agent to the registry: 1. Fork the [registry repository on GitHub](https://github.com/agentclientprotocol/registry) 2. Create a folder with your agent's ID (lowercase, hyphens allowed) 3. Add an `agent.json` file following [the schema](https://github.com/agentclientprotocol/registry/blob/main/agent.schema.json) 4. Optionally add an `icon.svg` (16x16 recommended) 5. Submit a pull request See the [contributing guide](https://github.com/agentclientprotocol/registry/blob/main/CONTRIBUTING.md) for details. # ACP and other protocols Source: https://agentclientprotocol.com/get-started/related-protocols How the Agent Client Protocol relates to MCP, A2A, the Agent Communication Protocol, and LSP. The Agent Client Protocol (ACP) defines how a Client, such as a code editor or another agent, talks to an AI coding Agent. Several other protocols cover nearby problems or share the acronym. This page explains where each one fits. | Protocol | Purpose | Relationship to ACP | | - | - | - | | Agent Client Protocol (ACP) | Drive an Agent through interactive sessions | This protocol | | [Model Context Protocol](#model-context-protocol) | Give an Agent tools and data | Used together with ACP | | [Agent2Agent](#agent2agent) | Delegate tasks to independent agents | Different interaction model | | [Agent Communication Protocol](#agent-communication-protocol) | Messaging between agents | Unrelated project with the same acronym | | [Language Server Protocol](#language-server-protocol) | Language features in editors | The model ACP is based on | ## Model Context Protocol The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) connects an Agent to tools, resources, and prompts. ACP connects a Client to that Agent. You don't choose between them. Most ACP Agents are also MCP clients. The two protocols meet in a few places: * The Client passes the user's configured MCP servers to the Agent in [`session/new`](/protocol/v1/session-setup#mcp-servers), and the Agent connects to them directly. * A Client that wants to provide its own tools can expose them as an MCP server and include it in that list. See [Architecture](/get-started/architecture#mcp). * ACP reuses MCP's JSON representations where possible, such as content blocks. It adds its own types for coding UX, such as diffs, plans, and permission requests. The [MCP-over-ACP RFD](/rfds/mcp-over-acp) proposes carrying MCP requests over the existing ACP connection, so a Client doesn't need a separate MCP server process. ## Agent2Agent [Agent2Agent](https://a2a-protocol.org) (A2A) is a Linux Foundation project for delegating tasks to independent agents. An A2A agent publishes an Agent Card that describes its skills and endpoint. Other agents send it tasks, and it works on them on its own and returns results and artifacts. ACP defines the interactive session between a Client and an Agent. The Client sends prompts, renders streamed updates and tool calls, answers permission requests, and can give the Agent access to its files and terminals. The Client doesn't have to be an editor. An agent can act as an ACP Client to run other coding agents as sub-agents. Use ACP when a program drives an Agent and stays involved during each turn. Use A2A when an agent hands a task to another agent, often one run by a different party, and that agent handles it on its own. ## Agent Communication Protocol The [Agent Communication Protocol](https://github.com/i-am-bee/acp), from IBM's BeeAI project, also used the name "ACP". It is a separate protocol for messaging between agents, applications, and humans, and it is not related to the Agent Client Protocol. That project has merged into A2A under the Linux Foundation, and its repository was archived in August 2025. Articles that mention "ACP" together with agent-to-agent messaging, BeeAI, or IBM usually mean the Agent Communication Protocol. ## Language Server Protocol The [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) lets any editor use any language server. ACP applies the same idea to coding agents: any Client can use any Agent that implements ACP. ACP follows LSP's structure. Both use JSON-RPC 2.0, the editor usually starts the server as a subprocess and talks to it over stdio, and both sides negotiate capabilities during initialization. ACP defines its own methods because the work is different. A language server answers questions about documents. An Agent runs [prompt turns](/protocol/v1/prompt-turn) that stream updates, report [tool calls](/protocol/v1/tool-calls), and ask the Client for [permission](/protocol/v1/tool-calls#requesting-permission) before acting. # Community Source: https://agentclientprotocol.com/libraries/community Community managed libraries for the Agent Client Protocol ## Cangjie * [acp-cj](https://atomgit.com/ystyle/acp-cj) ## C++ * [acp-cpp](https://github.com/dunkbing/acp-cpp) ## Crystal * [acp.cr](https://github.com/hahwul/acp.cr) ## Dart * [acp\_dart](https://github.com/SkrOYC/acp-dart) ## .NET * [acp-csharp](https://github.com/nuskey8/acp-csharp) * [Acp.Net](https://github.com/MertBasar0/acp-net) * [Agentic.ACPLibrary](https://github.com/AgenticDesktop/ACPLibrary) ## Elixir * [raxol\_agent\_client\_protocol](https://github.com/DROOdotFOO/raxol/tree/master/packages/raxol_agent_client_protocol) ## Emacs * [acp.el](https://github.com/xenodium/acp.el) ## Go * [acp-go-sdk](https://github.com/coder/acp-go-sdk) * [acp-go](https://github.com/ironpark/acp-go) * [acp](https://github.com/eino-contrib/acp) * [acp-sdk](https://github.com/spachava753/acp-sdk) * [acp](https://github.com/Tangerg/acp) * [acp-go-sdk](https://github.com/caelis-labs/acp-go-sdk) * [acp-go](https://github.com/BrokkAi/acp-go) ## React * [use-acp](https://github.com/marimo-team/use-acp) ## Ruby * [acp-sdk](https://github.com/bottrall/acp-sdk) ## TypeScript * [acp-ts-sdk](https://github.com/langwatch/acp-ts-sdk) ## Swift * [swift-acp](https://github.com/wiedymi/swift-acp) * [swift-sdk](https://github.com/aptove/swift-sdk) * [acp-swift-sdk](https://github.com/rebornix/acp-swift-sdk) ## Vala * [Agent Client Protocol Vala SDK](https://gitcode.com/ai-outputs/AgentClientProtocol) # Java Source: https://agentclientprotocol.com/libraries/java Java library for the Agent Client Protocol The [java-sdk](https://github.com/agentclientprotocol/java-sdk) provides Java models, JSON-RPC plumbing, and side-specific connection helpers for building ACP-compatible agents and clients. The repository includes runnable examples for client and agent implementations, plus Spring AI integrations, under [`examples/`](https://github.com/agentclientprotocol/java-sdk/tree/main/examples). For dependency setup and API details, see the repository README and published Javadocs from the project. # Kotlin Source: https://agentclientprotocol.com/libraries/kotlin Kotlin library for the Agent Client Protocol The [kotlin-sdk](https://github.com/agentclientprotocol/kotlin-sdk) provides implementations of both sides of the Agent Client Protocol that you can use to build your own agent server or client. **It currently supports JVM, other targets are in progress.** To get started, add the repository to your build file: ```kotlin theme={null} repositories { mavenCentral() } ``` Add the dependency: ```kotlin theme={null} dependencies { implementation("com.agentclientprotocol:acp:0.1.0-SNAPSHOT") } ``` The [sample](https://github.com/agentclientprotocol/kotlin-sdk/tree/master/samples/kotlin-acp-client-sample) demonstrates how to implement both sides of the protocol. # Python Source: https://agentclientprotocol.com/libraries/python Python library for the Agent Client Protocol The [agentclientprotocol/python-sdk](https://github.com/agentclientprotocol/python-sdk) repository packages Pydantic models, async base classes, and JSON-RPC plumbing so you can build ACP-compatible agents and clients in Python. It mirrors the official ACP schema and ships helper utilities for both sides of the protocol. To get started, add the SDK to your project: ```bash theme={null} pip install agent-client-protocol ``` (Using [uv](https://github.com/astral-sh/uv)? Run `uv add agent-client-protocol`.) The repository includes runnable examples for agents, clients, Gemini CLI bridges, and dual-agent/client demos under [`examples/`](https://github.com/agentclientprotocol/python-sdk/tree/main/examples). Browse the full documentation—including the quickstart, contrib helpers, and API reference—at [agentclientprotocol.github.io/python-sdk](https://agentclientprotocol.github.io/python-sdk/). # Rust Source: https://agentclientprotocol.com/libraries/rust Rust library for the Agent Client Protocol The [agent-client-protocol](https://crates.io/crates/agent-client-protocol) Rust crate provides implementations of both sides of the Agent Client Protocol that you can use to build your own agent server or client. To get started, add the crate as a dependency to your project's `Cargo.toml`: ```bash theme={null} cargo add agent-client-protocol ``` Depending on what kind of tool you're building, you'll need to implement either the [Agent](https://docs.rs/agent-client-protocol/latest/agent_client_protocol/trait.Agent.html) trait or the [Client](https://docs.rs/agent-client-protocol/latest/agent_client_protocol/trait.Client.html) trait to define the interaction with the ACP counterpart. The [agent](https://github.com/agentclientprotocol/rust-sdk/blob/main/src/agent-client-protocol/examples/agent.rs) and [client](https://github.com/agentclientprotocol/rust-sdk/blob/main/src/agent-client-protocol/examples/client.rs) example binaries provide runnable examples of how to do this, which you can use as a starting point. You can read the full documentation for the `agent-client-protocol` crate on [docs.rs](https://docs.rs/agent-client-protocol/latest/agent_client_protocol/). ## Users The `agent-client-protocol` crate powers the integration with external agents in the [Zed](https://zed.dev) editor. # Testing Source: https://agentclientprotocol.com/libraries/testing Check an agent implementation against the Agent Client Protocol The [agentclientprotocol/acp-tck](https://github.com/agentclientprotocol/acp-tck) repository provides a Test Compatibility Kit (TCK) for ACP agents. It launches your agent as a stdio subprocess, drives it through the protocol (initialization, session lifecycle, prompt turns, cancellation, error handling, and transport hygiene), and reports which requirements pass, fail, don't apply, or were never exercised. > [!WARNING] > > The TCK is experimental and does not cover the full protocol. Its > requirements, options, and report format may change, and a passing run is not > an official statement of ACP conformance. Each requirement is reported with its spec citation and a tier: mandatory behavior, behavior that applies only to capabilities the agent advertises, recommended behavior, and informational probes. See the [README](https://github.com/agentclientprotocol/acp-tck#readme) for all options, the exact list of covered requirements, and how verdicts are computed. # TypeScript Source: https://agentclientprotocol.com/libraries/typescript TypeScript library for the Agent Client Protocol The [@agentclientprotocol/sdk](https://www.npmjs.com/package/@agentclientprotocol/sdk) npm package provides implementations of both sides of the Agent Client Protocol that you can use to build your own agent server or client. To get started, add the package as a dependency to your project: ```bash theme={null} npm install @agentclientprotocol/sdk ``` Depending on what kind of tool you're building, you'll start with either the [`agent()`](https://agentclientprotocol.github.io/typescript-sdk/functions/agent.html) or [`client()`](https://agentclientprotocol.github.io/typescript-sdk/functions/client.html) function to register typed handlers for the ACP methods you support and connect to your counterpart. The [examples directory](https://github.com/agentclientprotocol/typescript-sdk/tree/main/src/examples) contains runnable implementations of both sides that can be driven from your terminal or from an ACP Client like [Zed](https://zed.dev), making them great starting points for your own integration! Browse the [TypeScript library reference](https://agentclientprotocol.github.io/typescript-sdk) for detailed API documentation. ## Deprecated classes Earlier versions of the library were built around the [AgentSideConnection](https://agentclientprotocol.github.io/typescript-sdk/classes/AgentSideConnection.html) and [ClientSideConnection](https://agentclientprotocol.github.io/typescript-sdk/classes/ClientSideConnection.html) classes. These classes are now deprecated in favor of the fluent `agent()` and `client()` APIs. They remain available for backwards compatibility, but new integrations should use the fluent API as shown in the [examples](https://github.com/agentclientprotocol/typescript-sdk/tree/main/src/examples). ## Users For a complete, production-ready implementation of an ACP agent, check out [Gemini CLI](https://github.com/google-gemini/gemini-cli/tree/main/packages/cli/src/acp). # Agent Plan Source: https://agentclientprotocol.com/protocol/v1/agent-plan How Agents communicate their execution plans A plan is the Agent's list of steps for a multi-step task. Each entry has a description, a priority, and a status. Agents may send plans to Clients through [`session/update`](/protocol/v1/prompt-turn#3-agent-reports-output) notifications and update them as work progresses. ## Creating plans When the language model creates an execution plan, the Agent **SHOULD** report it to the Client: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "plan", "entries": [ { "content": "Analyze the existing codebase structure", "priority": "high", "status": "pending" }, { "content": "Identify components that need refactoring", "priority": "high", "status": "pending" }, { "content": "Create unit tests for critical functions", "priority": "medium", "status": "pending" } ] } } } ``` **entries** `PlanEntry[]` *required* An array of [plan entries](#plan-entries) representing the tasks to be accomplished ## Plan entries Each plan entry represents a specific task or goal within the overall execution strategy: **content** `string` *required* A human-readable description of what this task aims to accomplish **priority** `PlanEntryPriority` *required* The relative importance of this task. * `high` * `medium` * `low` **status** `PlanEntryStatus` *required* The current execution status of this task * `pending` * `in_progress` * `completed` ## Updating plans As the Agent progresses through the plan, it **SHOULD** report updates by sending more `session/update` notifications with the same structure. The Agent **MUST** send a complete list of all plan entries in each update and their current status. The Client **MUST** replace the current plan completely. ### Dynamic planning Plans can change during execution. The Agent **MAY** add, remove, or modify plan entries as it discovers new requirements or completes tasks. # Authentication Source: https://agentclientprotocol.com/protocol/v1/authentication Authenticating with agents and logging out ACP authentication is negotiated during [initialization](/protocol/v1/initialization). Agents advertise available authentication methods in `authMethods`. Each authentication method type defines the flow a Client uses. Agents that support ending an authenticated state advertise the `logout` capability. ```mermaid theme={null} sequenceDiagram participant Client participant Agent participant Login as Interactive login process Client->>Agent: initialize Agent-->>Client: initialize response (authMethods, auth.logout) alt Agent handles login Client->>Agent: authenticate (methodId) Agent-->>Client: authenticate response else Terminal authentication Client->>Login: launch configured Agent program Login-->>Client: login succeeds Client->>Agent: reconnect and initialize end Note over Client,Agent: Authenticated requests may proceed alt User logs out Client->>Agent: logout Agent-->>Client: logout response end Note over Client,Agent: New sessions require authentication again ``` ## Advertising authentication Agents advertise authentication options in the `authMethods` field of the `initialize` response. Every method has an `id`, but the Client sends that ID to `authenticate` only for a method whose type defines that protocol-driven flow. Agents that support `logout` also advertise `agentCapabilities.auth.logout`: ```json highlight={7-11,12-18} theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "auth": { "logout": {} } }, "authMethods": [ { "id": "agent-login", "name": "Agent login", "description": "Sign in using the agent's login flow" } ] } } ``` If `agentCapabilities.auth.logout` is omitted or `null`, the Agent does not support `logout` and Clients **MUST NOT** call it. Supplying `{}` means the Agent supports the method. ### Authentication method types The default authentication method type is `agent`, where the Agent handles authentication itself. When no `type` is present, the method is treated as `agent`: ```json theme={null} { "id": "agent-login", "name": "Agent login", "description": "Sign in using the agent's login flow" } ``` The `terminal` type tells the Client to run the configured Agent program interactively: ```json theme={null} { "id": "terminal-login", "name": "Log in from the terminal", "type": "terminal", "args": ["--login"], "env": { "ACP_INTERACTIVE_LOGIN": "1" } } ``` Terminal methods require Client support. Clients advertise this during initialization with `clientCapabilities.auth.terminal`: ```json highlight={7-9} theme={null} { "jsonrpc": "2.0", "id": 0, "method": "initialize", "params": { "protocolVersion": 1, "clientCapabilities": { "auth": { "terminal": true } } } } ``` A Client advertises this capability only when it can reproduce the configured Agent invocation in an interactive terminal. An Agent may advertise a `terminal` method only when this capability is `true`. See the [schema](/protocol/v1/schema#authmethod) for the full `AuthMethod` definitions and the [Terminal Authentication RFD](/rfds/auth-methods) for the design. ## Protocol-driven authentication When an Agent requires authentication and the selected method uses the protocol-driven flow, the Client calls `authenticate` with the advertised authentication method ID: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "authenticate", "params": { "methodId": "agent-login" } } ``` **methodId** `string` *required* The ID of an advertised authentication method whose type defines the `authenticate` flow. Clients **MUST NOT** pass a `terminal` method. On success, the Agent returns an empty result: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": {} } ``` After successful authentication, the Client can create new sessions without receiving an `auth_required` error for authentication-gated requests. ## Terminal authentication For a `terminal` method, the Client: 1. Launches a separate interactive process using the same configured Agent program and base launch configuration as the ACP connection. 2. Appends the method's `args` and applies its `env`, overriding any same-named variables in the base launch configuration. 3. 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, reconnects and reinitializes the ACP Agent. The descriptor cannot provide a command. The Client derives the command from its own Agent configuration. Agents **SHOULD** provide arguments that enter a login-only flow and exit when it completes. ACP does not define an output pattern or other in-band success signal. Clients may recognize implementation-specific signals only as an extension. The terminal process is not the ACP connection, so the Client **MUST NOT** send an `authenticate` request for a terminal method. ### Launch safety * Clients **SHOULD** pass `args` as separate arguments rather than building a shell command line from them, and **SHOULD NOT** offer terminal authentication when the launch target re-parses arguments, such as a remote shell or a Windows batch file. * Clients **SHOULD NOT** apply `env` entries that change program lookup, dynamic loading, interpreter or shell startup, or proxy and TLS trust without user approval. Examples include `PATH`, `LD_*`, `DYLD_*`, `NODE_OPTIONS`, `PYTHONPATH`, `BASH_ENV`, `HTTPS_PROXY`, and `SSL_CERT_FILE`. * Clients **SHOULD** show the appended `args` and `env` before launch. `env` values **SHOULD NOT** contain secrets. ## Logging out The `logout` method allows Clients to end the current authenticated state. Clients should only call it after verifying the Agent advertised `agentCapabilities.auth.logout` during initialization. ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "logout", "params": {} } ``` On success, the Agent returns an empty result: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "result": {} } ``` After a successful `logout`, new sessions that require authentication will require the user to complete one of the advertised authentication flows again. ## Active sessions The protocol does not guarantee what happens to already-running sessions after `logout`. Agents may terminate them, keep them running, or return `auth_required` errors for future session activity. Clients **SHOULD** be prepared for active session operations to fail with authentication-related errors after logout and should prompt the user to authenticate again when appropriate. # Cancellation Source: https://agentclientprotocol.com/protocol/v1/cancellation Mechanisms for request cancellation ACP uses JSON-RPC 2.0 for making requests and getting responses. The JSON-RPC specification doesn't define any standard mechanism for request cancellation and keeps it up to the implementation. ## `$/cancel_request` notification To make cancellation consistent, ACP defines a `$/cancel_request` notification that can be sent to cancel requests. Cancellation remains optional as it might not be implementable in all clients or servers. For example if the implementation uses a single threaded synchronous programming language then there is little it can do to react to a `$/cancel_request` notification. When a `$/cancel_request` notification is received by a supporting implementation, the implementation: * **MAY** cancel the corresponding request activity and all nested activities related to that request * **MAY** finish sending any pending notifications before responding * **MUST** send one of these responses for the original request: * A valid response with appropriate data, such as `session/prompt` with the `cancelled` stop reason or `session/request_permission` with the `cancelled` outcome * An error response with code [`-32800` (Request Cancelled)](/protocol/v1/schema#errorcode) The calling side **MAY** implement graceful cancellation processing by waiting for the response from the remote side. Cancellation **MAY** also be done explicitly on a per-feature basis within the protocol to cover specific scenarios, such as cancellation of a [prompt turn](/protocol/v1/prompt-turn#cancellation). ## Internal cancellation Requests can also be cancelled internally by the executing party without receiving `$/cancel_request`: * On the Client, the user closes the IDE or switches projects, or a file becomes unavailable. * On the Agent, the LLM context limit is reached, an internal timeout fires, or resources run out. When internal cancellation occurs, the executing party **SHOULD**: * Send the same `-32800` (Cancelled) error response as if `$/cancel_request` was received * Ensure consistent behavior regardless of cancellation source ## Example: cascading cancellation flow This example shows an Agent explicitly propagating cancellation to an outstanding terminal request. That propagation is optional, not an automatic protocol guarantee. Independently, the Client **MUST** answer pending permission requests with the `cancelled` outcome when it sends `session/cancel`, as specified in [prompt turn cancellation](/protocol/v1/prompt-turn#cancellation). It does not wait for `$/cancel_request`. ```mermaid theme={null} sequenceDiagram participant Client participant Agent Note over Client,Agent: 1. Session prompt in progress Client->>Agent: session/prompt (id=1, "Analyze file X") Agent-->>Client: session/update (agent started processing) Note over Client,Agent: 2. Agent makes concurrent requests Agent->>Client: terminal/create (id=2, "grep pattern file.txt") Agent->>Client: session/request_permission (id=3, "read sensitive file") Note over Client,Agent: 3. Client cancels the prompt turn Client->>Agent: session/cancel (sessionId) Client->>Agent: response to id=3 (outcome: cancelled) opt 4. Agent propagates cancellation to the terminal request Agent->>Client: $/cancel_request (requestId=2) end Note over Client,Agent: 5. Terminal request is cancelled in this example Client->>Agent: response to id=2 (error -32800 "Cancelled") Note over Client,Agent: 6. Agent completes prompt cancellation Agent->>Client: response to id=1 (stopReason: "cancelled") ``` # Content Source: https://agentclientprotocol.com/protocol/v1/content Understanding content blocks in the Agent Client Protocol A content block is one piece of user-facing content: text, an image, audio, a link to a resource, or an embedded resource. Content blocks appear in: * User prompts sent via [`session/prompt`](/protocol/v1/prompt-turn#1-user-message) * Language model output streamed through [`session/update`](/protocol/v1/prompt-turn#3-agent-reports-output) notifications * Progress updates and results from [tool calls](/protocol/v1/tool-calls) ## Content types Content from the Agent is untrusted. See [Rendering Agent Content](/protocol/v1/security#rendering-agent-content) and [URIs and Remote Resources](/protocol/v1/security#uris-and-remote-resources). ACP's `ContentBlock` is compatible with, and a superset of, the [Model Context Protocol (MCP) 2025-06-18 `ContentBlock`](https://modelcontextprotocol.io/specification/2025-06-18/schema#contentblock), so Agents can forward content from MCP tool outputs unchanged. ACP adds an optional `uri` on image content. ### Text content Text may be plain text or Markdown. Clients **SHOULD** render it as Markdown. See [Rendering Agent Content](/protocol/v1/security#rendering-agent-content) for raw HTML. ```json theme={null} { "type": "text", "text": "What's the weather like today?" } ``` All Agents **MUST** support text content blocks when included in prompts. **text** `string` *required* The text content to display **annotations** `Annotations` Optional metadata about how the content should be used or displayed. [Learn more](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#annotations). ### Image content Images can be included for visual context or analysis. ```json theme={null} { "type": "image", "mimeType": "image/png", "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB..." } ``` Requires the `image` [prompt capability](/protocol/v1/initialization#prompt-capabilities) when included in prompts. **data** `string` *required* Base64-encoded image data **mimeType** `string` *required* The MIME type of the image (e.g., "image/png", "image/jpeg") **uri** `string` Optional URI reference for the image source **annotations** `Annotations` Optional metadata about how the content should be used or displayed. [Learn more](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#annotations). ### Audio content Audio data for transcription or analysis. ```json theme={null} { "type": "audio", "mimeType": "audio/wav", "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAAB..." } ``` Requires the `audio` [prompt capability](/protocol/v1/initialization#prompt-capabilities) when included in prompts. **data** `string` *required* Base64-encoded audio data **mimeType** `string` *required* The MIME type of the audio (e.g., "audio/wav", "audio/mp3") **annotations** `Annotations` Optional metadata about how the content should be used or displayed. [Learn more](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#annotations). ### Embedded resource Complete resource contents embedded directly in the message. ```json theme={null} { "type": "resource", "resource": { "uri": "file:///home/user/script.py", "mimeType": "text/x-python", "text": "def hello():\n print('Hello, world!')" } } ``` This is the preferred way to include context in prompts, such as when using @-mentions to reference files or other resources. By embedding the content directly in the request, Clients can include context from sources that the Agent may not have direct access to. Requires the `embeddedContext` [prompt capability](/protocol/v1/initialization#prompt-capabilities) when included in prompts. **resource** `EmbeddedResourceResource` *required* The embedded resource contents, which can be either: **Text Resource** **uri** `string` *required* The URI identifying the resource **text** `string` *required* The text content of the resource **mimeType** `string` Optional MIME type of the text content **Blob Resource** **uri** `string` *required* The URI identifying the resource **blob** `string` *required* Base64-encoded binary data **mimeType** `string` Optional MIME type of the blob **annotations** `Annotations` Optional metadata about how the content should be used or displayed. [Learn more](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#annotations). ### Resource link References to resources that the Agent can access. All Agents **MUST** support resource links when included in prompts. ```json theme={null} { "type": "resource_link", "uri": "file:///home/user/document.pdf", "name": "document.pdf", "mimeType": "application/pdf", "size": 1024000 } ``` **uri** `string` *required* The URI of the resource **name** `string` *required* A human-readable name for the resource **mimeType** `string` The MIME type of the resource **title** `string` Optional display title for the resource **description** `string` Optional description of the resource contents **size** `integer` Optional size of the resource in bytes **annotations** `Annotations` Optional metadata about how the content should be used or displayed. [Learn more](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#annotations). # Elicitation Source: https://agentclientprotocol.com/protocol/v1/elicitation Requesting structured information from users Elicitation lets an Agent ask a user for structured information through the Client. It is based on the locked [MCP 2026-07-28 release-candidate elicitation specification](https://modelcontextprotocol.io/specification/draft/client/elicitation) and supports two modes: * **Form mode** collects non-sensitive data using a restricted JSON Schema. * **URL mode** opens an out-of-band interaction for sensitive or externally hosted workflows such as OAuth. ## User interaction requirements Clients **MUST** clearly identify the Agent requesting information, respect user privacy, and provide clear decline and cancel controls. For form mode, Clients **MUST** let users review and modify responses before sending them. For URL mode, Clients **MUST** display the target host and obtain consent before navigating to it. Clients **SHOULD** present the request's `message` so users understand what is requested and why. ## Checking support Clients advertise elicitation support in `clientCapabilities.elicitation` during [initialization](/protocol/v1/initialization#client-capabilities). ```json theme={null} { "clientCapabilities": { "elicitation": { "form": {}, "url": {} } } } ``` Capability objects have the following semantics: * An omitted or `null` top-level `elicitation` field means elicitation is unsupported. * Form support exists only when `form` is explicitly present and non-null. URL support exists only when `url` is explicitly present and non-null. * An omitted or `null` mode field means that mode is not advertised. * A present capability object may advertise zero, one, or both modes. `{}` and `{"form":null,"url":null}` advertise no supported modes. This deliberately differs from the MCP 2026-07-28 release candidate, where an empty elicitation capability retains the original form-only meaning. ACP requires each supported mode to be explicit. Agents **MUST NOT** request a mode the Client has not advertised. Agents **SHOULD** provide a graceful fallback when the required mode is unavailable. ## Creating an elicitation The Agent sends an `elicitation/create` request directly over the ACP connection. This adapts the MCP 2026-07-28 data model. ACP also requires `mode` explicitly. It does not apply MCP's omitted-mode form default. Scope is represented with flattened fields: * `sessionId` for a session-scoped request. It can also include `toolCallId` to associate the request with a tool call in that session. * `requestId` for a request-scoped interaction outside a session. Agents **MUST** bind each elicitation and related state to the receiving Client connection and, when authentication exists, the verified user identity. A `sessionId` alone or an unverified Client-provided identity is not sufficient. ### Form mode ```json theme={null} { "jsonrpc": "2.0", "id": 43, "method": "elicitation/create", "params": { "sessionId": "sess_abc123", "mode": "form", "message": "How should I approach this refactoring?", "requestedSchema": { "type": "object", "properties": { "strategy": { "type": "string", "enum": ["conservative", "balanced", "aggressive"] } }, "required": ["strategy"] } } } ``` Form schemas are flat objects whose properties use the supported primitive and enum schemas. Clients **SHOULD** validate submitted values before responding, and Agents **SHOULD** validate them again. Clients that support schema defaults **SHOULD** pre-populate form fields with their declared default values. Form mode **MUST NOT** be used to request secrets or credentials that grant access or authorize transactions, such as passwords, API keys, access or refresh tokens, private keys, recovery codes, or payment credentials. Ordinary profile information such as a name, email address, or username is not categorically prohibited. Agents **MUST** use URL mode for sensitive interactions. If the Client does not support URL mode, the Agent **MUST NOT** fall back to form mode. It must use another safe flow or fail the operation. ### URL mode ```json theme={null} { "jsonrpc": "2.0", "id": 44, "method": "elicitation/create", "params": { "requestId": 12, "mode": "url", "elicitationId": "github-oauth-001", "url": "https://agent.example.com/connect?elicitationId=github-oauth-001", "message": "Please authorize access to your repositories." } } ``` An `accept` response means the user consented to open the URL. It does not mean the external interaction completed. URL mode is not a substitute for authorizing the Client's access to the Agent. Agents **MUST NOT** send credentials or tokens obtained through URL mode back over ACP or place them in Client or model context. ## Responses The Client responds with one of three actions: * `accept`: the user submitted or consented to the interaction. * `decline`: the user explicitly declined. * `cancel`: the user dismissed the interaction without choosing. The `content` field is optional on `accept`. Receivers treat omission and `null` equivalently. It is only meaningful for `accept`. Receivers ignore it for `decline` and `cancel`. For an accepted form elicitation, `content` **SHOULD** conform to the requested schema. For an accepted URL elicitation, clients normally omit `content` because the interaction happens out of band. Agents **MUST NOT** assume an elicitation succeeds. They **MUST** handle `decline`, `cancel`, and failures by safely falling back, retrying, or failing the originating operation as appropriate. ### URL completion Unlike MCP 2026-07-28, ACP retains an `elicitationId` and completion notification for its direct request flow. The Agent **MUST** keep each `elicitationId` unique among outstanding URL elicitations on that Agent-Client connection, and the Client **MUST** treat it as opaque. The Agent **MAY** send `elicitation/complete` after the external interaction finishes. It **MUST** send that notification only to the same Client that received the original request and include the original `elicitationId`. Clients **MUST** ignore unknown or already-completed IDs. Requests using a mode the Client has not advertised produce JSON-RPC `-32602` (Invalid params). ## URL security Agents and Clients implementing URL mode **MUST** follow these requirements: These requirements adapt MCP's [Safe URL Handling](https://modelcontextprotocol.io/specification/draft/client/elicitation#safe-url-handling) rules to ACP. * Agents **MUST NOT** put credentials, personal data, or pre-authenticated access in the URL and **SHOULD** use HTTPS outside development. * Agents **SHOULD NOT** include URLs intended to be clickable in any field of a form-mode request. * Clients **MUST NOT** prefetch the URL or open it without explicit user consent. They **MUST** show the full URL before asking for consent. * Clients **MUST** open the URL in a secure context that prevents the Client or Agent's language model from inspecting the page or user input. * Clients **SHOULD** highlight the domain and warn about suspicious or ambiguous URLs, including Punycode domains. * Clients **SHOULD NOT** render a URL as clickable in any elicitation field except the `url` field of a URL-mode request, subject to the restrictions above. * The Agent **MUST** verify that the authenticated user who started the elicitation is the same user who completes the external interaction. See the [schema reference](/protocol/v1/schema#elicitation%2Fcreate) for the complete request and response types. # Errors Source: https://agentclientprotocol.com/protocol/v1/error Error handling in the Agent Client Protocol Failed requests return a [JSON-RPC 2.0 error object](https://www.jsonrpc.org/specification#error_object): * `code`: an integer identifying the kind of error * `message`: a short human-readable description * `data` (optional): additional information whose shape depends on the code ```json theme={null} { "jsonrpc": "2.0", "id": 3, "error": { "code": -32002, "message": "Resource not found", "data": { "sessionId": "sess_abc123def456" } } } ``` ## Error codes | Code | Message | Meaning | | - | - | - | | `-32700` | Parse error | The message is not valid JSON. | | `-32600` | Invalid request | The message is not a valid request object, or a request other than `initialize` arrived before initialization. | | `-32601` | Method not found | The receiver does not implement the method. | | `-32602` | Invalid params | The parameters are malformed or contain a value the receiver does not support. | | `-32603` | Internal error | The receiver failed unexpectedly. | | `-32800` | Request cancelled | The request was [cancelled](/protocol/v1/cancellation). | | `-32000` | Authentication required | The request requires [authentication](/protocol/v1/authentication) first. | | `-32002` | Resource not found | A referenced resource, such as a session or file, does not exist. | Receivers **MUST** treat an unrecognized code as a generic failure. Implementation-specific errors **SHOULD** use codes outside `-32768` to `-32000` and `-32899` to `-32800`, which are reserved for JSON-RPC and ACP. ACP takes `-32800` (Request cancelled) from the second range, which LSP also reserves. ## Common cases ### Unknown methods A receiver that does not implement a method, or receives a capability-gated method it did not advertise, **SHOULD** respond with `-32601`. ### Invalid parameters Malformed parameters and unsupported values get `-32602`. For example, an invalid `session/list` cursor, or an unknown `configId` or value in `session/set_config_option`. The same applies to an unknown mode in `session/set_mode`. A `systemPrompt` the Agent cannot apply gets an error, and `-32602` is recommended. See [System prompt](/protocol/v1/session-setup#system-prompt). ### Unknown sessions If a session-scoped request names a session that does not exist or is not active on the connection, the Agent **SHOULD** respond with `-32002` and set `data.sessionId` to the requested ID. A session is active once it is created, loaded or resumed on the connection, until it is closed. This applies to `session/prompt`, `session/set_mode` and `session/set_config_option`, and to `session/load` or `session/resume` of a session that does not exist. Closing or deleting a session that does not exist still succeeds. See [Closing Active Sessions](/protocol/v1/session-setup#closing-active-sessions) and [Deleting Sessions](/protocol/v1/session-delete). Clients **SHOULD** respond with `-32002` when `fs/read_text_file` names a file that does not exist, or a `terminal/*` method names an unknown terminal. ### Requests before initialization Agents **SHOULD** reject any request other than `initialize` that arrives before initialization completes with `-32600`. # Extensibility Source: https://agentclientprotocol.com/protocol/v1/extensibility Adding custom data and capabilities Implementations can add custom behavior without breaking peers that don't know about it. They can attach custom data in `_meta` fields, define custom methods whose names start with `_`, and advertise custom capabilities during initialization. ## The `_meta` field Object types that define a `_meta` field can use it to attach custom information with type `{ [key: string]: unknown }`. This includes many requests, responses, notifications, and nested types such as content blocks, tool calls, plan entries, and capability objects. Not every protocol type defines `_meta`. For example, the `Error` object does not. ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "session/prompt", "params": { "sessionId": "sess_abc123def456", "prompt": [ { "type": "text", "text": "Hello, world!" } ], "_meta": { "traceparent": "00-80e1afed08e019fc1110464cfa66635c-7a085853722dc6d2-01", "com.example/debugMode": true } } } ``` Clients may propagate fields to the agent for correlation purposes, such as `requestId`. The following root-level keys in `_meta` **SHOULD** be reserved for [W3C trace context](https://www.w3.org/TR/trace-context/) to guarantee interop with existing MCP implementations and OpenTelemetry tooling: * `traceparent` * `tracestate` * `baggage` Implementations **MUST NOT** add any custom fields at the root of a type that's part of the specification. All possible names are reserved for future protocol versions. ## Extension methods The protocol reserves any method name starting with an underscore (`_`) for custom extensions, so custom methods can't conflict with methods added in future protocol versions. Extension methods follow standard [JSON-RPC 2.0](https://www.jsonrpc.org/specification) semantics: * **[Requests](https://www.jsonrpc.org/specification#request_object)** - Include an `id` field and expect a response * **[Notifications](https://www.jsonrpc.org/specification#notification)** - Omit the `id` field and are one-way ### Custom requests In addition to the requests specified by the protocol, implementations **MAY** expose and call custom JSON-RPC requests as long as their name starts with an underscore (`_`). ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "_com.example/workspace/buffers", "params": { "language": "rust" } } ``` Upon receiving a custom request, implementations **MUST** respond accordingly with the provided `id`: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "buffers": [ { "id": 0, "path": "/home/user/project/src/main.rs" }, { "id": 1, "path": "/home/user/project/src/editor.rs" } ] } } ``` If the receiving end doesn't recognize the custom method name, it should respond with the standard "Method not found" error: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "error": { "code": -32601, "message": "Method not found" } } ``` To avoid such cases, extensions **SHOULD** advertise their [custom capabilities](#advertising-custom-capabilities) so that callers can check their availability first and adapt their behavior or interface accordingly. ### Custom notifications Custom notifications are regular JSON-RPC notifications that start with an underscore (`_`). Like all notifications, they omit the `id` field: ```json theme={null} { "jsonrpc": "2.0", "method": "_com.example/file_opened", "params": { "path": "/home/user/project/src/editor.rs" } } ``` Unlike with custom requests, implementations **SHOULD** ignore unrecognized notifications. ## Advertising custom capabilities Implementations **SHOULD** use the `_meta` field in capability objects to advertise support for extensions and their methods. To avoid collisions with other extensions, follow [MCP's naming convention](https://modelcontextprotocol.io/specification/2026-07-28/basic/index): prefix extension names with dot-separated labels in reverse-DNS order of a domain you control, followed by `/`. For example, use `com.example/` for `_meta` keys, including capability entries, and `_com.example/` for custom methods. For example: ```json theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "loadSession": true, "_meta": { "com.example/workspace": true, "com.example/fileNotifications": true } } } } ``` Implementations can then negotiate custom features during initialization without breaking standard Clients and Agents. # File System Source: https://agentclientprotocol.com/protocol/v1/file-system Client filesystem access methods The filesystem methods allow Agents to read and write text files within the Client's environment. These methods enable Agents to access unsaved editor state and allow Clients to track file modifications made during agent execution. ## Checking support Before attempting to use filesystem methods, Agents **MUST** verify that the Client supports these capabilities by checking the [Client Capabilities](/protocol/v1/initialization#client-capabilities) field in the Client's `initialize` request: ```json highlight={9,10} theme={null} { "jsonrpc": "2.0", "id": 0, "method": "initialize", "params": { "protocolVersion": 1, "clientCapabilities": { "fs": { "readTextFile": true, "writeTextFile": true } } } } ``` If `readTextFile` or `writeTextFile` is `false` or not present, the Agent **MUST NOT** attempt to call the corresponding filesystem method. ## Reading files The `fs/read_text_file` method allows Agents to read text file contents from the Client's filesystem, including unsaved changes in the editor. ```json theme={null} { "jsonrpc": "2.0", "id": 3, "method": "fs/read_text_file", "params": { "sessionId": "sess_abc123def456", "path": "/home/user/project/src/main.py", "line": 10, "limit": 50 } } ``` **sessionId** `SessionId` *required* The [Session ID](/protocol/v1/session-setup#session-id) for this request. The session determines which filesystem roots are in scope for the path. **path** `string` *required* Absolute path to the file to read **line** `number` Optional line number to start reading from (1-based) **limit** `number` Optional maximum number of lines to read The Client responds with the file contents: ```json theme={null} { "jsonrpc": "2.0", "id": 3, "result": { "content": "def hello_world():\n print('Hello, world!')\n" } } ``` ## Writing files The `fs/write_text_file` method allows Agents to write or update text files in the Client's filesystem. ```json theme={null} { "jsonrpc": "2.0", "id": 4, "method": "fs/write_text_file", "params": { "sessionId": "sess_abc123def456", "path": "/home/user/project/config.json", "content": "{\n \"debug\": true,\n \"version\": \"1.0.0\"\n}" } } ``` **sessionId** `SessionId` *required* The [Session ID](/protocol/v1/session-setup#session-id) for this request. The session determines which filesystem roots are in scope for the path. **path** `string` *required* Absolute path to the file to write. The Client **MUST** create the file if it doesn't exist. **content** `string` *required* The text content to write to the file The Client responds with an empty result on success: ```json theme={null} { "jsonrpc": "2.0", "id": 4, "result": {} } ``` ## Security The Client performs these operations itself, so it is responsible for checking them. A permission request from the Agent does not replace the Client's own checks. * Clients **SHOULD** check requested paths against the session's [root set](/protocol/v1/session-setup#workspace-root-security) at the time of use, and deny the request or ask the user outside them. * Clients **SHOULD** ask the user before `fs/write_text_file` changes files that control execution or approval, such as version-control hooks, editor or Agent settings, and MCP configuration. # Initialization Source: https://agentclientprotocol.com/protocol/v1/initialization How all Agent Client Protocol connections begin The Initialization phase allows [Clients](/protocol/v1/overview#client) and [Agents](/protocol/v1/overview#agent) to negotiate protocol versions, capabilities, and authentication methods. ```mermaid theme={null} sequenceDiagram participant Client participant Agent Note over Client, Agent: Connection established Client->>Agent: initialize Note right of Agent: Negotiate protocol
version & capabilities Agent-->>Client: initialize response Note over Client,Agent: Ready for session setup ``` Before a Session can be created, Clients **MUST** initialize the connection by calling the `initialize` method with: * The latest [protocol version](#protocol-version) supported * The [capabilities](#client-capabilities) supported They **SHOULD** also provide a name and version to the Agent. ```json theme={null} { "jsonrpc": "2.0", "id": 0, "method": "initialize", "params": { "protocolVersion": 1, "clientCapabilities": { "auth": { "terminal": true }, "fs": { "readTextFile": true, "writeTextFile": true }, "terminal": true }, "clientInfo": { "name": "my-client", "title": "My Client", "version": "1.0.0" } } } ``` The Agent **MUST** respond with the chosen [protocol version](#protocol-version) and the [capabilities](#agent-capabilities) it supports. It **SHOULD** also provide a name and version to the Client as well: ```json theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "loadSession": true, "promptCapabilities": { "image": true, "audio": true, "embeddedContext": true }, "mcpCapabilities": { "http": true, "sse": true } }, "agentInfo": { "name": "my-agent", "title": "My Agent", "version": "1.0.0" }, "authMethods": [] } } ``` ## Protocol version The protocol versions that appear in the `initialize` requests and responses are a single integer that identifies a **MAJOR** protocol version. This version is only incremented when breaking changes are introduced. Clients and Agents **MUST** agree on a protocol version and act according to its specification. See [Capabilities](#capabilities) to learn how non-breaking features are introduced. ### Version negotiation The `initialize` request **MUST** include the latest protocol version the Client supports. If the Agent supports the requested version, it **MUST** respond with the same version. Otherwise, the Agent **MUST** respond with the latest version it supports. If the Client does not support the version specified by the Agent in the `initialize` response, the Client **SHOULD** close the connection and inform the user about it. ## Capabilities Capabilities describe features supported by the Client and the Agent. All capabilities included in the `initialize` request are **OPTIONAL**. Clients and Agents **SHOULD** support all possible combinations of their peer's capabilities. The introduction of new capabilities is not considered a breaking change. Therefore, Clients and Agents **MUST** treat all capabilities omitted in the `initialize` request as **UNSUPPORTED**. Capabilities are high-level and are not attached to a specific base protocol concept. Capabilities may specify the availability of protocol methods, notifications, or a subset of their parameters. They may also signal behaviors of the Agent or Client implementation. Implementations can also [advertise custom capabilities](/protocol/v1/extensibility#advertising-custom-capabilities) using the `_meta` field to indicate support for protocol extensions. ### Client capabilities The Client **SHOULD** specify whether it supports the following capabilities: #### Terminal authentication **auth.terminal** `boolean` The Client can reproduce the configured Agent invocation in an interactive terminal. When `true`, the Agent may advertise `type: "terminal"` authentication methods. > [card] > > Learn more about Terminal Authentication > > [Open](/protocol/v1/authentication) #### File system **readTextFile** `boolean` The `fs/read_text_file` method is available. **writeTextFile** `boolean` The `fs/write_text_file` method is available. > [card] > > Learn more about File System methods > > [Open](/protocol/v1/file-system) #### Terminal **terminal** `boolean` All `terminal/*` methods are available, allowing the Agent to execute and manage shell commands. > [card] > > Learn more about Terminals > > [Open](/protocol/v1/terminals) #### Elicitation **elicitation** `ElicitationCapabilities Object` The Client advertises its supported `elicitation/create` modes. Omitted or `null` means no modes are advertised. A present object advertises each mode only through its corresponding non-null `form` or `url` field. Empty and all-null objects are valid but advertise no supported modes. Unlike MCP, ACP does not treat `{}` as form support. > [card] > > Learn more about Elicitation > > [Open](/protocol/v1/elicitation) #### Boolean config options **session.configOptions.boolean** `BooleanConfigOptionCapabilities Object` The Client supports `boolean` session configuration options. Omitted or `null` at any level means the Client does not advertise support. Supplying `{}` means Agents may include `type: "boolean"` options in v1 `configOptions` payloads. > [card] > > Learn more about Session Config Options > > [Open](/protocol/v1/session-config-options) #### Session compaction **session.compaction** `CompactionCapabilities Object` The Client supports ID-addressed `compaction_update` and `compaction_summary_chunk` session updates, including their lifecycle, placement, patch, and replay semantics. Omitted or `null` at either level means unsupported. Supplying `{}` advertises the complete contract. Agents must not send these updates to a v1 Client that does not advertise it. > [card] > > Learn more about Session Compaction > > [Open](/protocol/v1/prompt-turn#session-compaction) #### Session notices **session.notices** `NoticeCapabilities Object` The Client can present live `notice` session updates to the user. This field is optional and nullable. Omitting `session` or `notices`, or setting either to `null`, means unsupported. Supplying `{}` advertises notice support. Agents must not send notices without this capability and may instead use an agent message when the information should still be surfaced to the user. > [card] > > Learn more about Session Notices > > [Open](/protocol/v1/prompt-turn#session-notices) ### Agent capabilities The Agent **SHOULD** specify whether it supports the following capabilities: **loadSession** `boolean` The [`session/load`](/protocol/v1/session-setup#loading-sessions) method is available. **promptCapabilities** `PromptCapabilities Object` Object indicating the different types of [content](/protocol/v1/content) that may be included in `session/prompt` requests. **auth** `AgentAuthCapabilities Object` Authentication-related capabilities supported by the Agent. #### Prompt capabilities As a baseline, all Agents **MUST** support `text` and `resource_link` content blocks in `session/prompt` requests. Optionally, they **MAY** support richer types of [content](/protocol/v1/content) by specifying the following capabilities: **image** `boolean` The prompt may include `image` content blocks **audio** `boolean` The prompt may include `audio` content blocks **embeddedContext** `boolean` The prompt may include `resource` content blocks #### MCP capabilities **http** `boolean` The Agent supports connecting to MCP servers over HTTP. **sse** `boolean` The Agent supports connecting to MCP servers over SSE. Note: This transport has been deprecated by the MCP spec. #### Authentication capabilities **logout** `LogoutCapabilities Object` The [`logout`](/protocol/v1/authentication#logging-out) method is available. > [card] > > Learn more about Authentication > > [Open](/protocol/v1/authentication) #### Session capabilities As a baseline, all Agents **MUST** support `session/new`, `session/prompt`, `session/cancel`, and `session/update`. Optionally, they **MAY** support other session methods and notifications by specifying additional capabilities. **delete** `SessionDeleteCapabilities Object` The [`session/delete`](/protocol/v1/session-delete) method is available. Omitted or `null` both mean the Agent does not advertise support. Supplying an empty object means the Agent supports deleting sessions from `session/list`. **additionalDirectories** `SessionAdditionalDirectoriesCapabilities Object` The Agent supports `additionalDirectories` on supported session lifecycle requests. Omitted or `null` both mean the Agent does not advertise support. Supplying `{}` means the Agent supports additional workspace roots. **systemPrompt** `SessionSystemPromptCapabilities Object` The Agent supports [`systemPrompt`](/protocol/v1/session-setup#system-prompt) on session lifecycle requests. Omitted or `null` both mean the Agent does not advertise support. Supplying `{}` means the Agent supports `append` mode. Supplying `{ "mode": { "override": {} } }` also advertises `override` mode. > [!NOTE] > > `session/load` is still handled by the top-level `load_session` capability. > This will be unified in future versions of the protocol. ## Implementation information Both Clients and Agents **SHOULD** provide information about their implementation in the `clientInfo` and `agentInfo` fields respectively. Both take the following three fields: **name** `string` *required* Intended for programmatic or logical use, but can be used as a display name fallback if title isn't present. **title** `string` Intended for UI and end-user contexts and optimized to be human-readable and easily understood. Optional. Omitted and `null` are equivalent. If not provided, the name should be used for display. **version** `string` *required* Version of the implementation. Can be displayed to the user or used for debugging or metrics purposes. > [!NOTE] > > Note: in future versions of the protocol, this information will be required. *** Once the connection is initialized, you're ready to [create a session](/protocol/v1/session-setup) and begin the conversation with the Agent. # Overview Source: https://agentclientprotocol.com/protocol/v1/overview How the Agent Client Protocol works The Agent Client Protocol allows [Agents](#agent) and [Clients](#client) to communicate by exposing methods that each side can call and sending notifications to inform each other of events. ## Communication Model The protocol follows the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification with two types of messages: * Methods are request-response pairs that expect a result or error. * Notifications are one-way messages that don't expect a response. ## Message flow A typical flow follows this pattern: **1. Initialization Phase** * Client → Agent: `initialize` to establish connection * Client: completes an advertised authentication flow if required. For example, `authenticate` for an Agent-handled method or launch and reconnect for a terminal method **2. Session Setup - either:** * Client → Agent: `session/new` to create a new session * Client → Agent: `session/load` to resume an existing session if supported **3. Prompt Turn** * Client → Agent: `session/prompt` to send user message * Agent → Client: `session/update` notifications for progress updates and user-facing notices * Agent → Client: File operations or permission requests as needed * Client → Agent: `session/cancel` to interrupt processing if needed * Turn ends and the Agent sends the `session/prompt` response with a stop reason ## Agent Agents are programs that use generative AI to autonomously modify code. They typically run as subprocesses of the Client. ### Baseline methods **initialize** [Negotiate versions and exchange capabilities.](/protocol/v1/initialization). **authenticate** Authenticate with the Agent (if required). **session/new** [Create a new conversation session](/protocol/v1/session-setup#creating-a-session). **session/prompt** [Send user prompts](/protocol/v1/prompt-turn#1-user-message) to the Agent. ### Optional methods **session/load** [Load an existing session](/protocol/v1/session-setup#loading-sessions) (requires `loadSession` capability). **logout** [End the current authenticated state](/protocol/v1/authentication#logging-out) (requires `agentCapabilities.auth.logout` capability). **session/set\_mode** [Switch between agent operating modes](/protocol/v1/session-modes#setting-the-current-mode). ### Notifications **session/cancel** [Cancel ongoing operations](/protocol/v1/prompt-turn#cancellation) (no response expected). ## Client Clients provide the interface between users and agents. They are typically code editors (IDEs, text editors) but can also be other UIs for interacting with agents. Clients manage the environment, handle user interactions, and control access to resources. ### Baseline methods **session/request\_permission** [Request user authorization](/protocol/v1/tool-calls#requesting-permission) for tool calls. ### Optional methods **fs/read\_text\_file** [Read file contents](/protocol/v1/file-system#reading-files) (requires `fs.readTextFile` capability). **fs/write\_text\_file** [Write file contents](/protocol/v1/file-system#writing-files) (requires `fs.writeTextFile` capability). **terminal/create** [Create a new terminal](/protocol/v1/terminals) (requires `terminal` capability). **terminal/output** Get terminal output and exit status (requires `terminal` capability). **terminal/release** Release a terminal (requires `terminal` capability). **terminal/wait\_for\_exit** Wait for terminal command to exit (requires `terminal` capability). **terminal/kill** Kill terminal command without releasing (requires `terminal` capability). **elicitation/create** [Request structured information from the user](/protocol/v1/elicitation) (requires the matching `elicitation` mode capability). ### Notifications **elicitation/complete** [Report completion of an out-of-band URL interaction](/protocol/v1/elicitation#url-completion) (no response expected). **session/update** [Send session updates](/protocol/v1/prompt-turn#3-agent-reports-output) to inform the Client of changes (no response expected). This includes: * [Message chunks](/protocol/v1/content) (agent, user, thought) * [Tool calls and updates](/protocol/v1/tool-calls) * [Plans](/protocol/v1/agent-plan) * [Available commands updates](/protocol/v1/slash-commands#advertising-commands) * [Mode changes](/protocol/v1/session-modes#from-the-agent) * [User-facing notices](/protocol/v1/prompt-turn#session-notices) * [Context compactions](/protocol/v1/prompt-turn#session-compaction) ## Argument requirements * All file paths in the protocol **MUST** be absolute. * Line numbers are 1-based ## Error handling All methods follow standard JSON-RPC 2.0 [error handling](https://www.jsonrpc.org/specification#error_object): * Successful responses include a `result` field * Errors include an `error` object with `code` and `message` * Notifications never receive responses (success or error) See [Errors](/protocol/v1/error) for the error codes ACP uses and when to use them. ## Conventions Unless explicitly defined otherwise in the schema, ACP-defined JSON object property keys use `camelCase`. String values carried by discriminator fields use `snake_case`. The JSON-RPC envelope fields (`jsonrpc`, `id`, `method`, `params`, `result`, and `error`) follow the JSON-RPC 2.0 specification. ## Extensibility Implementations can extend the protocol without breaking compatibility: * Add custom data using `_meta` fields * Create custom methods by prefixing their name with underscore (`_`) * Advertise custom capabilities during initialization See [Extensibility](/protocol/v1/extensibility) for details. ## Next steps * [Security Considerations](/protocol/v1/security) covers the trust model. Read it before shipping an Agent or Client. * [Initialization](/protocol/v1/initialization) covers version and capability negotiation. * [Session Setup](/protocol/v1/session-setup) covers creating and loading sessions. * [Prompt Turn](/protocol/v1/prompt-turn) covers the prompt turn lifecycle. * [Extensibility](/protocol/v1/extensibility) covers custom data, methods, and capabilities. * The [Test Compatibility Kit](/libraries/testing) checks an Agent implementation against the protocol. # Prompt Turn Source: https://agentclientprotocol.com/protocol/v1/prompt-turn Understanding the core conversation flow A prompt turn represents a complete interaction cycle between the [Client](/protocol/v1/overview#client) and [Agent](/protocol/v1/overview#agent), starting with a user message and continuing until the Agent completes its response. This may involve multiple exchanges with the language model and tool invocations. Before sending prompts, Clients **MUST** first complete the [initialization](/protocol/v1/initialization) phase and [session setup](/protocol/v1/session-setup). ## Session updates Agents send `session/update` notifications to report streamed content, tool activity, and changes to session state. The `sessionUpdate` field inside `params.update` identifies the variant: | `sessionUpdate` value | Description | | - | - | | `user_message_chunk` | A streamed chunk of a user message. | | `agent_message_chunk` | A streamed chunk of the Agent's response. | | `agent_thought_chunk` | A streamed chunk of the Agent's reasoning. | | `tool_call` | A new [tool call](/protocol/v1/tool-calls#creating). | | `tool_call_update` | A change to a [tool call's status or results](/protocol/v1/tool-calls#updating). | | `plan` | The Agent's [execution plan](/protocol/v1/agent-plan). | | `available_commands_update` | The set of [available slash commands](/protocol/v1/slash-commands) is ready or has changed. | | `current_mode_update` | The current [session mode](/protocol/v1/session-modes#from-the-agent) has changed. | | `config_option_update` | The session's [configuration options](/protocol/v1/session-config-options#from-the-agent) have changed. | | `session_info_update` | [Session metadata](/protocol/v1/session-list#updating-session-metadata), such as the title or last update time, has changed. | | `usage_update` | The session's [context window usage and cumulative cost](#session-usage-updates). | | `notice` | A live [user-facing notice](#session-notices) that is not part of session history. Requires the Client's `session.notices` capability. | | `compaction_update` | Creates or updates a [context compaction](#session-compaction). Requires the Client's `session.compaction` capability. | | `compaction_summary_chunk` | Appends content to a [compaction's retained summary](#session-compaction). Requires the Client's `session.compaction` capability. | This is the complete set of variants defined in the current [`SessionUpdate` schema](/protocol/v1/schema#sessionupdate), which describes each payload in detail. The walkthrough below illustrates common uses of these updates. Session updates are not limited to active prompt turns. For example, Agents may advertise commands after creating a session, and replay user and Agent messages when [loading a session](/protocol/v1/session-setup#loading-sessions). ## The prompt turn lifecycle ```mermaid theme={null} sequenceDiagram participant Client participant Agent Note over Agent,Client: Session ready Note left of Client: User sends message Client->>Agent: session/prompt (user message) Note right of Agent: Process with LLM loop Until completion Note right of Agent: LLM responds with
content/tool calls Agent->>Client: session/update (plan) Agent->>Client: session/update (agent_message_chunk) opt Tool calls requested Agent->>Client: session/update (tool_call) opt Permission required Agent->>Client: session/request_permission Note left of Client: User grants/denies Client-->>Agent: Permission response end Agent->>Client: session/update (tool_call status: in_progress) Note right of Agent: Execute tool Agent->>Client: session/update (tool_call status: completed) Note right of Agent: Send tool results
back to LLM end opt User cancelled during execution Note left of Client: User cancels prompt Client->>Agent: session/cancel Note right of Agent: Abort operations Agent-->>Client: session/prompt response (cancelled) end end Agent-->>Client: session/prompt response (stopReason) ``` ### 1. User message The turn begins when the Client sends a `session/prompt`: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "session/prompt", "params": { "sessionId": "sess_abc123def456", "prompt": [ { "type": "text", "text": "Can you analyze this code for potential issues?" }, { "type": "resource", "resource": { "uri": "file:///home/user/project/main.py", "mimeType": "text/x-python", "text": "def process_data(items):\n for item in items:\n print(item)" } } ] } } ``` **sessionId** `SessionId` *required* The [ID](/protocol/v1/session-setup#session-id) of the session to send this message to. **prompt** `ContentBlock[]` *required* The contents of the user message, e.g. text, images, files, etc. Clients **MUST** restrict types of content according to the [Prompt Capabilities](/protocol/v1/initialization#prompt-capabilities) established during [initialization](/protocol/v1/initialization). > [card] > > Learn more about Content > > [Open](/protocol/v1/content) ### 2. Agent processing Upon receiving the prompt request, the Agent processes the user's message and sends it to the language model, which **MAY** respond with text content, tool calls, or both. ### 3. Agent reports output The Agent reports the model's output to the Client via `session/update` notifications. This may include the Agent's plan for accomplishing the task: ```json expandable theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "plan", "entries": [ { "content": "Check for syntax errors", "priority": "high", "status": "pending" }, { "content": "Identify potential type issues", "priority": "medium", "status": "pending" }, { "content": "Review error handling patterns", "priority": "medium", "status": "pending" }, { "content": "Suggest improvements", "priority": "low", "status": "pending" } ] } } } ``` > [card] > > Learn more about Agent Plans > > [Open](/protocol/v1/agent-plan) The Agent then reports text responses from the model: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "agent_message_chunk", "messageId": "msg_agent_c42b9", "content": { "type": "text", "text": "I'll analyze your code for potential issues. Let me examine it..." } } } } ``` #### Message IDs The Agent **MAY** include an opaque, unique `messageId` on message chunks. Chunks with the same `messageId` belong to the same message. A changed `messageId` indicates a new message. If the model requested tool calls, these are also reported immediately: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "tool_call", "toolCallId": "call_001", "title": "Analyzing Python code", "kind": "other", "status": "pending" } } } ``` #### Session notices The Agent **MUST NOT** send `notice` updates unless the Client advertised support by supplying `clientCapabilities.session.notices: {}` in its `initialize` request. Omitting `session` or `notices`, or setting either field to `null`, means the Client does not advertise support. When the capability is absent, the Agent may use an ordinary agent message instead if the information should still be surfaced to the user. That fallback is conversation content and follows normal message-history semantics. When the Client advertises support, the Agent **MAY** send a live user-facing notice at any point while a session exists, including outside prompt processing: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "notice", "severity": "warning", "title": "MCP server unavailable", "description": "Continuing without it." } } } ``` `severity` is required and non-null and initially supports `info`, `warning`, and `error`. It is an open string enum: values beginning with `_` are reserved for implementation-specific extensions, while other unknown values are reserved for future ACP severities. Clients preserve unknown values and use a generic notice presentation without inferring additional behavior from them. `title` is required, non-null, non-empty plain text suitable for a compact presentation. `description` is optional, nullable plain text with supporting detail. Omission and `null` both mean no description. `_meta` is an optional, nullable object scoped to this event. Omission and `null` both mean no event metadata. Unlike compaction patch fields, these fields do not update or clear an earlier notice. Advertising support does not acknowledge delivery or guarantee display of an individual notice. Agents must still behave as though a notice may not have been received, displayed, or seen. A notice must not carry information required for protocol correctness, authorization, user action, task completion, or fatal-error reporting. Clients own presentation and dismissal. They may use a toast, banner, inline status region, notification center, or another accessible surface, and may coalesce repeated notices. Severity is only a presentation hint. Even `error` does not fail a request, stop foreground work, change session state, or imply a prompt stop reason. Dismissal is local and produces no acknowledgement or removal event. Notices have no ID or Agent-managed lifecycle. Each occurrence is an independent live event, not conversation history, and **SHOULD NOT** be included in session replay. If a condition remains relevant after reconnecting, the Agent may emit a new notice. #### Session compaction The Agent **MUST NOT** send `compaction_update` or `compaction_summary_chunk` unless the Client advertised support by supplying `clientCapabilities.session.compaction: {}` in its `initialize` request. Omitting `session` or `compaction`, or setting either field to `null`, means the Client does not support these updates. This requirement applies to both live updates and history replay. When the capability is absent, the Agent may describe compaction through an ordinary agent message instead. That fallback is conversation content, not an ID-addressed compaction entity, and follows normal message-history semantics. When the Client advertises support, the Agent **MAY** report context compaction as one persistent, ID-addressed timeline entity. A single `compaction_update` with `status: "completed"` is sufficient. Reporting progress is optional. Summary content is also optional. It may be sent all at once in the `summary` field or streamed using `compaction_summary_chunk` for the same `compactionId`. For example, an Agent can report that compaction has started: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "compaction_update", "compactionId": "cmp_001", "status": "in_progress" } } } ``` `compactionId` and `status` are required and non-null on every `compaction_update`. The ID is an opaque, Agent-owned string, unique within the session, and **MUST NOT** be reused for another compaction. Clients initialize a first-seen compaction ID with status `in_progress` and unset optional fields, then apply the notification. The first notification fixes the entity's timeline position in receive order: it follows previously received timeline content and precedes content first received later. Later updates and chunks for an ID-addressed entity patch it in place. They do not move or split it around the compaction. | `status` | Meaning | | - | - | | `in_progress` | Compaction has started and has not finished. | | `completed` | Compaction finished successfully. | | `failed` | Compaction finished unsuccessfully. | | `cancelled` | Compaction was cancelled before it finished. | The Agent **MUST** report a terminal status when a reported compaction ends. `status` is an open string enum. Values beginning with `_` are reserved for implementation-specific extensions. Other unknown values are reserved for future ACP statuses. Clients preserve unknown strings and present a generic state without inferring lifecycle or control behavior. If the retained summary is available incrementally, the Agent may append one [content block](/protocol/v1/content) at a time: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "compaction_summary_chunk", "compactionId": "cmp_001", "content": { "type": "text", "text": "## Retained context\n\n" } } } } ``` `compactionId` and `content` are required and non-null on each chunk. Chunk `_meta` is optional and nullable, is scoped to that chunk, and has no patch semantics: omission and `null` both mean no chunk metadata. An update may omit `summary` to retain the streamed content. A non-streaming Agent can instead supply the complete summary, and a streaming Agent can use the same field as an authoritative replacement of content received so far: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "compaction_update", "compactionId": "cmp_001", "status": "completed", "summary": [ { "type": "text", "text": "## Retained context\n\nThe user is updating the ACP schema." } ] } } } ``` The following `compaction_update` fields are optional, nullable patches: | Field | Type | Meaning | | - | - | - | | `summary` | `ContentBlock[]` | The unencrypted, user-displayable summary content produced or retained by compaction. | | `error` | `string` | A human-readable error description. | | `_meta` | `object` | Extensible metadata for the compaction entity. | For each patch field, omission leaves the stored value unchanged, `null` clears it, and a concrete value replaces it. On a first-seen ID, omission and `null` both start with no value. `summary: []` also clears the summary. Clients apply updates and chunks in receive order for each ID. Chunks append to the current summary. A concrete `summary` replaces all previously accumulated content, and any subsequent chunks append to that replacement. `summary: null` or `summary: []` clears accumulated content, including partial output before failure or cancellation. The summary is not the Agent's complete replacement history or generic status text such as "Compaction completed". It should faithfully represent the retained, user-displayable summary without internal prompt framing or hidden instructions. Text blocks may contain Markdown. Agents should omit it when no unencrypted summary is available or when disclosure would reveal context that was not otherwise user-visible. During [history replay](/protocol/v1/session-setup#loading-sessions), compaction updates and summary chunks follow the same semantics as live delivery. Replay does not implicitly reset omitted patch fields. Agents use replacement or clearing summary patches as needed to avoid duplicating content the Client already holds. Compaction does not instruct the Client to discard earlier conversation history. Collapsing it is a local presentation choice. It also does not replace [`usage_update`](#session-usage-updates), which reports current context-window usage and cost rather than a compaction boundary. #### Session usage updates The Agent **MAY** also report current session context and cumulative cost state with a `usage_update`: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "usage_update", "used": 53000, "size": 200000, "cost": { "amount": 0.045, "currency": "USD" } } } } ``` `used` and `size` are required and non-null token counts for the current session context. `cost` is optional and, if present, `amount` and `currency` are required. `currency` is the unit of `amount`: an ISO 4217 currency code such as `"USD"` for money, or another unit such as `"credits"`. ### 4. Check for completion If there are no pending tool calls, the turn ends and the Agent **MUST** respond to the original `session/prompt` request with a `StopReason`: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "result": { "stopReason": "end_turn" } } ``` Agents **MAY** stop the turn at any point by returning the corresponding [`StopReason`](#stop-reasons). ### 5. Tool invocation and status reporting Before proceeding with execution, the Agent **MAY** request permission from the Client via the `session/request_permission` method. Once permission is granted (if required), the Agent **SHOULD** invoke the tool and report a status update marking the tool as `in_progress`: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "tool_call_update", "toolCallId": "call_001", "status": "in_progress" } } } ``` As the tool runs, the Agent **MAY** send additional updates, providing real-time feedback about tool execution progress. While tools execute on the Agent, they **MAY** use Client capabilities such as the file system (`fs`) methods to access resources within the Client's environment. When the tool completes, the Agent sends another update with the final status and any content: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "tool_call_update", "toolCallId": "call_001", "status": "completed", "content": [ { "type": "content", "content": { "type": "text", "text": "Analysis complete:\n- No syntax errors found\n- Consider adding type hints for better clarity\n- The function could benefit from error handling for empty lists" } } ] } } } ``` > [card] > > Learn more about Tool Calls > > [Open](/protocol/v1/tool-calls) ### 6. Continue conversation The Agent sends the tool results back to the language model as another request. The cycle returns to [step 2](#2-agent-processing), continuing until the language model completes its response without requesting additional tool calls or the turn gets stopped by the Agent or cancelled by the Client. ## Stop reasons When an Agent stops a turn, it must specify the corresponding `StopReason`: **end\_turn** The language model finishes responding without requesting more tools **max\_tokens** The maximum token limit is reached **max\_turn\_requests** The maximum number of model requests in a single turn is exceeded **refusal** The Agent refuses to continue **cancelled** The Client cancels the turn ## Cancellation Clients **MAY** cancel an ongoing prompt turn at any time by sending a `session/cancel` notification: ```json theme={null} { "jsonrpc": "2.0", "method": "session/cancel", "params": { "sessionId": "sess_abc123def456" } } ``` The Client **SHOULD** preemptively mark all non-finished tool calls pertaining to the current turn as `cancelled` as soon as it sends the `session/cancel` notification. The Client **MUST** respond to all pending `session/request_permission` requests with the `cancelled` outcome. When the Agent receives this notification, it **SHOULD** stop all language model requests and all tool call invocations as soon as possible. After all ongoing operations have been successfully aborted and pending updates have been sent, the Agent **MUST** respond to the original `session/prompt` request with the `cancelled` [stop reason](#stop-reasons). > [!WARNING] > > API client libraries and tools often throw an exception when their operation is aborted, which may propagate as an error response to `session/prompt`. > > Clients often display unrecognized errors from the Agent to the user, which would be undesirable for cancellations as they aren't considered errors. > > Agents **MUST** catch these errors and return the semantically meaningful `cancelled` stop reason, so that Clients can reliably confirm the cancellation. The Agent **MAY** send `session/update` notifications with content or tool call updates after receiving the `session/cancel` notification, but it **MUST** ensure that it does so before responding to the `session/prompt` request. The Client **SHOULD** still accept tool call updates received after sending `session/cancel`. *** Once a prompt turn completes, the Client may send another `session/prompt` to continue the conversation, building on the context established in previous turns. # Schema Source: https://agentclientprotocol.com/protocol/v1/schema Schema definitions for the Agent Client Protocol > [!NOTE] > > The schema file can be downloaded directly from the [latest GitHub > release](https://github.com/agentclientprotocol/agent-client-protocol/releases/latest/download/schema.json). ## Agent Defines the interface that all ACP-compliant agents must implement. Agents are programs that use generative AI to autonomously modify code. They handle requests from clients and execute tasks using language models and tools. ### authenticate Authenticates the client using the specified authentication method. Called when the agent requires authentication before allowing session creation. The client provides an authentication method ID that was advertised during initialization and whose type defines the `authenticate` flow. After successful authentication, the client can proceed to create sessions with `session/new` without receiving an `auth_required` (`-32000`) error. See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/v1/initialization) #### AuthenticateRequest Request parameters for the authenticate method. Specifies which authentication method to use. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **methodId** `[AuthMethodId](#authmethodid)` *required* The ID of the authentication method to use. Must be one of the methods advertised in the initialize response. #### AuthenticateResponse Response to the `authenticate` method. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) ### initialize Establishes the connection with a client and negotiates protocol capabilities. This method is called once at the beginning of the connection to: * Negotiate the protocol version to use * Exchange capability information between client and agent * Determine available authentication methods The agent should respond with its supported protocol version and capabilities. See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/v1/initialization) #### InitializeRequest Request parameters for the initialize method. Sent by the client to establish connection and negotiate capabilities. See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/v1/initialization) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **clientCapabilities** `[ClientCapabilities](#clientcapabilities)` Capabilities supported by the client. * Default: `{"fs":{"readTextFile":false,"writeTextFile":false},"terminal":false,"auth":{"terminal":false}}` **clientInfo** `[Implementation](#implementation) | null` Information about the Client name and version sent to the Agent. Note: in future versions of the protocol, this will be required. **protocolVersion** `[ProtocolVersion](#protocolversion)` *required* The latest protocol version supported by the client. #### InitializeResponse Response to the `initialize` method. Contains the negotiated protocol version and agent capabilities. See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/v1/initialization) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **agentCapabilities** `[AgentCapabilities](#agentcapabilities)` Capabilities supported by the agent. * Default: `{"loadSession":false,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false},"mcpCapabilities":{"http":false,"sse":false},"sessionCapabilities":{},"auth":{}}` **agentInfo** `[Implementation](#implementation) | null` Information about the Agent name and version sent to the Client. Note: in future versions of the protocol, this will be required. **authMethods** `[AuthMethod\[\]](#authmethod)` Authentication methods supported by the agent. * Default: `[]` **protocolVersion** `[ProtocolVersion](#protocolversion)` *required* The protocol version the client specified if supported by the agent, or the latest protocol version supported by the agent. The client should disconnect, if it doesn't support this version. ### logout Logs out of the current authenticated state. After a successful logout, all new sessions will require authentication. There is no guarantee about the behavior of already running sessions. #### LogoutRequest Request parameters for the logout method. Terminates the current authenticated session. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) #### LogoutResponse Response to the `logout` method. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) ### session/cancel Cancels ongoing operations for a session. This is a notification sent by the client to cancel an ongoing prompt turn. Upon receiving this notification, the Agent SHOULD: * Stop all language model requests as soon as possible * Abort all tool call invocations in progress * Send any pending `session/update` notifications * Respond to the original `session/prompt` request with the `cancelled` stop reason See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v1/prompt-turn#cancellation) #### CancelNotification Notification to cancel ongoing operations for a session. See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v1/prompt-turn#cancellation) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **sessionId** `[SessionId](#sessionid)` *required* The ID of the session to cancel operations for. ### session/close Closes an active session and frees up any resources associated with it. This method is only available if the agent advertises the `sessionCapabilities.close` capability. The agent must cancel any ongoing work (as if `session/cancel` was called) and then free up any resources associated with the session. #### CloseSessionRequest Request parameters for closing an active session. If supported, the agent **must** cancel any ongoing work related to the session (treat it as if `session/cancel` was called) and then free up any resources associated with the session. Only available if the Agent supports the `sessionCapabilities.close` capability. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **sessionId** `[SessionId](#sessionid)` *required* The ID of the session to close. #### CloseSessionResponse Response from closing a session. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) ### session/delete Deletes an existing session from `session/list`. This method is only available if the agent advertises the `sessionCapabilities.delete` capability. #### DeleteSessionRequest Request parameters for deleting an existing session from `session/list`. Only available if the Agent supports the `sessionCapabilities.delete` capability. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **sessionId** `[SessionId](#sessionid)` *required* The ID of the session to delete. #### DeleteSessionResponse Response from deleting a session. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) ### session/list Lists existing sessions known to the agent. This method is only available if the agent advertises the `sessionCapabilities.list` capability. The agent should return metadata about sessions with optional filtering and pagination support. #### ListSessionsRequest Request parameters for listing existing sessions. Only available if the Agent supports the `sessionCapabilities.list` capability. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **cursor** `string | null` Opaque cursor token from a previous response's nextCursor field for cursor-based pagination **cwd** `string | null` Filter sessions by working directory. Must be an absolute path. #### ListSessionsResponse Response from listing sessions. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **nextCursor** `string | null` Opaque cursor token. If present, pass this in the next request's cursor parameter to fetch the next page. If absent, there are no more results. **sessions** `[SessionInfo\[\]](#sessioninfo)` *required* Array of session information objects ### session/load Loads an existing session to resume a previous conversation. This method is only available if the agent advertises the `loadSession` capability. The agent should: * Restore the session context and conversation history * Connect to the specified MCP servers * Stream the entire conversation history back to the client via notifications See protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/v1/session-setup#loading-sessions) #### LoadSessionRequest Request parameters for loading an existing session. Only available if the Agent supports the `loadSession` capability. See protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/v1/session-setup#loading-sessions) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **additionalDirectories** `"string"[]` Additional workspace roots to activate for this session. Each path must be absolute. When omitted or empty, no additional roots are activated. When non-empty, this is the complete resulting additional-root list for the loaded session. It may differ from any previously used or reported list as long as the request `cwd` matches the session's `cwd`. **cwd** `string` *required* The working directory for this session. Must be an absolute path. **mcpServers** `[McpServer\[\]](#mcpserver)` *required* List of MCP servers to connect to for this session. **sessionId** `[SessionId](#sessionid)` *required* The ID of the session to load. **systemPrompt** `[SystemPrompt](#systemprompt) | null` System-level instructions for the loaded session. Optional. Omitted and `null` are equivalent. The Agent may then keep a system prompt it stored with the session or use its default instructions. Clients MUST only send this when the Agent advertises `sessionCapabilities.systemPrompt`, and SHOULD send the same value they used when the session was created. #### LoadSessionResponse Response from loading an existing session. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **configOptions** `[SessionConfigOption\[\]](#sessionconfigoption) | null` Initial session configuration options if supported by the Agent. **modes** `[SessionModeState](#sessionmodestate) | null` Initial mode state if supported by the Agent See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/session-modes) ### session/new Creates a new conversation session with the agent. Sessions represent independent conversation contexts with their own history and state. The agent should: * Create a new session context * Connect to any specified MCP servers * Return a unique session ID for future requests May return an `auth_required` (`-32000`) error if the agent requires authentication. See protocol docs: [Session Setup](https://agentclientprotocol.com/protocol/v1/session-setup) #### NewSessionRequest Request parameters for creating a new session. See protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/v1/session-setup#creating-a-session) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **additionalDirectories** `"string"[]` Additional workspace roots for this session. Each path must be absolute. These expand the session's filesystem scope without changing `cwd`, which remains the base for relative paths. When omitted or empty, no additional roots are activated for the new session. **cwd** `string` *required* The working directory for this session. Must be an absolute path. **mcpServers** `[McpServer\[\]](#mcpserver)` *required* List of MCP (Model Context Protocol) servers the agent should connect to. **systemPrompt** `[SystemPrompt](#systemprompt) | null` System-level instructions for the new session. Optional. Omitted and `null` are equivalent and mean the Agent uses its own default instructions. Clients MUST only send this when the Agent advertises `sessionCapabilities.systemPrompt`. #### NewSessionResponse Response from creating a new session. See protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/v1/session-setup#creating-a-session) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **configOptions** `[SessionConfigOption\[\]](#sessionconfigoption) | null` Initial session configuration options if supported by the Agent. **modes** `[SessionModeState](#sessionmodestate) | null` Initial mode state if supported by the Agent See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/session-modes) **sessionId** `[SessionId](#sessionid)` *required* Unique identifier for the created session. Used in all subsequent requests for this conversation. ### session/prompt Processes a user prompt within a session. This method handles the whole lifecycle of a prompt: * Receives user messages with optional context (files, images, etc.) * Processes the prompt using language models * Reports language model content and tool calls to the Clients * Requests permission to run tools * Executes any requested tool calls * Returns when the turn is complete with a stop reason See protocol docs: [Prompt Turn](https://agentclientprotocol.com/protocol/v1/prompt-turn) #### PromptRequest Request parameters for sending a user prompt to the agent. Contains the user's message and any additional context. See protocol docs: [User Message](https://agentclientprotocol.com/protocol/v1/prompt-turn#1-user-message) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **prompt** `[ContentBlock\[\]](#contentblock)` *required* The blocks of content that compose the user's message. As a baseline, the Agent MUST support `text` and `resource_link` content blocks, while other variants are optionally enabled via `PromptCapabilities`. The Client MUST adapt its interface according to `PromptCapabilities`. The client MAY include referenced pieces of context as either `resource` or `resource_link` content blocks. When available, `resource` is preferred as it avoids extra round-trips and allows the message to include pieces of context from sources the agent may not have access to. **sessionId** `[SessionId](#sessionid)` *required* The ID of the session to send this user message to #### PromptResponse Response from processing a user prompt. See protocol docs: [Check for Completion](https://agentclientprotocol.com/protocol/v1/prompt-turn#4-check-for-completion) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **stopReason** `[StopReason](#stopreason)` *required* Indicates why the agent stopped processing the turn. ### session/resume Resumes an existing session without returning previous messages. This method is only available if the agent advertises the `sessionCapabilities.resume` capability. The agent should resume the session context, allowing the conversation to continue without replaying the message history (unlike `session/load`). #### ResumeSessionRequest Request parameters for resuming an existing session. Resumes an existing session without returning previous messages (unlike `session/load`). This is useful for agents that can resume sessions but don't implement full session loading. Only available if the Agent supports the `sessionCapabilities.resume` capability. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **additionalDirectories** `"string"[]` Additional workspace roots to activate for this session. Each path must be absolute. When omitted or empty, no additional roots are activated. When non-empty, this is the complete resulting additional-root list for the resumed session. It may differ from any previously used or reported list as long as the request `cwd` matches the session's `cwd`. **cwd** `string` *required* The working directory for this session. Must be an absolute path. **mcpServers** `[McpServer\[\]](#mcpserver)` List of MCP servers to connect to for this session. **sessionId** `[SessionId](#sessionid)` *required* The ID of the session to resume. **systemPrompt** `[SystemPrompt](#systemprompt) | null` System-level instructions for the resumed session. Optional. Omitted and `null` are equivalent. The Agent may then keep a system prompt it stored with the session or use its default instructions. Clients MUST only send this when the Agent advertises `sessionCapabilities.systemPrompt`, and SHOULD send the same value they used when the session was created. #### ResumeSessionResponse Response from resuming an existing session. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **configOptions** `[SessionConfigOption\[\]](#sessionconfigoption) | null` Initial session configuration options if supported by the Agent. **modes** `[SessionModeState](#sessionmodestate) | null` Initial mode state if supported by the Agent See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/session-modes) ### session/set\_config\_option Sets the current value for a session configuration option. #### SetSessionConfigOptionRequest Request parameters for setting a session configuration option. **Type:** Union **Shared properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **configId** `[SessionConfigId](#sessionconfigid)` *required* The ID of the configuration option to set. **sessionId** `[SessionId](#sessionid)` *required* The ID of the session to set the configuration option for. **Variants:** **boolean** `object` A boolean value (`type: "boolean"`). **Properties** **type** `string` *required* The discriminator value. Must be `"boolean"`. **value** `boolean` *required* The boolean value. **value\_id** `object` A `SessionConfigValueId` string value. This is the default when `type` is absent on the wire. Unknown `type` values with string payloads also gracefully deserialize into this variant. **Properties** **value** `[SessionConfigValueId](#sessionconfigvalueid)` *required* The value ID. #### SetSessionConfigOptionResponse Response to `session/set_config_option` method. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **configOptions** `[SessionConfigOption\[\]](#sessionconfigoption)` *required* The full set of configuration options and their current values. ### session/set\_mode Sets the current mode for a session. Allows switching between different agent modes (e.g., "ask", "architect", "code") that affect system prompts, tool availability, and permission behaviors. The mode must be one of the modes advertised in `availableModes` during session creation or loading. Agents may also change modes autonomously and notify the client via `current_mode_update` notifications. This method can be called at any time during a session, whether the Agent is idle or actively generating a response. See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/session-modes) #### SetSessionModeRequest Request parameters for setting a session mode. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **modeId** `[SessionModeId](#sessionmodeid)` *required* The ID of the mode to set. **sessionId** `[SessionId](#sessionid)` *required* The ID of the session to set the mode for. #### SetSessionModeResponse Response to `session/set_mode` method. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) ## Client Defines the interface that ACP-compliant clients must implement. Clients are typically code editors (IDEs, text editors) that provide the interface between users and AI agents. They manage the environment, handle user interactions, and control access to resources. ### elicitation/complete Notification that a URL-based elicitation has completed. See protocol docs: [Elicitation](https://agentclientprotocol.com/protocol/v1/elicitation#url-completion) #### CompleteElicitationNotification Notification sent by the agent when a URL-based elicitation is complete. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. Optional. Omitted and `null` are equivalent and mean no metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **elicitationId** `[ElicitationId](#elicitationid)` *required* The ID of the elicitation that completed. ### elicitation/create Requests structured user input via a form or URL. See protocol docs: [Elicitation](https://agentclientprotocol.com/protocol/v1/elicitation) #### CreateElicitationRequest Request from the agent to elicit structured user input. The agent sends this to the client to request information from the user, either via a form or by directing them to a URL. Elicitations are tied to a session (optionally a tool call) or a request. **Type:** Union **Shared properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. Optional. Omitted and `null` are equivalent and mean no metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **message** `string` *required* A human-readable message describing what input is needed. **Variants:** **form** `object` Form-based elicitation where the client renders a form from the provided schema. **Properties** **mode** `string` *required* The discriminator value. Must be `"form"`. **requestedSchema** `[ElicitationSchema](#elicitationschema)` *required* A JSON Schema describing the form fields to present to the user. **Alternatives (`anyOf`):** **Session** Tied to a session, optionally to a specific tool call within that session. **Properties** **sessionId** `[SessionId](#sessionid)` *required* The session this elicitation is tied to. **toolCallId** `[ToolCallId](#toolcallid) | null` Optional tool call within the session. Optional. Omitted and `null` are equivalent and mean the elicitation is scoped to the session without a specific tool call. **Request** Tied to a specific JSON-RPC request outside of a session (e.g., during auth/configuration phases before any session is started). **Properties** **requestId** `[RequestId](#requestid)` *required* The request this elicitation is tied to. **url** `object` URL-based elicitation where the client directs the user to a URL. **Properties** **elicitationId** `[ElicitationId](#elicitationid)` *required* The unique identifier for this elicitation. **mode** `string` *required* The discriminator value. Must be `"url"`. **url** `string` *required* The URL to direct the user to. * Format: `uri` **Alternatives (`anyOf`):** **Session** Tied to a session, optionally to a specific tool call within that session. **Properties** **sessionId** `[SessionId](#sessionid)` *required* The session this elicitation is tied to. **toolCallId** `[ToolCallId](#toolcallid) | null` Optional tool call within the session. Optional. Omitted and `null` are equivalent and mean the elicitation is scoped to the session without a specific tool call. **Request** Tied to a specific JSON-RPC request outside of a session (e.g., during auth/configuration phases before any session is started). **Properties** **requestId** `[RequestId](#requestid)` *required* The request this elicitation is tied to. **other** `object` Custom or future elicitation mode. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Clients that do not understand this mode should preserve the raw payload when storing, replaying, proxying, or forwarding elicitation requests. They MUST NOT render it as a known elicitation mode. **Properties** **mode** `string` *required* Custom or future elicitation mode. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. **Alternatives (`anyOf`):** **Session** Tied to a session, optionally to a specific tool call within that session. **Properties** **sessionId** `[SessionId](#sessionid)` *required* The session this elicitation is tied to. **toolCallId** `[ToolCallId](#toolcallid) | null` Optional tool call within the session. Optional. Omitted and `null` are equivalent and mean the elicitation is scoped to the session without a specific tool call. **Request** Tied to a specific JSON-RPC request outside of a session (e.g., during auth/configuration phases before any session is started). **Properties** **requestId** `[RequestId](#requestid)` *required* The request this elicitation is tied to. #### CreateElicitationResponse Response from the client to an elicitation request. **Type:** Union **Shared properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. Optional. Omitted and `null` are equivalent and mean no metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **Variants:** **accept** `object` The user accepted and provided content. **Properties** **action** `string` *required* The discriminator value. Must be `"accept"`. **content** `object | null` The user-provided content, if any, as an object matching the requested schema. **decline** `object` The user declined the elicitation. **Properties** **action** `string` *required* The discriminator value. Must be `"decline"`. **cancel** `object` The elicitation was cancelled. **Properties** **action** `string` *required* The discriminator value. Must be `"cancel"`. **other** `object` Custom or future elicitation action. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Agents that do not understand this action should preserve the raw payload when storing, replaying, proxying, or forwarding elicitation responses. They MUST NOT treat it as a known elicitation action. **Properties** **action** `string` *required* Custom or future elicitation action. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ### fs/read\_text\_file Reads content from a text file in the client's file system. Only available if the client advertises the `fs.readTextFile` capability. Allows the agent to access file contents within the client's environment. See protocol docs: [Client](https://agentclientprotocol.com/protocol/v1/overview#client) #### ReadTextFileRequest Request to read content from a text file. Only available if the client supports the `fs.readTextFile` capability. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **limit** `integer | null` Maximum number of lines to read. * Minimum: `0` **line** `integer | null` Line number to start reading from (1-based). * Minimum: `0` **path** `string` *required* Absolute path to the file to read. **sessionId** `[SessionId](#sessionid)` *required* The session ID for this request. #### ReadTextFileResponse Response containing the contents of a text file. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **content** `string` *required* Content payload returned by this response. ### fs/write\_text\_file Writes content to a text file in the client's file system. Only available if the client advertises the `fs.writeTextFile` capability. Allows the agent to create or modify files within the client's environment. See protocol docs: [Client](https://agentclientprotocol.com/protocol/v1/overview#client) #### WriteTextFileRequest Request to write content to a text file. Only available if the client supports the `fs.writeTextFile` capability. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **content** `string` *required* The text content to write to the file. **path** `string` *required* Absolute path to the file to write. **sessionId** `[SessionId](#sessionid)` *required* The session ID for this request. #### WriteTextFileResponse Response to `fs/write_text_file` **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) ### session/request\_permission Requests permission from the user for a tool call operation. Called by the agent when it needs user authorization before executing a potentially sensitive operation. The client should present the options to the user and return their decision. If the client cancels the prompt turn via `session/cancel`, it MUST respond to this request with the `cancelled` outcome. See protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/v1/tool-calls#requesting-permission) #### RequestPermissionRequest Request for user permission to execute a tool call. Sent when the agent needs authorization before performing a sensitive operation. See protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/v1/tool-calls#requesting-permission) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **options** `[PermissionOption\[\]](#permissionoption)` *required* Available permission options for the user to choose from. **sessionId** `[SessionId](#sessionid)` *required* The session ID for this request. **toolCall** `[ToolCallUpdate](#toolcallupdate)` *required* Details about the tool call requiring permission. #### RequestPermissionResponse Response to a permission request. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **outcome** `[RequestPermissionOutcome](#requestpermissionoutcome)` *required* The user's decision on the permission request. ### session/update Handles session update notifications from the agent. This is a notification endpoint (no response expected) that receives real-time updates about session progress, including message chunks, tool calls, and execution plans. Note: Clients SHOULD continue accepting tool call updates even after sending a `session/cancel` notification, as the agent may send final updates before responding with the cancelled stop reason. See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/v1/prompt-turn#3-agent-reports-output) #### SessionNotification Notification containing a session update from the agent. Used to stream real-time progress and results during prompt processing. See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/v1/prompt-turn#3-agent-reports-output) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **sessionId** `[SessionId](#sessionid)` *required* The ID of the session this update pertains to. **update** `[SessionUpdate](#sessionupdate)` *required* The actual update content. ### terminal/create Executes a command in a new terminal Only available if the `terminal` Client capability is set to `true`. Returns a `TerminalId` that can be used with other terminal methods to get the current output, wait for exit, and kill the command. The `TerminalId` can also be used to embed the terminal in a tool call by using `terminal` tool call content. The Agent is responsible for releasing the terminal by using the `terminal/release` method. See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/v1/terminals) #### CreateTerminalRequest Request to create a new terminal and execute a command. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **args** `"string"[]` Array of command arguments. **command** `string` *required* The command to execute. **cwd** `string | null` Working directory for the command. Must be an absolute path. **env** `[EnvVariable\[\]](#envvariable)` Environment variables for the command. **outputByteLimit** `integer | null` Maximum number of output bytes to retain. When the limit is exceeded, the Client truncates from the beginning of the output to stay within the limit. The Client MUST ensure truncation happens at a character boundary to maintain valid string output, even if this means the retained output is slightly less than the specified limit. * Minimum: `0` **sessionId** `[SessionId](#sessionid)` *required* The session ID for this request. #### CreateTerminalResponse Response containing the ID of the created terminal. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **terminalId** `[TerminalId](#terminalid)` *required* The unique identifier for the created terminal. ### terminal/kill Kills the terminal command without releasing the terminal While `terminal/release` will also kill the command, this method will keep the `TerminalId` valid so it can be used with other methods. This method can be helpful when implementing command timeouts which terminate the command as soon as elapsed, and then get the final output so it can be sent to the model. Note: Call `terminal/release` when `TerminalId` is no longer needed. See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/v1/terminals) #### KillTerminalRequest Request to kill a terminal without releasing it. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **sessionId** `[SessionId](#sessionid)` *required* The session ID for this request. **terminalId** `[TerminalId](#terminalid)` *required* The ID of the terminal to kill. #### KillTerminalResponse Response to `terminal/kill` method **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) ### terminal/output Gets the terminal output and exit status Returns the current content in the terminal without waiting for the command to exit. If the command has already exited, the exit status is included. See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/v1/terminals) #### TerminalOutputRequest Request to get the current output and status of a terminal. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **sessionId** `[SessionId](#sessionid)` *required* The session ID for this request. **terminalId** `[TerminalId](#terminalid)` *required* The ID of the terminal to get output from. #### TerminalOutputResponse Response containing the terminal output and exit status. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **exitStatus** `[TerminalExitStatus](#terminalexitstatus) | null` Exit status if the command has completed. **output** `string` *required* The terminal output captured so far. **truncated** `boolean` *required* Whether the output was truncated due to byte limits. ### terminal/release Releases a terminal The command is killed if it hasn't exited yet. Use `terminal/wait_for_exit` to wait for the command to exit before releasing the terminal. After release, the `TerminalId` can no longer be used with other `terminal/*` methods, but tool calls that already contain it, continue to display its output. The `terminal/kill` method can be used to terminate the command without releasing the terminal, allowing the Agent to call `terminal/output` and other methods. See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/v1/terminals) #### ReleaseTerminalRequest Request to release a terminal and free its resources. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **sessionId** `[SessionId](#sessionid)` *required* The session ID for this request. **terminalId** `[TerminalId](#terminalid)` *required* The ID of the terminal to release. #### ReleaseTerminalResponse Response to terminal/release method **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) ### terminal/wait\_for\_exit Waits for the terminal command to exit and return its exit status See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/v1/terminals) #### WaitForTerminalExitRequest Request to wait for a terminal command to exit. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **sessionId** `[SessionId](#sessionid)` *required* The session ID for this request. **terminalId** `[TerminalId](#terminalid)` *required* The ID of the terminal to wait for. #### WaitForTerminalExitResponse Response containing the exit status of a terminal command. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **exitCode** `integer | null` The process exit code (may be null if terminated by signal). * Minimum: `0` **signal** `string | null` The signal that terminated the process (may be null if exited normally). ## Protocol Level Defines the interface that ACP-compliant agents and clients must both implement. Notifications whose methods start with '$/' are messages which are protocol implementation dependent and might not be implementable in all clients or agents. For example if the implementation uses a single threaded synchronous programming language then there is little it can do to react to a `$/cancel\_request\` notification. If an agent or client receives notifications starting with '\$/' it is free to ignore the notification. ### \$/cancel\_request Cancels an ongoing request. This is a notification sent by the side that sent a request to cancel that request. Upon receiving this notification, the receiver: 1. MAY cancel the corresponding request activity and all nested activities 2. MAY send any pending notifications. 3. MUST send one of these responses for the original request: * Valid response with appropriate data (partial results or cancellation marker) * Error response with code `-32800` (Cancelled) See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v1/cancellation) #### CancelRequestNotification Notification to cancel an ongoing request. See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v1/cancellation) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **requestId** `[RequestId](#requestid)` *required* The ID of the request to cancel. ## AgentAuthCapabilities Authentication-related capabilities supported by the agent. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **logout** `[LogoutCapabilities](#logoutcapabilities) | null` Whether the agent supports the logout method. Optional. Omitted or `null` both mean the agent does not advertise support. Supplying `\{\}` means the agent supports the logout method. ## AgentCapabilities Capabilities supported by the agent. Advertised during initialization to inform the client about available features and content types. See protocol docs: [Agent Capabilities](https://agentclientprotocol.com/protocol/v1/initialization#agent-capabilities) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **auth** `[AgentAuthCapabilities](#agentauthcapabilities)` Authentication-related capabilities supported by the agent. * Default: `{}` **loadSession** `boolean` Whether the agent supports `session/load`. * Default: `false` **mcpCapabilities** `[McpCapabilities](#mcpcapabilities)` MCP capabilities supported by the agent. * Default: `{"http":false,"sse":false}` **promptCapabilities** `[PromptCapabilities](#promptcapabilities)` Prompt capabilities supported by the agent. * Default: `{"image":false,"audio":false,"embeddedContext":false}` **sessionCapabilities** `[SessionCapabilities](#sessioncapabilities)` Session lifecycle and prompt capabilities advertised by the agent. * Default: `{}` ## Annotations Optional annotations for the client. The client can use annotations to inform how objects are used or displayed **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **audience** `[Role\[\]](#role) | null` Intended recipients for this content, such as the user or assistant. **lastModified** `string | null` Timestamp indicating when the underlying resource was last modified. **priority** `number | null` Relative importance of this content when clients choose what to surface. ## AudioContent Audio provided to or from an LLM. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **annotations** `[Annotations](#annotations) | null` Optional annotations that help clients decide how to display or route this content. **data** `string` *required* Base64-encoded media payload. **mimeType** `string` *required* MIME type describing the encoded media payload. ## AuthCapabilities Authentication capabilities supported by the client. Advertised during initialization to inform the agent which authentication method types the client can handle. This governs opt-in types that require additional client-side support. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **terminal** `boolean` Whether the client supports `terminal` authentication methods. The client should set this to `true` only when it can reproduce the configured agent invocation in an interactive terminal. When `true`, the agent may include `terminal` entries in its authentication methods. * Default: `false` ## AuthMethod Describes an available authentication method. The `type` field acts as the discriminator in the serialized JSON form. When no `type` is present, the method is treated as `agent`. **Type:** Union **terminal** `object` Client runs the configured agent program as a separate interactive process, without passing this method to `authenticate`. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **args** `"string"[]` Additional arguments to append to the configured agent invocation for terminal auth. **description** `string | null` Optional human-readable description of this authentication method. **env** `object` Additional environment variables to set on the configured agent invocation for terminal auth. These values override same-named variables in the base launch configuration. **id** `[AuthMethodId](#authmethodid)` *required* Unique identifier for this authentication method. **name** `string` *required* Human-readable name of the authentication method. **type** `string` *required* The discriminator value. Must be `"terminal"`. **agent** Agent handles authentication itself through `authenticate`. This is the default when no `type` is specified. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **description** `string | null` Optional human-readable description of this authentication method. **id** `[AuthMethodId](#authmethodid)` *required* Unique identifier for this authentication method. **name** `string` *required* Human-readable name of the authentication method. ## AuthMethodAgent Agent handles authentication itself through `authenticate`. This is the default authentication method type. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **description** `string | null` Optional human-readable description of this authentication method. **id** `[AuthMethodId](#authmethodid)` *required* Unique identifier for this authentication method. **name** `string` *required* Human-readable name of the authentication method. ## AuthMethodId Typed identifier used for auth method values on the wire. **Type:** `string` ## AuthMethodTerminal Terminal-based authentication method. The client runs the configured agent program as a separate interactive process for the user to authenticate via a TUI. Agents MUST advertise this method only when the client enabled its terminal authentication capability. A zero exit status signals success. Any other termination signals failure. The client MUST NOT pass this method to `authenticate`. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **args** `"string"[]` Additional arguments to append to the configured agent invocation for terminal auth. **description** `string | null` Optional human-readable description of this authentication method. **env** `object` Additional environment variables to set on the configured agent invocation for terminal auth. These values override same-named variables in the base launch configuration. **id** `[AuthMethodId](#authmethodid)` *required* Unique identifier for this authentication method. **name** `string` *required* Human-readable name of the authentication method. ## AvailableCommand Information about a command. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **description** `string` *required* Human-readable description of what the command does. **input** `[AvailableCommandInput](#availablecommandinput) | null` Input for the command if required **name** `string` *required* Command name (e.g., `create_plan`, `research_codebase`). ## AvailableCommandInput The input specification for a command. All text that was typed after the command name is provided as input. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **hint** `string` *required* A hint to display when the input hasn't been provided yet ## AvailableCommandsUpdate Available commands are ready or have changed **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **availableCommands** `[AvailableCommand\[\]](#availablecommand)` *required* Commands the agent can execute ## BlobResourceContents Binary resource contents. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **blob** `string` *required* Base64-encoded bytes for a binary resource payload. **mimeType** `string | null` MIME type describing the encoded media payload. **uri** `string` *required* URI associated with this resource or media payload. ## BooleanConfigOptionCapabilities Capabilities for boolean session configuration options. Supplying `\{\}` means the client supports boolean session configuration options. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) ## BooleanPropertySchema Schema for boolean properties in an elicitation form. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. Optional. Omitted and `null` are equivalent and mean no metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **default** `boolean | null` Default value. Optional. Omitted and `null` are equivalent and mean no default value is provided. **description** `string | null` Human-readable description. Optional. Omitted and `null` are equivalent and mean no description is provided. **title** `string | null` Optional title for the property. Optional. Omitted and `null` are equivalent and mean no title is provided. ## ClientCapabilities Capabilities supported by the client. Advertised during initialization to inform the agent about available features and methods. See protocol docs: [Client Capabilities](https://agentclientprotocol.com/protocol/v1/initialization#client-capabilities) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **auth** `[AuthCapabilities](#authcapabilities)` Authentication capabilities supported by the client. Determines which authentication method types the agent may include in its `InitializeResponse`. * Default: `{"terminal":false}` **elicitation** `[ElicitationCapabilities](#elicitationcapabilities) | null` Elicitation capabilities supported by the client. Determines which elicitation modes the agent may use. Optional. Omitted or `null` both mean the client does not advertise elicitation support. **fs** `[FileSystemCapabilities](#filesystemcapabilities)` File system capabilities supported by the client. Determines which file operations the agent can request. * Default: `{"readTextFile":false,"writeTextFile":false}` **session** `[ClientSessionCapabilities](#clientsessioncapabilities) | null` Session-related capabilities supported by the client. Optional. Omitted or `null` both mean the client does not advertise any session-related extensions. **terminal** `boolean` Whether the Client support all `terminal/*` methods. * Default: `false` ## ClientSessionCapabilities Session-related capabilities supported by the client. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **compaction** `[CompactionCapabilities](#compactioncapabilities) | null` Support for ID-addressed context compaction updates. Omitted or `null` means unsupported. `\{\}` advertises the complete compaction contract. **configOptions** `[SessionConfigOptionsCapabilities](#sessionconfigoptionscapabilities) | null` Config option capabilities supported by the client. Omitted or `null` both mean the client does not advertise support for any config option extensions. **notices** `[NoticeCapabilities](#noticecapabilities) | null` Support for live user-facing `notice` session updates. Optional. Omitted or `null` both mean the client does not advertise support. Supplying `\{\}` means the client can present notices to the user. ## CompactionCapabilities Client support for ID-addressed context compaction updates. **Type:** `object` ## CompactionId Unique identifier for a context compaction within a session. **Type:** `string` ## CompactionStatus Lifecycle state of a context compaction. **Type:** Union **in\_progress** `string` Compaction has started and has not finished. **completed** `string` Compaction finished successfully. **failed** `string` Compaction finished unsuccessfully. **cancelled** `string` Compaction was cancelled before it finished. **other** `string` Custom or future compaction status. Values beginning with `_` are reserved for implementation-specific extensions. Other unknown values are reserved for future ACP statuses. ## CompactionSummaryChunk A content block appended to a compaction's summary. A first-seen ID creates an in-progress compaction. Chunks append in receive order. Agents MUST only send this update when the Client advertised the `session.compaction` Client capability. **Type:** Object **Properties:** **\_meta** `object | null` Metadata scoped to this chunk. Omission and `null` both mean absent. **compactionId** `[CompactionId](#compactionid)` *required* ID of the compaction whose summary receives this content. **content** `[ContentBlock](#contentblock)` *required* One content block to append. ## CompactionUpdate A context compaction upsert. The first notification fixes the compaction's timeline position. Later updates with the same ID patch that entity in place. Agents MUST only send this update when the Client advertised the `session.compaction` Client capability. `summary`, `error`, and `_meta` have patch semantics: omission leaves the stored value unchanged, `null` clears it, and a concrete value replaces it. `summary: []` also clears the summary. **Type:** Object **Properties:** **\_meta** `object | null` Extensible metadata patch for this compaction. **compactionId** `[CompactionId](#compactionid)` *required* The Agent-owned ID of this compaction, unique within the session. **error** `string | null` Human-readable error details for the compaction. **status** `[CompactionStatus](#compactionstatus)` *required* Current lifecycle status. **summary** \`[ContentBlock\[\]](#contentblock) \| null\` Complete replacement user-displayable summary content for the compaction. ## ConfigOptionUpdate Session configuration options have been updated. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **configOptions** `[SessionConfigOption\[\]](#sessionconfigoption)` *required* The full set of configuration options and their current values. ## Content Standard content block (text, images, resources). **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **content** `[ContentBlock](#contentblock)` *required* The actual content block. ## ContentBlock Content blocks represent displayable information in the Agent Client Protocol. Content blocks appear in: * User prompts sent via `session/prompt` * Language model output streamed through `session/update` notifications * Progress updates and results from tool calls This structure is compatible with the Model Context Protocol (MCP), so agents can forward content from MCP tool outputs without transformation. See protocol docs: [Content](https://agentclientprotocol.com/protocol/v1/content) **Type:** Union **text** `object` Text content. May be plain text or formatted with Markdown. All agents MUST support text content blocks in prompts. Clients SHOULD render this text as Markdown. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **annotations** `[Annotations](#annotations) | null` Optional annotations that help clients decide how to display or route this content. **text** `string` *required* Text payload carried by this content block. **type** `string` *required* The discriminator value. Must be `"text"`. **image** `object` Images for visual context or analysis. Requires the `image` prompt capability when included in prompts. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **annotations** `[Annotations](#annotations) | null` Optional annotations that help clients decide how to display or route this content. **data** `string` *required* Base64-encoded media payload. **mimeType** `string` *required* MIME type describing the encoded media payload. **type** `string` *required* The discriminator value. Must be `"image"`. **uri** `string | null` URI associated with this resource or media payload. **audio** `object` Audio data for transcription or analysis. Requires the `audio` prompt capability when included in prompts. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **annotations** `[Annotations](#annotations) | null` Optional annotations that help clients decide how to display or route this content. **data** `string` *required* Base64-encoded media payload. **mimeType** `string` *required* MIME type describing the encoded media payload. **type** `string` *required* The discriminator value. Must be `"audio"`. **resource\_link** `object` References to resources that the agent can access. All agents MUST support resource links in prompts. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **annotations** `[Annotations](#annotations) | null` Optional annotations that help clients decide how to display or route this content. **description** `string | null` Optional human-readable details shown with this protocol object. **mimeType** `string | null` MIME type describing the encoded media payload. **name** `string` *required* Human-readable name shown for this protocol object. **size** `integer | null` Optional size of the linked resource in bytes, if known. **title** `string | null` Optional display title for end-user UI. **type** `string` *required* The discriminator value. Must be `"resource_link"`. **uri** `string` *required* URI associated with this resource or media payload. **resource** `object` Complete resource contents embedded directly in the message. Preferred for including context as it avoids extra round-trips. Requires the `embeddedContext` prompt capability when included in prompts. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **annotations** `[Annotations](#annotations) | null` Optional annotations that help clients decide how to display or route this content. **resource** `[EmbeddedResourceResource](#embeddedresourceresource)` *required* Embedded resource payload, either text or binary data. **type** `string` *required* The discriminator value. Must be `"resource"`. ## ContentChunk A streamed item of content **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **content** `[ContentBlock](#contentblock)` *required* A single item of content **messageId** `[MessageId](#messageid) | null` A unique identifier for the message this chunk belongs to. All chunks belonging to the same message share the same `messageId`. A change in `messageId` indicates a new message has started. ## Cost Cost information for a session. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **amount** `number` *required* Total cumulative cost for session. **currency** `string` *required* Unit of `amount`: an ISO 4217 currency code (e.g., "USD", "EUR") for money, or another unit such as "credits". ## CurrentModeUpdate The current mode of the session has changed See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/session-modes) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **currentModeId** `[SessionModeId](#sessionmodeid)` *required* The ID of the current mode ## Diff A diff representing file modifications. Shows changes to files in a format suitable for display in the client UI. See protocol docs: [Content](https://agentclientprotocol.com/protocol/v1/tool-calls#content) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **newText** `string` *required* The new content after modification. **oldText** `string | null` The original content (omitted or `null` for new files). **path** `string` *required* The absolute file path being modified. ## ElicitationAcceptAction The user accepted the elicitation and provided content. **Type:** Object **Properties:** **content** `object | null` The user-provided content, if any, as an object matching the requested schema. ## ElicitationCapabilities Elicitation capabilities supported by the client. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. Optional. Omitted and `null` are equivalent and mean no metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **form** `[ElicitationFormCapabilities](#elicitationformcapabilities) | null` Whether the client supports form-based elicitation. Optional. Omitted and `null` are equivalent and mean form support is not advertised. Supplying `\{\}` explicitly advertises form support. **url** `[ElicitationUrlCapabilities](#elicitationurlcapabilities) | null` Whether the client supports URL-based elicitation. Optional. Omitted or `null` both mean the client does not advertise support. Supplying `\{\}` means the client supports URL-based elicitation. ## ElicitationContentValue Allowed wire representations for `ElicitationContentValue`. **Type:** Union **String** `string` String value accepted in elicitation response content. **Integer** `int64` Integer value accepted in elicitation response content. **Number** `double` Number value accepted in elicitation response content. **Boolean** `boolean` Boolean value accepted in elicitation response content. **StringArray** `array` String array value accepted in elicitation response content. ## ElicitationFormCapabilities Form-based elicitation capabilities. Supplying `\{\}` means the client supports form-based elicitation. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. Optional. Omitted and `null` are equivalent and mean no metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) ## ElicitationFormMode Form-based elicitation mode where the client renders a form from the provided schema. **Type:** Union **Shared properties:** **requestedSchema** `[ElicitationSchema](#elicitationschema)` *required* A JSON Schema describing the form fields to present to the user. **Variants:** **Session** Tied to a session, optionally to a specific tool call within that session. **Properties** **sessionId** `[SessionId](#sessionid)` *required* The session this elicitation is tied to. **toolCallId** `[ToolCallId](#toolcallid) | null` Optional tool call within the session. Optional. Omitted and `null` are equivalent and mean the elicitation is scoped to the session without a specific tool call. **Request** Tied to a specific JSON-RPC request outside of a session (e.g., during auth/configuration phases before any session is started). **Properties** **requestId** `[RequestId](#requestid)` *required* The request this elicitation is tied to. ## ElicitationId Unique identifier for an elicitation. **Type:** `string` ## ElicitationPropertySchema Property schema for elicitation form fields. Each variant corresponds to a JSON Schema `"type"` value. Single-select enums use `type: "string"` with `enum` or `oneOf` set. Multi-select enums use `type: "array"`. **Type:** Union **string** `object` String property (or single-select enum when `enum`/`oneOf` is set). **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. Optional. Omitted and `null` are equivalent and mean no metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **default** `string | null` Default value. Optional. Omitted and `null` are equivalent and mean no default value is provided. **description** `string | null` Human-readable description. Optional. Omitted and `null` are equivalent and mean no description is provided. **enum** `"string"[] | null` Enum values for untitled single-select enums. Optional. Omitted and `null` are equivalent and mean no untitled single-select choices are declared by `enum`. **format** `[StringFormat](#stringformat) | null` String format. Optional. Omitted and `null` are equivalent and mean there is no format constraint. **maxLength** `integer | null` Maximum string length. Optional. Omitted and `null` are equivalent and mean there is no maximum length constraint. * Minimum: `0` **minLength** `integer | null` Minimum string length. Optional. Omitted and `null` are equivalent and mean there is no minimum length constraint. * Minimum: `0` **oneOf** `[EnumOption\[\]](#enumoption) | null` Titled enum options for titled single-select enums. Optional. Omitted and `null` are equivalent and mean no titled single-select choices are declared by `oneOf`. **pattern** `string | null` Pattern the string must match. Optional. Omitted and `null` are equivalent and mean there is no pattern constraint. **title** `string | null` Optional title for the property. Optional. Omitted and `null` are equivalent and mean no title is provided. **type** `string` *required* The discriminator value. Must be `"string"`. **number** `object` Number (floating-point) property. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. Optional. Omitted and `null` are equivalent and mean no metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **default** `number | null` Default value. Optional. Omitted and `null` are equivalent and mean no default value is provided. **description** `string | null` Human-readable description. Optional. Omitted and `null` are equivalent and mean no description is provided. **maximum** `number | null` Maximum value (inclusive). Optional. Omitted and `null` are equivalent and mean there is no inclusive upper bound. **minimum** `number | null` Minimum value (inclusive). Optional. Omitted and `null` are equivalent and mean there is no inclusive lower bound. **title** `string | null` Optional title for the property. Optional. Omitted and `null` are equivalent and mean no title is provided. **type** `string` *required* The discriminator value. Must be `"number"`. **integer** `object` Integer property. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. Optional. Omitted and `null` are equivalent and mean no metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **default** `integer | null` Default value. Optional. Omitted and `null` are equivalent and mean no default value is provided. **description** `string | null` Human-readable description. Optional. Omitted and `null` are equivalent and mean no description is provided. **maximum** `integer | null` Maximum value (inclusive). Optional. Omitted and `null` are equivalent and mean there is no inclusive upper bound. **minimum** `integer | null` Minimum value (inclusive). Optional. Omitted and `null` are equivalent and mean there is no inclusive lower bound. **title** `string | null` Optional title for the property. Optional. Omitted and `null` are equivalent and mean no title is provided. **type** `string` *required* The discriminator value. Must be `"integer"`. **boolean** `object` Boolean property. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. Optional. Omitted and `null` are equivalent and mean no metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **default** `boolean | null` Default value. Optional. Omitted and `null` are equivalent and mean no default value is provided. **description** `string | null` Human-readable description. Optional. Omitted and `null` are equivalent and mean no description is provided. **title** `string | null` Optional title for the property. Optional. Omitted and `null` are equivalent and mean no title is provided. **type** `string` *required* The discriminator value. Must be `"boolean"`. **array** `object` Multi-select array property. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. Optional. Omitted and `null` are equivalent and mean no metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **default** `"string"[] | null` Default selected values. Optional. Omitted and `null` are equivalent and mean no default selections are provided. **description** `string | null` Human-readable description. Optional. Omitted and `null` are equivalent and mean no description is provided. **items** `[MultiSelectItems](#multiselectitems)` *required* The items definition describing allowed values. **maxItems** `integer | null` Maximum number of items to select. Optional. Omitted and `null` are equivalent and mean there is no maximum selection count. * Minimum: `0` **minItems** `integer | null` Minimum number of items to select. Optional. Omitted and `null` are equivalent and mean there is no minimum selection count. * Minimum: `0` **title** `string | null` Optional title for the property. Optional. Omitted and `null` are equivalent and mean no title is provided. **type** `string` *required* The discriminator value. Must be `"array"`. **other** `object` Custom or future elicitation property schema. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Clients that do not understand this property schema type should preserve the raw schema when storing, replaying, proxying, or forwarding elicitation requests. They MUST NOT render it as a known input control. **Properties** **type** `string` *required* Custom or future elicitation property schema type. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## ElicitationRequestScope Request-scoped elicitation, tied to a specific JSON-RPC request outside of a session (e.g., during auth/configuration phases before any session is started). **Type:** Object **Properties:** **requestId** `[RequestId](#requestid)` *required* The request this elicitation is tied to. ## ElicitationSchema Type-safe elicitation schema for requesting structured user input. This represents a JSON Schema object with primitive-typed properties, as required by the elicitation specification. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. Optional. Omitted and `null` are equivalent and mean no metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **description** `string | null` Optional description of what this schema represents. Optional. Omitted and `null` are equivalent and mean no schema description is provided. **properties** `object` Property definitions (must be primitive types). * Default: `{}` **required** `"string"[] | null` List of required property names. Optional. Omitted and `null` are equivalent and mean no property names are required. **title** `string | null` Optional title for the schema. Optional. Omitted and `null` are equivalent and mean no title is provided. **type** `[ElicitationSchemaType](#elicitationschematype)` Type discriminator. Always `"object"`. * Default: `"object"` ## ElicitationSchemaType Type discriminator for elicitation schemas. **Type:** Union **object** `string` Object schema type. ## ElicitationSessionScope Session-scoped elicitation, optionally tied to a specific tool call. When `toolCallId` is set, the elicitation is tied to a specific tool call. This is useful when an agent receives an elicitation from an MCP server during a tool call and needs to redirect it to the user. **Type:** Object **Properties:** **sessionId** `[SessionId](#sessionid)` *required* The session this elicitation is tied to. **toolCallId** `[ToolCallId](#toolcallid) | null` Optional tool call within the session. Optional. Omitted and `null` are equivalent and mean the elicitation is scoped to the session without a specific tool call. ## ElicitationUrlCapabilities URL-based elicitation capabilities. Supplying `\{\}` means the client supports URL-based elicitation. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. Optional. Omitted and `null` are equivalent and mean no metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) ## ElicitationUrlMode URL-based elicitation mode where the client directs the user to a URL. **Type:** Union **Shared properties:** **elicitationId** `[ElicitationId](#elicitationid)` *required* The unique identifier for this elicitation. **url** `string` *required* The URL to direct the user to. * Format: `uri` **Variants:** **Session** Tied to a session, optionally to a specific tool call within that session. **Properties** **sessionId** `[SessionId](#sessionid)` *required* The session this elicitation is tied to. **toolCallId** `[ToolCallId](#toolcallid) | null` Optional tool call within the session. Optional. Omitted and `null` are equivalent and mean the elicitation is scoped to the session without a specific tool call. **Request** Tied to a specific JSON-RPC request outside of a session (e.g., during auth/configuration phases before any session is started). **Properties** **requestId** `[RequestId](#requestid)` *required* The request this elicitation is tied to. ## EmbeddedResource The contents of a resource, embedded into a prompt or tool call result. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **annotations** `[Annotations](#annotations) | null` Optional annotations that help clients decide how to display or route this content. **resource** `[EmbeddedResourceResource](#embeddedresourceresource)` *required* Embedded resource payload, either text or binary data. ## EmbeddedResourceResource Resource content that can be embedded in a message. **Type:** Union **TextResourceContents** Text resource contents embedded directly in the message. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **mimeType** `string | null` MIME type describing the encoded media payload. **text** `string` *required* Text payload carried by this content block. **uri** `string` *required* URI associated with this resource or media payload. **BlobResourceContents** Binary resource contents embedded directly in the message. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **blob** `string` *required* Base64-encoded bytes for a binary resource payload. **mimeType** `string | null` MIME type describing the encoded media payload. **uri** `string` *required* URI associated with this resource or media payload. ## EnumOption A titled enum option with a const value, human-readable title, and optional description. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. Optional. Omitted and `null` are equivalent and mean no metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **const** `string` *required* The constant value for this option. **description** `string | null` Human-readable description. Optional. Omitted and `null` are equivalent and mean no description is provided. **title** `string` *required* Human-readable title for this option. ## EnvVariable An environment variable to set when launching an MCP server. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **name** `string` *required* The name of the environment variable. **value** `string` *required* The value to set for the environment variable. ## Error JSON-RPC error object. Represents an error that occurred during method execution, following the JSON-RPC 2.0 error object specification with optional additional data. See protocol docs: [JSON-RPC Error Object](https://www.jsonrpc.org/specification#error_object) **Type:** Object **Properties:** **code** `[ErrorCode](#errorcode)` *required* A number indicating the error type that occurred. This must be an integer as defined in the JSON-RPC specification. **data** `object` Optional primitive or structured value that contains additional information about the error. This may include debugging information or context-specific details. **message** `string` *required* A string providing a short description of the error. The message should be limited to a concise single sentence. ## ErrorCode Predefined error codes for common JSON-RPC and ACP-specific errors. Standard errors use the JSON-RPC 2.0 codes. ACP-specific errors use the JSON-RPC server-error range (-32000 to -32099), and request cancellation uses -32800 from the range LSP reserves (-32899 to -32800). **Type:** Union **-32700** `int32` **Parse error**: Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text. **-32600** `int32` **Invalid request**: The JSON sent is not a valid Request object. **-32601** `int32` **Method not found**: The method does not exist or is not available. **-32602** `int32` **Invalid params**: Invalid method parameter(s). **-32603** `int32` **Internal error**: Internal JSON-RPC error. **-32800** `int32` **Request cancelled**: Execution of the method was aborted either due to a cancellation request from the caller or because of resource constraints or shutdown. **-32000** `int32` **Authentication required**: Authentication is required before this operation can be performed. **-32002** `int32` **Resource not found**: A given resource, such as a session or file, was not found. **Other** `int32` Other undefined error code. ## ExtNotification Allows either side to send an arbitrary notification that is not part of the ACP spec. Extension notifications provide a way to send one-way messages for custom functionality while maintaining protocol compatibility. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) ## ExtRequest Allows for sending an arbitrary request that is not part of the ACP spec. Extension methods provide a way to add custom functionality while maintaining protocol compatibility. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) ## ExtResponse Allows for sending an arbitrary response to an extension request that is not part of the ACP spec. Extension methods provide a way to add custom functionality while maintaining protocol compatibility. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) ## FileSystemCapabilities File system capabilities that a client may support. See protocol docs: [FileSystem](https://agentclientprotocol.com/protocol/v1/initialization#filesystem) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **readTextFile** `boolean` Whether the Client supports `fs/read_text_file` requests. * Default: `false` **writeTextFile** `boolean` Whether the Client supports `fs/write_text_file` requests. * Default: `false` ## HttpHeader An HTTP header to set when making requests to the MCP server. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **name** `string` *required* The name of the HTTP header. **value** `string` *required* The value to set for the HTTP header. ## ImageContent An image provided to or from an LLM. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **annotations** `[Annotations](#annotations) | null` Optional annotations that help clients decide how to display or route this content. **data** `string` *required* Base64-encoded media payload. **mimeType** `string` *required* MIME type describing the encoded media payload. **uri** `string | null` URI associated with this resource or media payload. ## Implementation Metadata about the implementation of the client or agent. Describes the name and version of an ACP implementation, with an optional title for UI representation. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **name** `string` *required* Intended for programmatic or logical use, but can be used as a display name fallback if title isn't present. **title** `string | null` Intended for UI and end-user contexts and optimized to be human-readable and easily understood. If not provided, the name should be used for display. **version** `string` *required* Version of the implementation. Can be displayed to the user or used for debugging or metrics purposes. (e.g. "1.0.0"). ## IntegerPropertySchema Schema for integer properties in an elicitation form. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. Optional. Omitted and `null` are equivalent and mean no metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **default** `integer | null` Default value. Optional. Omitted and `null` are equivalent and mean no default value is provided. **description** `string | null` Human-readable description. Optional. Omitted and `null` are equivalent and mean no description is provided. **maximum** `integer | null` Maximum value (inclusive). Optional. Omitted and `null` are equivalent and mean there is no inclusive upper bound. **minimum** `integer | null` Minimum value (inclusive). Optional. Omitted and `null` are equivalent and mean there is no inclusive lower bound. **title** `string | null` Optional title for the property. Optional. Omitted and `null` are equivalent and mean no title is provided. ## LogoutCapabilities Logout capabilities supported by the agent. Supplying `\{\}` means the agent supports the logout method. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) ## McpCapabilities MCP capabilities supported by the agent **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **http** `boolean` Agent supports `http` MCP servers. * Default: `false` **sse** `boolean` Agent supports `sse` MCP servers. * Default: `false` ## McpServer Configuration for connecting to an MCP (Model Context Protocol) server. MCP servers provide tools and context that the agent can use when processing prompts. See protocol docs: [MCP Servers](https://agentclientprotocol.com/protocol/v1/session-setup#mcp-servers) **Type:** Union **http** `object` HTTP transport configuration Only available when the Agent capabilities indicate `mcp_capabilities.http` is `true`. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **headers** `[HttpHeader\[\]](#httpheader)` *required* HTTP headers to set when making requests to the MCP server. **name** `string` *required* Human-readable name identifying this MCP server. **type** `string` *required* The discriminator value. Must be `"http"`. **url** `string` *required* URL to the MCP server. **sse** `object` SSE transport configuration Only available when the Agent capabilities indicate `mcp_capabilities.sse` is `true`. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **headers** `[HttpHeader\[\]](#httpheader)` *required* HTTP headers to set when making requests to the MCP server. **name** `string` *required* Human-readable name identifying this MCP server. **type** `string` *required* The discriminator value. Must be `"sse"`. **url** `string` *required* URL to the MCP server. **stdio** Stdio transport configuration All Agents MUST support this transport. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **args** `"string"[]` *required* Command-line arguments to pass to the MCP server. **command** `string` *required* Absolute path to the MCP server executable. **env** `[EnvVariable\[\]](#envvariable)` *required* Environment variables to set when launching the MCP server. **name** `string` *required* Human-readable name identifying this MCP server. ## McpServerHttp HTTP transport configuration for MCP. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **headers** `[HttpHeader\[\]](#httpheader)` *required* HTTP headers to set when making requests to the MCP server. **name** `string` *required* Human-readable name identifying this MCP server. **url** `string` *required* URL to the MCP server. ## McpServerSse SSE transport configuration for MCP. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **headers** `[HttpHeader\[\]](#httpheader)` *required* HTTP headers to set when making requests to the MCP server. **name** `string` *required* Human-readable name identifying this MCP server. **url** `string` *required* URL to the MCP server. ## McpServerStdio Stdio transport configuration for MCP. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **args** `"string"[]` *required* Command-line arguments to pass to the MCP server. **command** `string` *required* Absolute path to the MCP server executable. **env** `[EnvVariable\[\]](#envvariable)` *required* Environment variables to set when launching the MCP server. **name** `string` *required* Human-readable name identifying this MCP server. ## MessageId Unique identifier for a message within a session. **Type:** `string` ## MultiSelectItems Items for a multi-select (array) property schema. **Type:** Union **string** `object` Multi-select string items with plain string values. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. Optional. Omitted and `null` are equivalent and mean no metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **enum** `"string"[]` *required* Allowed enum values. **type** `string` *required* The discriminator value. Must be `"string"`. **other** `object` Custom or future typed multi-select items. **Properties** **type** `string` *required* Custom or future multi-select item type. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. **titled** Titled multi-select items with human-readable labels. As in MCP, titled items omit `type` and are identified by `anyOf`. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. Optional. Omitted and `null` are equivalent and mean no metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **anyOf** `[EnumOption\[\]](#enumoption)` *required* Titled enum options. ## MultiSelectPropertySchema Schema for multi-select (array) properties in an elicitation form. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. Optional. Omitted and `null` are equivalent and mean no metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **default** `"string"[] | null` Default selected values. Optional. Omitted and `null` are equivalent and mean no default selections are provided. **description** `string | null` Human-readable description. Optional. Omitted and `null` are equivalent and mean no description is provided. **items** `[MultiSelectItems](#multiselectitems)` *required* The items definition describing allowed values. **maxItems** `integer | null` Maximum number of items to select. Optional. Omitted and `null` are equivalent and mean there is no maximum selection count. * Minimum: `0` **minItems** `integer | null` Minimum number of items to select. Optional. Omitted and `null` are equivalent and mean there is no minimum selection count. * Minimum: `0` **title** `string | null` Optional title for the property. Optional. Omitted and `null` are equivalent and mean no title is provided. ## Notice Fire-and-forget information for the user. Notices are live events rather than session history. Agents must not rely on a notice being received, displayed, or seen by the user. Agents MUST only send notices when the Client advertised the `session.notices` Client capability. Otherwise, Agents may use an agent message when the information should still be surfaced to the user. See RFD: [Session Notices](https://agentclientprotocol.com/rfds/session-notices) **Type:** Object **Properties:** **\_meta** `object | null` Metadata scoped to this notice. Omitted and `null` are equivalent and mean no metadata was supplied. **description** `string | null` Optional plain-text detail or guidance. Omitted and `null` are equivalent and mean no description was supplied. **severity** `[NoticeSeverity](#noticeseverity)` *required* Presentation severity hint. **title** `string` *required* Required non-empty plain-text title that can stand alone. * Min length: `1` ## NoticeCapabilities Client support for presenting live notices to the user. **Type:** `object` ## NoticeSeverity Severity hint for a session notice. **Type:** Union **info** `string` Informational notice. **warning** `string` Warning notice. **error** `string` Error notice. **other** `string` Custom or future notice severity. Values beginning with `_` are reserved for implementation-specific extensions. Other unknown values are reserved for future ACP severities. ## NumberPropertySchema Schema for number (floating-point) properties in an elicitation form. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. Optional. Omitted and `null` are equivalent and mean no metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **default** `number | null` Default value. Optional. Omitted and `null` are equivalent and mean no default value is provided. **description** `string | null` Human-readable description. Optional. Omitted and `null` are equivalent and mean no description is provided. **maximum** `number | null` Maximum value (inclusive). Optional. Omitted and `null` are equivalent and mean there is no inclusive upper bound. **minimum** `number | null` Minimum value (inclusive). Optional. Omitted and `null` are equivalent and mean there is no inclusive lower bound. **title** `string | null` Optional title for the property. Optional. Omitted and `null` are equivalent and mean no title is provided. ## PermissionOption An option presented to the user when requesting permission. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **kind** `[PermissionOptionKind](#permissionoptionkind)` *required* Hint about the nature of this permission option. **name** `string` *required* Human-readable label to display to the user. **optionId** `[PermissionOptionId](#permissionoptionid)` *required* Unique identifier for this permission option. ## PermissionOptionId Unique identifier for a permission option. **Type:** `string` ## PermissionOptionKind The type of permission option being presented to the user. Helps clients choose appropriate icons and UI treatment. **Type:** Union **allow\_once** `string` Allow this operation only this time. **allow\_always** `string` Allow this operation and remember the choice. **reject\_once** `string` Reject this operation only this time. **reject\_always** `string` Reject this operation and remember the choice. ## Plan An execution plan for accomplishing complex tasks. Plans consist of multiple entries representing individual tasks or goals. Agents report plans to clients to provide visibility into their execution strategy. Plans can evolve during execution as the agent discovers new requirements or completes tasks. See protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/v1/agent-plan) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **entries** `[PlanEntry\[\]](#planentry)` *required* The list of tasks to be accomplished. When updating a plan, the agent must send a complete list of all entries with their current status. The client replaces the entire plan with each update. ## PlanEntry A single entry in the execution plan. Represents a task or goal that the assistant intends to accomplish as part of fulfilling the user's request. See protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/v1/agent-plan#plan-entries) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **content** `string` *required* Human-readable description of what this task aims to accomplish. **priority** `[PlanEntryPriority](#planentrypriority)` *required* The relative importance of this task. Used to indicate which tasks are most critical to the overall goal. **status** `[PlanEntryStatus](#planentrystatus)` *required* Current execution status of this task. ## PlanEntryPriority Priority levels for plan entries. Used to indicate the relative importance or urgency of different tasks in the execution plan. See protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/v1/agent-plan#plan-entries) **Type:** Union **high** `string` High priority task - critical to the overall goal. **medium** `string` Medium priority task - important but not critical. **low** `string` Low priority task - nice to have but not essential. ## PlanEntryStatus Status of a plan entry in the execution flow. Tracks the lifecycle of each task from planning through completion. See protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/v1/agent-plan#plan-entries) **Type:** Union **pending** `string` The task has not started yet. **in\_progress** `string` The task is currently being worked on. **completed** `string` The task has been successfully completed. ## PromptCapabilities Prompt capabilities supported by the agent in `session/prompt` requests. Baseline agent functionality requires support for `text` and `resource_link` content blocks in prompt requests. Other variants must be explicitly opted in to. Capabilities for different types of content in prompt requests. Indicates which content types beyond the baseline (text and resource links) the agent can process. See protocol docs: [Prompt Capabilities](https://agentclientprotocol.com/protocol/v1/initialization#prompt-capabilities) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **audio** `boolean` Agent supports `audio` content blocks. * Default: `false` **embeddedContext** `boolean` Agent supports embedded context in `session/prompt` requests. When enabled, the Client is allowed to include `resource` content blocks in prompt requests for pieces of context that are referenced in the message. * Default: `false` **image** `boolean` Agent supports `image` content blocks. * Default: `false` ## ProtocolVersion Protocol version identifier. This version is only bumped for breaking changes. Non-breaking changes should be introduced via capabilities. **Type:** `integer (uint16)` | Constraint | Value | | - | - | | Minimum | `0` | | Maximum | `65535` | ## RequestId JSON RPC Request Id An identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification. The value SHOULD normally not be Null \[1] and Numbers SHOULD NOT contain fractional parts \[2] The Server MUST reply with the same value in the Response object if included. This member is used to correlate the context between the two objects. \[1] The use of Null as a value for the id member in a Request object is discouraged, because this specification uses a value of Null for Responses with an unknown id. Also, because JSON-RPC 1.0 uses an id value of Null for Notifications this could cause confusion in handling. \[2] Fractional parts may be problematic, since many decimal fractions cannot be represented exactly as binary fractions. **Type:** Union **null** `null` The JSON-RPC `null` request id. **Number** `int64` A numeric JSON-RPC request id. **Str** `string` A string JSON-RPC request id. ## RequestPermissionOutcome The outcome of a permission request. **Type:** Union **cancelled** `object` The prompt turn was cancelled before the user responded. When a client sends a `session/cancel` notification to cancel an ongoing prompt turn, it MUST respond to all pending `session/request_permission` requests with this `cancelled` outcome. See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v1/prompt-turn#cancellation) **Properties** **outcome** `string` *required* The discriminator value. Must be `"cancelled"`. **selected** `object` The user selected one of the provided options. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **optionId** `[PermissionOptionId](#permissionoptionid)` *required* The ID of the option the user selected. **outcome** `string` *required* The discriminator value. Must be `"selected"`. ## ResourceLink A resource that the server is capable of reading, included in a prompt or tool call result. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **annotations** `[Annotations](#annotations) | null` Optional annotations that help clients decide how to display or route this content. **description** `string | null` Optional human-readable details shown with this protocol object. **mimeType** `string | null` MIME type describing the encoded media payload. **name** `string` *required* Human-readable name shown for this protocol object. **size** `integer | null` Optional size of the linked resource in bytes, if known. **title** `string | null` Optional display title for end-user UI. **uri** `string` *required* URI associated with this resource or media payload. ## Role The sender or recipient of messages and data in a conversation. **Type:** Union **assistant** `string` The assistant side of a conversation. **user** `string` The user side of a conversation. ## SelectedPermissionOutcome The user selected one of the provided options. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **optionId** `[PermissionOptionId](#permissionoptionid)` *required* The ID of the option the user selected. ## SessionAdditionalDirectoriesCapabilities Capabilities for additional session directories support. Supplying `\{\}` means the agent supports the `additionalDirectories` field on supported session lifecycle requests. Agents that also support `session/list` may return `SessionInfo.additionalDirectories` to report the complete ordered additional-root list associated with a listed session. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) ## SessionCapabilities Session capabilities supported by the agent. As a baseline, all Agents **MUST** support `session/new`, `session/prompt`, `session/cancel`, and `session/update`. Optionally, they **MAY** support other session methods and notifications by specifying additional capabilities. Note: `session/load` is still handled by the top-level `loadSession` capability. This will be unified in future versions of the protocol. See protocol docs: [Session Capabilities](https://agentclientprotocol.com/protocol/v1/initialization#session-capabilities) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **additionalDirectories** `[SessionAdditionalDirectoriesCapabilities](#sessionadditionaldirectoriescapabilities) | null` Whether the agent supports `additionalDirectories` on supported session lifecycle requests. Optional. Omitted or `null` both mean the agent does not advertise support. Supplying `\{\}` means the agent supports `additionalDirectories` on supported session lifecycle requests. Agents that also support `session/list` may return `SessionInfo.additionalDirectories` to report the complete ordered additional-root list associated with a listed session. **close** `[SessionCloseCapabilities](#sessionclosecapabilities) | null` Whether the agent supports `session/close`. Optional. Omitted or `null` both mean the agent does not advertise support. Supplying `\{\}` means the agent supports closing sessions. **delete** `[SessionDeleteCapabilities](#sessiondeletecapabilities) | null` Whether the agent supports `session/delete`. Optional. Omitted or `null` both mean the agent does not advertise support. Supplying `\{\}` means the agent supports deleting sessions from `session/list`. **list** `[SessionListCapabilities](#sessionlistcapabilities) | null` Whether the agent supports `session/list`. Optional. Omitted or `null` both mean the agent does not advertise support. Supplying `\{\}` means the agent supports listing sessions. **resume** `[SessionResumeCapabilities](#sessionresumecapabilities) | null` Whether the agent supports `session/resume`. Optional. Omitted or `null` both mean the agent does not advertise support. Supplying `\{\}` means the agent supports resuming sessions. **systemPrompt** `[SessionSystemPromptCapabilities](#sessionsystempromptcapabilities) | null` Whether the agent supports `systemPrompt` on session lifecycle requests. Optional. Omitted or `null` both mean the agent does not advertise support. Supplying `\{\}` means the agent supports `systemPrompt` in `append` mode. ## SessionCloseCapabilities Capabilities for the `session/close` method. Supplying `\{\}` means the agent supports closing sessions. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) ## SessionConfigBoolean A boolean on/off toggle session configuration option payload. **Type:** Object **Properties:** **currentValue** `boolean` *required* The current value of the boolean option. ## SessionConfigGroupId Unique identifier for a session configuration option value group. **Type:** `string` ## SessionConfigId Unique identifier for a session configuration option. **Type:** `string` ## SessionConfigOption A session configuration option selector and its current state. **Type:** Union **Shared properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **category** `[SessionConfigOptionCategory](#sessionconfigoptioncategory) | null` Optional semantic category for this option (UX only). **description** `string | null` Optional description for the Client to display to the user. **id** `[SessionConfigId](#sessionconfigid)` *required* Unique identifier for the configuration option. **name** `string` *required* Human-readable label for the option. **Variants:** **select** `object` Single-value selector (dropdown). **Properties** **currentValue** `[SessionConfigValueId](#sessionconfigvalueid)` *required* The currently selected value. **options** `[SessionConfigSelectOptions](#sessionconfigselectoptions)` *required* The set of selectable options. **type** `string` *required* The discriminator value. Must be `"select"`. **boolean** `object` Boolean on/off toggle. **Properties** **currentValue** `boolean` *required* The current value of the boolean option. **type** `string` *required* The discriminator value. Must be `"boolean"`. ## SessionConfigOptionCategory Semantic category for a session configuration option. This is intended to help Clients distinguish broadly common selectors (e.g. model selector vs session mode selector vs thought/reasoning level) for UX purposes (keyboard shortcuts, icons, placement). It MUST NOT be required for correctness. Clients MUST handle missing or unknown categories gracefully. Category names beginning with `_` are free for custom use, like other ACP extension methods. Category names that do not begin with `_` are reserved for the ACP spec. **Type:** Union **mode** `string` Session mode selector. **model** `string` Model selector. **model\_config** `string` Model-related configuration parameter. **thought\_level** `string` Thought/reasoning level selector. **other** `string` Unknown / uncategorized selector. ## SessionConfigOptionsCapabilities Session configuration option capabilities supported by the client. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **boolean** `[BooleanConfigOptionCapabilities](#booleanconfigoptioncapabilities) | null` Whether the client supports boolean session configuration options. Optional. Omitted or `null` both mean the client does not advertise support. Supplying `\{\}` means agents may include `type: "boolean"` entries in `configOptions`, and the client may send `session/set_config_option` requests with `type: "boolean"` and a boolean `value`. ## SessionConfigSelect A single-value selector (dropdown) session configuration option payload. **Type:** Object **Properties:** **currentValue** `[SessionConfigValueId](#sessionconfigvalueid)` *required* The currently selected value. **options** `[SessionConfigSelectOptions](#sessionconfigselectoptions)` *required* The set of selectable options. ## SessionConfigSelectGroup A group of possible values for a session configuration option. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **group** `[SessionConfigGroupId](#sessionconfiggroupid)` *required* Unique identifier for this group. **name** `string` *required* Human-readable label for this group. **options** `[SessionConfigSelectOption\[\]](#sessionconfigselectoption)` *required* The set of option values in this group. ## SessionConfigSelectOption A possible value for a session configuration option. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **description** `string | null` Optional description for this option value. **name** `string` *required* Human-readable label for this option value. **value** `[SessionConfigValueId](#sessionconfigvalueid)` *required* Unique identifier for this option value. ## SessionConfigSelectOptions Possible values for a session configuration option. **Type:** Union **Ungrouped** `array` A flat list of options with no grouping. **Grouped** `array` A list of options grouped under headers. ## SessionConfigValueId Unique identifier for a session configuration option value. **Type:** `string` ## SessionDeleteCapabilities Capabilities for the `session/delete` method. Supplying `\{\}` means the agent supports deleting sessions from `session/list`. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) ## SessionId A unique identifier for a conversation session between a client and agent. Each session has its own context, conversation history, and state, so one agent can run several independent sessions. See protocol docs: [Session ID](https://agentclientprotocol.com/protocol/v1/session-setup#session-id) **Type:** `string` ## SessionInfo Information about a session returned by session/list **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **additionalDirectories** `"string"[]` Additional workspace roots reported for this session. Each path must be absolute. When present, this is the complete ordered additional-root list reported by the Agent. Omitted and empty values are equivalent: the response reports no additional roots. **cwd** `string` *required* The working directory for this session. Must be an absolute path. **sessionId** `[SessionId](#sessionid)` *required* Unique identifier for the session **title** `string | null` Human-readable title for the session **updatedAt** `string | null` ISO 8601 timestamp of last activity ## SessionInfoUpdate Update to session metadata. All fields are optional to support partial updates. Agents send this notification to update session information like title or custom metadata. Clients can use it to keep session titles and state current. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **title** `string | null` Human-readable title for the session. Set to null to clear. **updatedAt** `string | null` ISO 8601 timestamp of last activity. Set to null to clear. ## SessionListCapabilities Capabilities for the `session/list` method. Supplying `\{\}` means the agent supports listing sessions. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) ## SessionMode A mode the agent can operate in. See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/session-modes) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **description** `string | null` Optional human-readable details shown with this protocol object. **id** `[SessionModeId](#sessionmodeid)` *required* Stable identifier used to refer to this protocol object in later messages. **name** `string` *required* Human-readable name shown for this protocol object. ## SessionModeId Unique identifier for a Session Mode. **Type:** `string` ## SessionModeState The set of modes and the one currently active. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **availableModes** `[SessionMode\[\]](#sessionmode)` *required* The set of modes that the Agent can operate in **currentModeId** `[SessionModeId](#sessionmodeid)` *required* The current mode the Agent is in. ## SessionResumeCapabilities Capabilities for the `session/resume` method. Supplying `\{\}` means the agent supports resuming sessions. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) ## SessionSystemPromptCapabilities Capabilities for client-provided system prompts. Supplying `\{\}` means the agent supports `systemPrompt` on session lifecycle requests in `append` mode. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **mode** `[SessionSystemPromptModeCapabilities](#sessionsystempromptmodecapabilities) | null` Delivery modes the agent supports in addition to `append`. Optional. Omitted or `null` both mean the agent supports only `append`. ## SessionSystemPromptModeCapabilities System prompt delivery modes the agent supports in addition to `append`. `append` has no entry because every agent advertising `sessionCapabilities.systemPrompt` supports it. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **override** `[SessionSystemPromptOverrideCapabilities](#sessionsystempromptoverridecapabilities) | null` Whether the agent supports `override` mode. Optional. Omitted or `null` both mean the agent does not advertise support. Supplying `\{\}` means the agent supports replacing its built-in default instructions with the client-provided system prompt. ## SessionSystemPromptOverrideCapabilities Capabilities for the `override` system prompt mode. Supplying `\{\}` means the agent supports replacing its built-in default instructions with the client-provided system prompt. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) ## SessionUpdate Different types of updates that can be sent during session processing. These updates provide real-time feedback about the agent's progress. See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/v1/prompt-turn#3-agent-reports-output) **Type:** Union **user\_message\_chunk** `object` A chunk of the user's message being streamed. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **content** `[ContentBlock](#contentblock)` *required* A single item of content **messageId** `[MessageId](#messageid) | null` A unique identifier for the message this chunk belongs to. All chunks belonging to the same message share the same `messageId`. A change in `messageId` indicates a new message has started. **sessionUpdate** `string` *required* The discriminator value. Must be `"user_message_chunk"`. **agent\_message\_chunk** `object` A chunk of the agent's response being streamed. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **content** `[ContentBlock](#contentblock)` *required* A single item of content **messageId** `[MessageId](#messageid) | null` A unique identifier for the message this chunk belongs to. All chunks belonging to the same message share the same `messageId`. A change in `messageId` indicates a new message has started. **sessionUpdate** `string` *required* The discriminator value. Must be `"agent_message_chunk"`. **agent\_thought\_chunk** `object` A chunk of the agent's internal reasoning being streamed. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **content** `[ContentBlock](#contentblock)` *required* A single item of content **messageId** `[MessageId](#messageid) | null` A unique identifier for the message this chunk belongs to. All chunks belonging to the same message share the same `messageId`. A change in `messageId` indicates a new message has started. **sessionUpdate** `string` *required* The discriminator value. Must be `"agent_thought_chunk"`. **tool\_call** `object` Notification that a new tool call has been initiated. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **content** `[ToolCallContent\[\]](#toolcallcontent)` Content produced by the tool call. **kind** `[ToolKind](#toolkind)` The category of tool being invoked. Helps clients choose appropriate icons and UI treatment. **locations** `[ToolCallLocation\[\]](#toolcalllocation)` File locations affected by this tool call. Enables "follow-along" features in clients. **name** `string | null` Programmatic name of the tool being invoked. This field is optional. Omitting it or sending `null` both mean that no tool name is available. **rawInput** `object` Raw input parameters sent to the tool. **rawOutput** `object` Raw output returned by the tool. **sessionUpdate** `string` *required* The discriminator value. Must be `"tool_call"`. **status** `[ToolCallStatus](#toolcallstatus)` Current execution status of the tool call. **title** `string` *required* Human-readable title describing what the tool is doing. **toolCallId** `[ToolCallId](#toolcallid)` *required* Unique identifier for this tool call within the session. **tool\_call\_update** `object` Update on the status or results of a tool call. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **content** `[ToolCallContent\[\]](#toolcallcontent) | null` Replace the content collection. **kind** `[ToolKind](#toolkind) | null` Update the tool kind. **locations** `[ToolCallLocation\[\]](#toolcalllocation) | null` Replace the locations collection. **name** `string | null` Update the programmatic name of the tool being invoked. This field is optional. Omitting it or sending `null` both mean that the existing name is left unchanged. **rawInput** `object` Update the raw input. **rawOutput** `object` Update the raw output. **sessionUpdate** `string` *required* The discriminator value. Must be `"tool_call_update"`. **status** `[ToolCallStatus](#toolcallstatus) | null` Update the execution status. **title** `string | null` Update the human-readable title. **toolCallId** `[ToolCallId](#toolcallid)` *required* The ID of the tool call being updated. **plan** `object` The agent's execution plan for complex tasks. See protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/v1/agent-plan) **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **entries** `[PlanEntry\[\]](#planentry)` *required* The list of tasks to be accomplished. When updating a plan, the agent must send a complete list of all entries with their current status. The client replaces the entire plan with each update. **sessionUpdate** `string` *required* The discriminator value. Must be `"plan"`. **available\_commands\_update** `object` Available commands are ready or have changed **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **availableCommands** `[AvailableCommand\[\]](#availablecommand)` *required* Commands the agent can execute **sessionUpdate** `string` *required* The discriminator value. Must be `"available_commands_update"`. **current\_mode\_update** `object` The current mode of the session has changed See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/session-modes) **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **currentModeId** `[SessionModeId](#sessionmodeid)` *required* The ID of the current mode **sessionUpdate** `string` *required* The discriminator value. Must be `"current_mode_update"`. **config\_option\_update** `object` Session configuration options have been updated. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **configOptions** `[SessionConfigOption\[\]](#sessionconfigoption)` *required* The full set of configuration options and their current values. **sessionUpdate** `string` *required* The discriminator value. Must be `"config_option_update"`. **session\_info\_update** `object` Session metadata has been updated (title, timestamps, custom metadata) **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **sessionUpdate** `string` *required* The discriminator value. Must be `"session_info_update"`. **title** `string | null` Human-readable title for the session. Set to null to clear. **updatedAt** `string | null` ISO 8601 timestamp of last activity. Set to null to clear. **usage\_update** `object` Context window and cost update for the session. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **cost** `[Cost](#cost) | null` Cumulative session cost (optional). **sessionUpdate** `string` *required* The discriminator value. Must be `"usage_update"`. **size** `uint64` *required* Total context window size in tokens. * Minimum: `0` **used** `uint64` *required* Tokens currently in context. * Minimum: `0` **notice** `object` Information for the user that is not part of session history. Agents MUST only send this update when the Client advertised the `session.notices` Client capability. **Properties** **\_meta** `object | null` Metadata scoped to this notice. Omitted and `null` are equivalent and mean no metadata was supplied. **description** `string | null` Optional plain-text detail or guidance. Omitted and `null` are equivalent and mean no description was supplied. **sessionUpdate** `string` *required* The discriminator value. Must be `"notice"`. **severity** `[NoticeSeverity](#noticeseverity)` *required* Presentation severity hint. **title** `string` *required* Required non-empty plain-text title that can stand alone. * Min length: `1` **compaction\_update** `object` A context compaction has been created or updated. Agents MUST only send this update when the Client advertised the `session.compaction` Client capability. **Properties** **\_meta** `object | null` Extensible metadata patch for this compaction. **compactionId** `[CompactionId](#compactionid)` *required* The Agent-owned ID of this compaction, unique within the session. **error** `string | null` Human-readable error details for the compaction. **sessionUpdate** `string` *required* The discriminator value. Must be `"compaction_update"`. **status** `[CompactionStatus](#compactionstatus)` *required* Current lifecycle status. **summary** \`[ContentBlock\[\]](#contentblock) \| null\` Complete replacement user-displayable summary content for the compaction. **compaction\_summary\_chunk** `object` A content block appended to a context compaction's retained summary. Agents MUST only send this update when the Client advertised the `session.compaction` Client capability. **Properties** **\_meta** `object | null` Metadata scoped to this chunk. Omission and `null` both mean absent. **compactionId** `[CompactionId](#compactionid)` *required* ID of the compaction whose summary receives this content. **content** `[ContentBlock](#contentblock)` *required* One content block to append. **sessionUpdate** `string` *required* The discriminator value. Must be `"compaction_summary_chunk"`. ## StopReason Reasons why an agent stops processing a prompt turn. See protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/v1/prompt-turn#stop-reasons) **Type:** Union **end\_turn** `string` The turn ended successfully. **max\_tokens** `string` The turn ended because the agent reached the maximum number of tokens. **max\_turn\_requests** `string` The turn ended because the agent reached the maximum number of allowed agent requests between user turns. **refusal** `string` The turn ended because the agent refused to continue. The user prompt and everything that comes after it won't be included in the next prompt, so this should be reflected in the UI. **cancelled** `string` The turn was cancelled by the client via `session/cancel`. This stop reason MUST be returned when the client sends a `session/cancel` notification, even if the cancellation causes exceptions in underlying operations. Agents should catch these exceptions and return this semantically meaningful response to confirm successful cancellation. ## StringFormat String format types for string properties in elicitation schemas. **Type:** Union **email** `string` Email address format. **uri** `string` URI format. **date** `string` Date format (YYYY-MM-DD). **date-time** `string` Date-time format (ISO 8601). ## StringMultiSelectItems String item schema for multi-select enum properties. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. Optional. Omitted and `null` are equivalent and mean no metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **enum** `"string"[]` *required* Allowed enum values. ## StringPropertySchema Schema for string properties in an elicitation form. When `enum` or `oneOf` is set, this represents a single-select enum with `"type": "string"`. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. Optional. Omitted and `null` are equivalent and mean no metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **default** `string | null` Default value. Optional. Omitted and `null` are equivalent and mean no default value is provided. **description** `string | null` Human-readable description. Optional. Omitted and `null` are equivalent and mean no description is provided. **enum** `"string"[] | null` Enum values for untitled single-select enums. Optional. Omitted and `null` are equivalent and mean no untitled single-select choices are declared by `enum`. **format** `[StringFormat](#stringformat) | null` String format. Optional. Omitted and `null` are equivalent and mean there is no format constraint. **maxLength** `integer | null` Maximum string length. Optional. Omitted and `null` are equivalent and mean there is no maximum length constraint. * Minimum: `0` **minLength** `integer | null` Minimum string length. Optional. Omitted and `null` are equivalent and mean there is no minimum length constraint. * Minimum: `0` **oneOf** `[EnumOption\[\]](#enumoption) | null` Titled enum options for titled single-select enums. Optional. Omitted and `null` are equivalent and mean no titled single-select choices are declared by `oneOf`. **pattern** `string | null` Pattern the string must match. Optional. Omitted and `null` are equivalent and mean there is no pattern constraint. **title** `string | null` Optional title for the property. Optional. Omitted and `null` are equivalent and mean no title is provided. ## SystemPrompt Client-provided system-level instructions for a session. Clients MUST only send this when the Agent advertises `sessionCapabilities.systemPrompt`. Agents that cannot apply it, for example because of an unadvertised mode or an unsupported content block type, MUST return an error instead of creating, loading, or resuming the session. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **content** `[ContentBlock\[\]](#contentblock)` *required* The system prompt content. Agents advertising the capability MUST accept `text` content blocks. Clients MUST NOT send other content block types until a future capability allows them, and Agents MUST return an error for content blocks they do not support. Clients MUST NOT send an empty array. Agents MAY reject one with `-32602` without creating, loading, or resuming the session. **mode** `[SystemPromptMode](#systempromptmode)` *required* How the Agent combines `content` with its own instructions. Required. Agents MUST return an error for a mode they do not support rather than treating it as `append` or `override`. ## SystemPromptMode How the Agent combines a client-provided system prompt with its own instructions. Unknown modes are preserved so they can be stored, proxied, or forwarded. An Agent MUST return an error for a mode it does not support rather than treating it as `append` or `override`. **Type:** Union **append** `string` Add the content to the Agent's own instructions rather than replacing them. Every Agent that advertises `sessionCapabilities.systemPrompt` supports this mode. Agents SHOULD give the content system-level precedence, for example in the model's system prompt or developer instructions rather than in user-turn content. Where it is placed and how it is formatted is implementation-defined. **override** `string` Replace the Agent's built-in default instructions with the content. This does not change tool availability, MCP servers, permissions, or session configuration. Context the Agent supplies from the workspace or environment MAY still be included. Clients that use this mode take responsibility for any tool guidance or safety instructions the Agent's default instructions provided, and MUST only use it when the Agent advertises `sessionCapabilities.systemPrompt.mode.override`. **other** `string` Custom or future system prompt mode. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## Terminal Embed a terminal created with `terminal/create` by its id. The terminal must be added before calling `terminal/release`. See protocol docs: [Terminal](https://agentclientprotocol.com/protocol/v1/terminals) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **terminalId** `[TerminalId](#terminalid)` *required* Identifier of the terminal instance to embed in the content stream. ## TerminalExitStatus Exit status of a terminal command. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **exitCode** `integer | null` The process exit code (may be null if terminated by signal). * Minimum: `0` **signal** `string | null` The signal that terminated the process (may be null if exited normally). ## TerminalId Typed identifier used for terminal values on the wire. **Type:** `string` ## TextContent Text provided to or from an LLM. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **annotations** `[Annotations](#annotations) | null` Optional annotations that help clients decide how to display or route this content. **text** `string` *required* Text payload carried by this content block. ## TextResourceContents Text-based resource contents. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **mimeType** `string | null` MIME type describing the encoded media payload. **text** `string` *required* Text payload carried by this content block. **uri** `string` *required* URI associated with this resource or media payload. ## TitledMultiSelectItems Items definition for titled multi-select enum properties. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. Optional. Omitted and `null` are equivalent and mean no metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **anyOf** `[EnumOption\[\]](#enumoption)` *required* Titled enum options. ## ToolCall Represents a tool call that the language model has requested. Tool calls are actions that the agent executes on behalf of the language model, such as reading files, executing code, or fetching data from external sources. See protocol docs: [Tool Calls](https://agentclientprotocol.com/protocol/v1/tool-calls) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **content** `[ToolCallContent\[\]](#toolcallcontent)` Content produced by the tool call. **kind** `[ToolKind](#toolkind)` The category of tool being invoked. Helps clients choose appropriate icons and UI treatment. **locations** `[ToolCallLocation\[\]](#toolcalllocation)` File locations affected by this tool call. Enables "follow-along" features in clients. **name** `string | null` Programmatic name of the tool being invoked. This field is optional. Omitting it or sending `null` both mean that no tool name is available. **rawInput** `object` Raw input parameters sent to the tool. **rawOutput** `object` Raw output returned by the tool. **status** `[ToolCallStatus](#toolcallstatus)` Current execution status of the tool call. **title** `string` *required* Human-readable title describing what the tool is doing. **toolCallId** `[ToolCallId](#toolcallid)` *required* Unique identifier for this tool call within the session. ## ToolCallContent Content produced by a tool call. Tool calls can produce different types of content including standard content blocks (text, images) or file diffs. See protocol docs: [Content](https://agentclientprotocol.com/protocol/v1/tool-calls#content) **Type:** Union **content** `object` Standard content block (text, images, resources). **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **content** `[ContentBlock](#contentblock)` *required* The actual content block. **type** `string` *required* The discriminator value. Must be `"content"`. **diff** `object` File modification shown as a diff. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **newText** `string` *required* The new content after modification. **oldText** `string | null` The original content (omitted or `null` for new files). **path** `string` *required* The absolute file path being modified. **type** `string` *required* The discriminator value. Must be `"diff"`. **terminal** `object` Embed a terminal created with `terminal/create` by its id. The terminal must be added before calling `terminal/release`. See protocol docs: [Terminal](https://agentclientprotocol.com/protocol/v1/terminals) **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **terminalId** `[TerminalId](#terminalid)` *required* Identifier of the terminal instance to embed in the content stream. **type** `string` *required* The discriminator value. Must be `"terminal"`. ## ToolCallId Unique identifier for a tool call within a session. **Type:** `string` ## ToolCallLocation A file location being accessed or modified by a tool. Enables clients to implement "follow-along" features that track which files the agent is working with in real-time. See protocol docs: [Following the Agent](https://agentclientprotocol.com/protocol/v1/tool-calls#following-the-agent) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **line** `integer | null` Optional 1-based line number within the file. * Minimum: `0` **path** `string` *required* The absolute file path being accessed or modified. ## ToolCallStatus Execution status of a tool call. Tool calls progress through different statuses during their lifecycle. See protocol docs: [Status](https://agentclientprotocol.com/protocol/v1/tool-calls#status) **Type:** Union **pending** `string` The tool call hasn't started running yet because the input is either streaming or we're awaiting approval. **in\_progress** `string` The tool call is currently running. **completed** `string` The tool call completed successfully. **failed** `string` The tool call failed with an error. ## ToolCallUpdate An update to an existing tool call. Used to report progress and results as tools execute. All fields except the tool call ID are optional - only changed fields need to be included. See protocol docs: [Updating](https://agentclientprotocol.com/protocol/v1/tool-calls#updating) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **content** `[ToolCallContent\[\]](#toolcallcontent) | null` Replace the content collection. **kind** `[ToolKind](#toolkind) | null` Update the tool kind. **locations** `[ToolCallLocation\[\]](#toolcalllocation) | null` Replace the locations collection. **name** `string | null` Update the programmatic name of the tool being invoked. This field is optional. Omitting it or sending `null` both mean that the existing name is left unchanged. **rawInput** `object` Update the raw input. **rawOutput** `object` Update the raw output. **status** `[ToolCallStatus](#toolcallstatus) | null` Update the execution status. **title** `string | null` Update the human-readable title. **toolCallId** `[ToolCallId](#toolcallid)` *required* The ID of the tool call being updated. ## ToolKind Categories of tools that can be invoked. Tool kinds help clients choose appropriate icons and optimize how they display tool execution progress. See protocol docs: [Creating](https://agentclientprotocol.com/protocol/v1/tool-calls#creating) **Type:** Union **read** `string` Reading files or data. **edit** `string` Modifying files or content. **delete** `string` Removing files or data. **move** `string` Moving or renaming files. **search** `string` Searching for information. **execute** `string` Running commands or code. **think** `string` Internal reasoning or planning. **fetch** `string` Retrieving external data. **switch\_mode** `string` Switching the current session mode. **other** `string` Other tool types (default). ## UnstructuredCommandInput All text that was typed after the command name is provided as input. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **hint** `string` *required* A hint to display when the input hasn't been provided yet ## UsageUpdate Context window and cost update for a session. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) **cost** `[Cost](#cost) | null` Cumulative session cost (optional). **size** `uint64` *required* Total context window size in tokens. * Minimum: `0` **used** `uint64` *required* Tokens currently in context. * Minimum: `0` # Security Considerations Source: https://agentclientprotocol.com/protocol/v1/security Trust model and security guidance for Agents and Clients This page describes ACP's trust model and security guidance that spans features. Guidance for a single feature is on that feature's page. See [Feature Guidance](#feature-guidance). ## Trust Model * The Agent runs with whatever permissions its process is given. ACP itself does not sandbox it. * Files, web pages, tool results, and MCP servers can influence Agent output. Treat every Agent-authored string, URI, and path as untrusted, including replayed content. * Permission requests are advisory: the Agent performs its own operations and is responsible for honoring the user's decision. The Client performs [file system](/protocol/v1/file-system) and [terminal](/protocol/v1/terminals) operations itself. * `clientInfo` and `agentInfo` are self-reported. Implementations **SHOULD NOT** use them for security decisions, and Clients **SHOULD** identify the Agent from their own launch configuration. Out of scope: a malicious Agent binary, detecting prompt injection, and operating-system sandboxing. ## Rendering Agent content This applies to all Agent-authored display text, including messages, thoughts, tool calls, plans, commands, modes, config options, notices, session titles, authentication methods, permission requests, and elicitations. * Clients **SHOULD NOT** run scripts from Agent content, and **SHOULD** disable or sanitize raw HTML when rendering Markdown. * Clients **SHOULD NOT** automatically run active content, such as diagram renderers, that can fetch resources or execute code. * Clients **SHOULD NOT** open links from Agent content without user action, and **SHOULD** show the full target and get user confirmation before handing a link with a scheme other than `http` or `https` to the operating system or another handler. * Clients **SHOULD** show the full link target when it differs from the link text. * Clients **SHOULD** reveal or remove bidirectional, zero-width, and tag characters in commands, paths, URLs, diffs, and permission requests. * Clients that print Agent text to a terminal **SHOULD** neutralize terminal control sequences in it. * Clients **SHOULD** keep Agent [slash commands](/protocol/v1/slash-commands) distinguishable from their own commands. * Clients **MAY** bound or throttle permission requests, elicitations, and output. ## URIs and remote resources This applies to `uri` on images, resource links, and embedded resources, and to URLs in Markdown. * Clients **SHOULD** render images from `data` and **SHOULD NOT** fetch Agent-supplied remote URIs without user action. A request can leak data through its URL. * Automatic fetches **SHOULD** use only `https:` or `data:` URIs, **SHOULD NOT** carry credentials, **SHOULD** refuse loopback and private-network targets, and **SHOULD** bound the response size. * Clients **SHOULD NOT** run scripts in SVG images from Agent content. * Clients **SHOULD NOT** read a `file:` URI from Agent content outside the session's [root set](/protocol/v1/session-setup#workspace-root-security) without user action. * Agents **SHOULD** apply the root set and these fetch rules to URIs in prompts. ## Credentials * Implementations **SHOULD NOT** put credentials in `_meta`, including `traceparent`, `tracestate`, and `baggage`. * Session, message, tool-call, and terminal IDs are not credentials. ## Prompt injection * Agents **SHOULD** treat embedded resources, files, tool results, and MCP results as data, not as user instructions. * Agents **SHOULD** request permission before sending data off the machine after reading untrusted content. * Agents **SHOULD** request permission before writing files that control execution or approval, such as version-control hooks, editor or Agent settings, and MCP configuration. * Clients **SHOULD NOT** open links, run commands, change settings, or send data based only on Agent-authored text. * A [system prompt](/protocol/v1/session-setup#system-prompt) carries more weight than user turns. Clients **SHOULD** only send content they trust at that level, and Agents **MAY** reject it. ## Intermediaries * An intermediary between the Client and the Agent, such as a proxy, can read and change every message, and each side treats it as the other. Clients **SHOULD** only use intermediaries the user trusts. * Intermediaries **SHOULD NOT** answer permission requests or elicitations for the user except under user-configured policy. * An Agent serving more than one user **SHOULD** scope `session/list`, session loading and resumption, permission requests, and elicitations to the user that owns the session. ## Transports [Custom transports](/protocol/v1/transports#custom-transports) **SHOULD** document their security considerations, including how peers authenticate. ## Feature guidance * [Workspace roots](/protocol/v1/session-setup#workspace-root-security) * [Terminal authentication](/protocol/v1/authentication#launch-safety) * [MCP servers](/protocol/v1/session-setup#security) * [Permission requests](/protocol/v1/tool-calls#security) * [File system](/protocol/v1/file-system#security) and [terminal](/protocol/v1/terminals#security) methods, which the Client performs itself * [Elicitation](/protocol/v1/elicitation) ## Residual risk A user can approve a harmful operation, prompt injection can steer operations the user allowed, and an Agent can act without asking. # Session Config Options Source: https://agentclientprotocol.com/protocol/v1/session-config-options Flexible configuration selectors for agent sessions Agents can provide an arbitrary list of configuration options for a session, which Clients show to users as selectors. Options can cover models, model parameters, modes, reasoning levels, and more. > [!NOTE] > > Session Config Options are the preferred way to expose session-level > configuration. If an Agent provides `configOptions`, Clients **SHOULD** use > them instead of the [`modes`](/protocol/v1/session-modes) field. Modes will be > removed in a future version of the protocol. ## Initial state During [Session Setup](/protocol/v1/session-setup) the Agent **MAY** return a list of configuration options and their current values: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "sessionId": "sess_abc123def456", "configOptions": [ { "id": "mode", "name": "Session Mode", "description": "Controls how the agent requests permission", "category": "mode", "type": "select", "currentValue": "ask", "options": [ { "value": "ask", "name": "Ask", "description": "Request permission before making any changes" }, { "value": "code", "name": "Code", "description": "Write and modify code with full tool access" } ] }, { "id": "model", "name": "Model", "category": "model", "type": "select", "currentValue": "model-1", "options": [ { "value": "model-1", "name": "Model 1", "description": "The fastest model" }, { "value": "model-2", "name": "Model 2", "description": "The most powerful model" } ] }, { "id": "context_size", "name": "Context Size", "category": "model_config", "type": "select", "currentValue": "200k", "options": [ { "value": "200k", "name": "200K" }, { "value": "1m", "name": "1M" } ] } ] } } ``` **configOptions** `SessionConfigOption[]` The list of configuration options available for this session. The order of this array represents the Agent's preferred priority. Clients **SHOULD** respect this ordering when displaying options. ### SessionConfigOption **id** `string` *required* Unique identifier for this configuration option. Used when setting values. **name** `string` *required* Human-readable label for the option **description** `string` Optional description providing more details about what this option controls **category** `SessionConfigOptionCategory` Optional [semantic category](#option-categories) to help Clients provide consistent UX. **type** `string` *required* The type of input control. `select` is supported by default. `boolean` is only supported when the Client advertises `session.configOptions.boolean: {}` in `clientCapabilities`. **currentValue** `string | boolean` *required* The current value for this option. For `select` options this is a string value ID. For `boolean` options this is a boolean. **options** `SessionConfigSelectOption[] | SessionConfigSelectGroup[]` The available values for a `select` option. Required when `type` is `"select"` and omitted when `type` is `"boolean"`. This is either a flat array of values or an array of groups. Values and groups are not mixed in the same array. ### SessionConfigSelectOption **value** `string` *required* The value identifier used when setting this option **name** `string` *required* Human-readable name to display **description** `string` Optional description of what this value does ### Grouped select options Select values may be organized into groups: ```json theme={null} { "options": [ { "group": "recommended", "name": "Recommended", "options": [ { "value": "model-1", "name": "Model 1", "description": "Fast for everyday tasks" } ] } ] } ``` Each `SessionConfigSelectGroup` requires `group` (its unique string identifier), `name` (its human-readable label), and `options` (an array of `SessionConfigSelectOption` objects). A group may also include `_meta`. Each option still requires `value` and `name`. Its `description` and `_meta` fields are optional. ### Boolean config options Agents **MAY** include boolean config options only after the Client advertises support during initialization: ```json theme={null} { "clientCapabilities": { "session": { "configOptions": { "boolean": {} } } } } ``` Omitting `session`, `configOptions`, or `boolean` means the Client does not advertise support. When support is advertised, a boolean option uses `type: "boolean"` and a boolean `currentValue`: ```json theme={null} { "id": "brave_mode", "name": "Brave Mode", "description": "Skip confirmation prompts and act autonomously", "type": "boolean", "currentValue": true } ``` Agents **MUST NOT** include `type: "boolean"` options in `configOptions` payloads unless the Client advertised support. Agents that need to support older Clients should omit the boolean option or provide a `select` fallback. ## Option categories Each config option **MAY** include a `category` field. Categories are semantic metadata intended to help Clients provide consistent UX, such as attaching keyboard shortcuts, choosing icons, or deciding placement. > [!WARNING] > > Categories are for UX purposes only and **MUST NOT** be required for > correctness. Clients **MUST** handle missing or unknown categories gracefully. Category names beginning with `_` are free for custom use (e.g., `_my_custom_category`). Category names that do not begin with `_` are reserved for the ACP spec. | Category | Description | | - | - | | `mode` | Session mode selector | | `model` | Model selector | | `model_config` | Model-related parameter, such as context size or speed/quality trade-off | | `thought_level` | Thought/reasoning level selector | Clients **SHOULD** render `model_config` options near the `model` selector, such as in the same popover or panel. No capability negotiation is required for category values. When multiple options share the same category, Clients **SHOULD** use the array ordering to resolve ties, preferring earlier options in the list for prominent placement or keyboard shortcuts. ## Option ordering The order of the `configOptions` array is significant. Agents **SHOULD** place higher-priority options first in the list. Clients **SHOULD**: * Display options in the order provided by the Agent * Use ordering to resolve ties when multiple options share the same category * If displaying a limited number of options, prefer those at the beginning of the list ## Default values and graceful degradation Every configuration option's `currentValue` is the value the Agent uses until the Client changes it. Agents **MUST** be able to operate with it, even if: * The Client doesn't support configuration options * The Client chooses not to display certain options * The Client receives an option type it doesn't recognize If a Client receives an option with an unrecognized `type`, it **SHOULD** ignore that option. The Agent keeps using its `currentValue`. ## Setting a config option The current value of a config option can be changed at any point during a session, whether the Agent is idle or generating a response. ### From the Client Clients can change a config option value by calling the `session/set_config_option` method: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "session/set_config_option", "params": { "sessionId": "sess_abc123def456", "configId": "mode", "value": "code" } } ``` **sessionId** `SessionId` *required* The ID of the session **configId** `string` *required* The `id` of the configuration option to change **value** `string | boolean` *required* The new value to set. For `select` options, this must be one of the values listed in the option's `options` array. For `boolean` options, this must be a boolean. For boolean options, Clients send `type: "boolean"` with a boolean `value`: ```json theme={null} { "jsonrpc": "2.0", "id": 3, "method": "session/set_config_option", "params": { "sessionId": "sess_abc123def456", "configId": "brave_mode", "type": "boolean", "value": true } } ``` The Agent **MUST** respond with the complete list of all configuration options and their current values: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "result": { "configOptions": [ { "id": "mode", "name": "Session Mode", "description": "Controls how the agent requests permission", "category": "mode", "type": "select", "currentValue": "code", "options": [ { "value": "ask", "name": "Ask", "description": "Request permission before making any changes" }, { "value": "code", "name": "Code", "description": "Write and modify code with full tool access" } ] }, { "id": "model", "name": "Model", "category": "model", "type": "select", "currentValue": "model-1", "options": [ { "value": "model-1", "name": "Model 1", "description": "The fastest model" }, { "value": "model-2", "name": "Model 2", "description": "The most powerful model" } ] }, { "id": "context_size", "name": "Context Size", "category": "model_config", "type": "select", "currentValue": "200k", "options": [ { "value": "200k", "name": "200K" }, { "value": "1m", "name": "1M" } ] } ] } } ``` > [!NOTE] > > The response always contains the **complete** configuration state, so Agents > can report dependent changes. For example, changing the model may change the > available reasoning options. ### From the Agent The Agent can also change configuration options and notify the Client by sending a `config_option_update` session notification: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "config_option_update", "configOptions": [ { "id": "mode", "name": "Session Mode", "description": "Controls how the agent requests permission", "category": "mode", "type": "select", "currentValue": "code", "options": [ { "value": "ask", "name": "Ask", "description": "Request permission before making any changes" }, { "value": "code", "name": "Code", "description": "Write and modify code with full tool access" } ] }, { "id": "model", "name": "Model", "category": "model", "type": "select", "currentValue": "model-2", "options": [ { "value": "model-1", "name": "Model 1", "description": "The fastest model" }, { "value": "model-2", "name": "Model 2", "description": "The most powerful model" } ] }, { "id": "context_size", "name": "Context Size", "category": "model_config", "type": "select", "currentValue": "200k", "options": [ { "value": "200k", "name": "200K" }, { "value": "1m", "name": "1M" } ] } ] } } } ``` This notification also contains the complete configuration state. Common reasons an Agent might update configuration options include: * Switching modes after completing a planning phase * Falling back to a different model due to rate limits or errors * Adjusting available options based on context discovered during execution ## Relationship to session modes Session Config Options supersede the older [Session Modes](/protocol/v1/session-modes) API. However, during the transition period, Agents that provide mode-like configuration **SHOULD** send both: * `configOptions` with a `category: "mode"` option for Clients that support config options * `modes` for Clients that only support the older API If an Agent provides both `configOptions` and `modes` in the session response: * Clients that support config options **SHOULD** use `configOptions` exclusively and ignore `modes` * Clients that don't support config options **SHOULD** fall back to `modes` * Agents **SHOULD** keep both in sync to ensure consistent behavior regardless of which field the Client uses > [card] > > Learn about the Session Modes API > > [Open](/protocol/v1/session-modes) # Session Delete Source: https://agentclientprotocol.com/protocol/v1/session-delete Removing sessions from session history The `session/delete` method lets Clients remove sessions from an Agent's `session/list` results, so users can clean up session history from any ACP Client. Before deleting sessions, Clients **MUST** first complete the [initialization](/protocol/v1/initialization) phase and verify the Agent supports this capability. ```mermaid theme={null} sequenceDiagram participant Client participant Agent Note over Agent,Client: Initialized Client->>Agent: session/list Agent-->>Client: session/list response (sessions) alt User deletes a session Client->>Agent: session/delete (sessionId) Agent-->>Client: session/delete response end Client->>Agent: session/list Agent-->>Client: session/list response (without deleted session) ``` ## Checking support Before attempting to delete a session, Clients **MUST** verify that the Agent supports this capability by checking the `sessionCapabilities.delete` field in the `initialize` response: ```json highlight={7-9} theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "sessionCapabilities": { "delete": {} } } } } ``` If `sessionCapabilities.delete` is omitted or `null`, the Agent does not support deleting sessions and Clients **MUST NOT** attempt to call `session/delete`. Supplying `{}` means the Agent supports the method. ## Deleting a session Clients delete a session by calling `session/delete` with the session ID to remove from session history: ```json theme={null} { "jsonrpc": "2.0", "id": 3, "method": "session/delete", "params": { "sessionId": "sess_abc123def456" } } ``` **sessionId** `SessionId` *required* Unique identifier for the session to delete. On success, the Agent returns an empty result: ```json theme={null} { "jsonrpc": "2.0", "id": 3, "result": {} } ``` ## Semantics * Deleted sessions no longer appear in future `session/list` results. * Deleting an already-deleted session, or a session that never existed, **SHOULD** succeed silently. * Clients **SHOULD** treat a `-32002` response to `session/delete` as a successful delete. * Agents may implement soft delete or hard delete. ACP only specifies the user-facing session-list behavior. * Behavior for `session/load` on a deleted session is implementation-defined. * Behavior for deleting an active session is implementation-defined. # Session List Source: https://agentclientprotocol.com/protocol/v1/session-list Discovering existing sessions The `session/list` method returns the sessions an Agent knows about. Clients use it to show session history and let users switch between sessions. Agents can also send a `session_info_update` notification when a session's title or metadata changes, so Clients don't have to poll. Before listing sessions, Clients **MUST** first complete the [initialization](/protocol/v1/initialization) phase to verify the Agent supports this capability. ```mermaid theme={null} sequenceDiagram participant Client participant Agent Note over Agent,Client: Initialized Client->>Agent: session/list Agent-->>Client: session/list response (sessions) alt User selects a session Client->>Agent: session/load (sessionId) Note over Agent,Client: Replay conversation history... Agent-->>Client: session/load response end Note over Client,Agent: Ready for prompts ``` ## Checking support Before attempting to list sessions, Clients **MUST** verify that the Agent supports this capability by checking the `sessionCapabilities.list` field in the `initialize` response: ```json highlight={7-9} theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "sessionCapabilities": { "list": {} } } } } ``` If `sessionCapabilities.list` is not present, the Agent does not support listing sessions and Clients **MUST NOT** attempt to call `session/list`. Agents that also advertise `sessionCapabilities.additionalDirectories` may include `additionalDirectories` in returned `SessionInfo` objects to report additional workspace roots for listed sessions. > [!NOTE] > > If the Agent advertises the `sessionCapabilities.delete` capability, Clients > can remove sessions from future `session/list` results with > [`session/delete`](/protocol/v1/session-delete). ## Listing sessions Clients discover existing sessions by calling the `session/list` method with optional filtering and pagination parameters: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "session/list", "params": { "cwd": "/home/user/project", "cursor": "eyJwYWdlIjogMn0=" } } ``` All parameters are optional. A request with an empty `params` object returns the first page of sessions. **cwd** `string` Filter sessions by working directory. Must be an absolute path. Only sessions with a matching `cwd` are returned. **cursor** `string` Opaque cursor token from a previous response's `nextCursor` field for cursor-based pagination. See [Pagination](#pagination). The Agent **MUST** respond with a list of sessions and optional pagination metadata: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "result": { "sessions": [ { "sessionId": "sess_abc123def456", "cwd": "/home/user/project", "title": "Implement session list API", "updatedAt": "2025-10-29T14:22:15Z", "_meta": { "messageCount": 12, "hasErrors": false } }, { "sessionId": "sess_xyz789ghi012", "cwd": "/home/user/another-project", "title": "Debug authentication flow", "updatedAt": "2025-10-28T16:45:30Z" }, { "sessionId": "sess_uvw345rst678", "cwd": "/home/user/project", "updatedAt": "2025-10-27T15:30:00Z" } ], "nextCursor": "eyJwYWdlIjogM30=" } } ``` **sessions** `SessionInfo[]` *required* Array of session information objects. **SessionInfo** **sessionId** `string` *required* Unique identifier for the session. **cwd** `string` *required* Working directory for the session. Always an absolute path. **additionalDirectories** `string[]` If the Agent advertises `sessionCapabilities.additionalDirectories`, it **MAY** include this field to report the complete ordered additional-root list associated with the listed session. Omitted and empty values are equivalent: this `SessionInfo` response reports no additional roots. Clients **MUST NOT** merge this field with prior values or infer additional roots from agent-specific state. **title** `string` Human-readable title for the session. May be auto-generated from the first prompt. **updatedAt** `string` ISO 8601 timestamp of the last activity in the session. **\_meta** `object` Agent-specific metadata. See [Extensibility](/protocol/v1/extensibility). **nextCursor** `string` Opaque cursor token. If present, pass this in the next request's `cursor` parameter to fetch the next page. If absent, there are no more results. When no sessions match the criteria, the Agent **MUST** return an empty `sessions` array. ## Pagination `session/list` uses cursor-based pagination. The request includes an optional `cursor`, and the response includes `nextCursor` when more results are available. * Clients **MUST** treat a missing `nextCursor` as the end of results * Clients **MUST** treat cursors as opaque tokens, which means not parsing, modifying, or persisting them * Agents **SHOULD** return `-32602` if the cursor is invalid * Agents **SHOULD** enforce reasonable page sizes internally ## Updating session metadata Agents can update session metadata in real-time by sending a `session_info_update` notification via `session/update`. This follows the same pattern as other session notifications like [`available_commands_update`](/protocol/v1/slash-commands) and [`current_mode_update`](/protocol/v1/session-modes). ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "session_info_update", "title": "Implement user authentication", "_meta": { "tags": ["feature", "auth"], "priority": "high" } } } } ``` All fields are optional. Only include fields that have changed. Omitted fields are left unchanged. **title** `string | null` Human-readable title for the session. Set to `null` to clear. **updatedAt** `string | null` ISO 8601 timestamp of last activity. Set to `null` to clear. **\_meta** `object` Agent-specific metadata. See [Extensibility](/protocol/v1/extensibility). The `sessionId`, `cwd`, and `additionalDirectories` fields are **not** included in the update. `sessionId` is already in the notification's `params`, `cwd` is immutable after session setup, and ACP does not currently define mid-session mutation for `additionalDirectories`. Agents typically send this notification after the first meaningful exchange to auto-generate a title. ## Interaction with other session methods `session/list` only discovers sessions. It does **not** restore or modify them: 1. Client calls `session/list` to discover available sessions 2. User selects a session from the list 3. Client calls [`session/load`](/protocol/v1/session-setup#loading-sessions) with the chosen `sessionId` to resume the conversation # Session Modes Source: https://agentclientprotocol.com/protocol/v1/session-modes Switch between different agent operating modes > [!NOTE] > > You can now use [Session Config Options](/protocol/v1/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](/protocol/v1/session-setup) the Agent **MAY** return a list of modes it can operate in and the currently active mode: ```json theme={null} { "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`](/protocol/v1/schema#session%2Fset_mode) method. ```json theme={null} { "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: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "current_mode_update", "currentModeId": "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: ```json theme={null} { "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": "content", "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. > [card] > > Learn more about permission requests > > [Open](/protocol/v1/tool-calls#requesting-permission) # Session Setup Source: https://agentclientprotocol.com/protocol/v1/session-setup Creating and loading sessions Sessions represent a specific conversation or thread between the [Client](/protocol/v1/overview#client) and [Agent](/protocol/v1/overview#agent). Each session has its own context, conversation history, and state, so one Agent can run several independent sessions. Before creating a session, Clients **MUST** first complete the [initialization](/protocol/v1/initialization) phase to establish protocol compatibility and capabilities. If the Agent requires authentication, `session/new` may fail with an `auth_required` error until the Client completes the [authentication flow](/protocol/v1/authentication). ```mermaid theme={null} sequenceDiagram participant Client participant Agent Note over Agent,Client: Initialized alt Client->>Agent: session/new Note over Agent: Create session context Note over Agent: Connect to MCP servers Agent-->>Client: session/new response (sessionId) else Client->>Agent: session/load (sessionId) Note over Agent: Restore session context Note over Agent: Connect to MCP servers Note over Agent,Client: Replay conversation history... Agent->>Client: session/update Agent->>Client: session/update Note over Agent,Client: All content streamed Agent-->>Client: session/load response else Client->>Agent: session/resume (sessionId) Note over Agent: Restore session context Note over Agent: Connect to MCP servers Agent-->>Client: session/resume response end Note over Client,Agent: Ready for prompts ``` ## Creating a session Clients create a new session by calling the `session/new` method with: * The [working directory](#working-directory) for the session * A list of [MCP servers](#mcp-servers) the Agent should connect to ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "session/new", "params": { "cwd": "/home/user/project", "mcpServers": [ { "name": "filesystem", "command": "/path/to/mcp-server", "args": ["--stdio"], "env": [] } ] } } ``` The Agent **MUST** respond with a unique [Session ID](#session-id) that identifies this conversation: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "sessionId": "sess_abc123def456" } } ``` ## Loading sessions Agents that support the `loadSession` capability allow Clients to resume previous conversations with history replay. This feature enables persistence across restarts and sharing sessions between different Client instances. ### Checking support Before attempting to load a session, Clients **MUST** verify that the Agent supports this capability by checking the `loadSession` field in the `initialize` response: ```json highlight={7} theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "loadSession": true } } } ``` If `loadSession` is `false` or not present, the Agent does not support loading sessions and Clients **MUST NOT** attempt to call `session/load`. ### Loading a session To load an existing session, Clients **MUST** call the `session/load` method with: * The [Session ID](#session-id) to resume * [MCP servers](#mcp-servers) to connect to * The [working directory](#working-directory) ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "session/load", "params": { "sessionId": "sess_789xyz", "cwd": "/home/user/project", "mcpServers": [ { "name": "filesystem", "command": "/path/to/mcp-server", "args": ["--mode", "filesystem"], "env": [] } ] } } ``` The Agent **MUST** replay the entire conversation to the Client in the form of `session/update` notifications (like `session/prompt`). [Session compactions](/protocol/v1/prompt-turn#session-compaction) are replayed using the same update, chunk, and patch semantics as live delivery. The Client's `session.compaction` capability is required for replay as well as live delivery. Live-only [notices](/protocol/v1/prompt-turn#session-notices) are not conversation history and **SHOULD NOT** be replayed. If the underlying condition is still relevant after loading finishes, the Agent may emit a new notice as a new live event, subject to the Client's `session.notices` capability. For example, a user message from the conversation history: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_789xyz", "update": { "sessionUpdate": "user_message_chunk", "messageId": "msg_user_8f7a1", "content": { "type": "text", "text": "What's the capital of France?" } } } } ``` Followed by the agent's response: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_789xyz", "update": { "sessionUpdate": "agent_message_chunk", "messageId": "msg_agent_c42b9", "content": { "type": "text", "text": "The capital of France is Paris." } } } } ``` If the Agent provides message IDs during replay, each `messageId` is an opaque, unique identifier for the replayed message. When **all** the conversation entries have been streamed to the Client, the Agent **MUST** respond to the original `session/load` request. ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": {} } ``` The response **MAY** also include initial mode, model, or session configuration state when those features are supported by the Agent. The Client can then continue sending prompts as if the session was never interrupted. ## Resuming sessions Agents that advertise `sessionCapabilities.resume` allow Clients to reconnect to an existing session without replaying the conversation history. ### Checking support Before attempting to resume a session, Clients **MUST** verify that the Agent supports this capability by checking for the `sessionCapabilities.resume` field in the `initialize` response: ```json highlight={7-9} theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "sessionCapabilities": { "resume": {} } } } } ``` If `sessionCapabilities.resume` is not present, the Agent does not support resuming sessions and Clients **MUST NOT** attempt to call `session/resume`. ### Resuming a session To resume an existing session without replaying prior messages, Clients **MUST** call the `session/resume` method with: * The [Session ID](#session-id) to resume * [MCP servers](#mcp-servers) to connect to * The [working directory](#working-directory) ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "session/resume", "params": { "sessionId": "sess_789xyz", "cwd": "/home/user/project", "mcpServers": [ { "name": "filesystem", "command": "/path/to/mcp-server", "args": ["--mode", "filesystem"], "env": [] } ] } } ``` Unlike `session/load`, the Agent **MUST NOT** replay the conversation history via `session/update` notifications before responding. Instead, it restores the session context, reconnects to the requested MCP servers, and returns once the session is ready to continue. ```json theme={null} { "jsonrpc": "2.0", "id": 2, "result": {} } ``` The response **MAY** also include initial mode, model, or session configuration state when those features are supported by the Agent. ## Closing active sessions Agents that advertise `sessionCapabilities.close` allow Clients to tell the Agent to cancel any ongoing work for a session and free any resources associated with that active session. ### Checking support Before attempting to close a session, Clients **MUST** verify that the Agent supports this capability by checking the `sessionCapabilities.close` field in the `initialize` response: ```json highlight={7-9} theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "sessionCapabilities": { "close": {} } } } } ``` If `sessionCapabilities.close` is not present, the Agent does not support closing sessions and Clients **MUST NOT** attempt to call `session/close`. ### Closing a session To close an active session, Clients **MUST** call the `session/close` method with the session ID: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "session/close", "params": { "sessionId": "sess_789xyz" } } ``` **sessionId** `SessionId` *required* The ID of the active session to close. The Agent **MUST** cancel any ongoing work for that session as if [`session/cancel`](/protocol/v1/prompt-turn#cancellation) had been called, then free the resources associated with the session. On success, the Agent responds with an empty result object: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "result": {} } ``` Closing is idempotent. If the session does not exist or is not active, for example because it was already closed, the Agent **SHOULD** respond with the same empty result. Clients **SHOULD** treat a `-32002` response to `session/close` as a successful close. See [Unknown Sessions](/protocol/v1/error#unknown-sessions). ## Additional workspace roots Agents that advertise `sessionCapabilities.additionalDirectories` allow Clients to include `additionalDirectories` on supported session lifecycle requests to expand the session's effective filesystem root set. Supported stable lifecycle requests include `session/new`, `session/load`, and `session/resume`. ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "session/load", "params": { "sessionId": "sess_789xyz", "cwd": "/home/user/project", "additionalDirectories": [ "/home/user/shared-lib", "/home/user/product-docs" ], "mcpServers": [] } } ``` When present, `additionalDirectories` has the following behavior: * `cwd` remains the primary working directory and the base for relative paths * each `additionalDirectories` entry **MUST** be an absolute path * omitting the field or providing an empty array activates no additional roots for the resulting session * on `session/load` and `session/resume`, Clients must send the full intended additional-root list again. That list may differ from any previous or reported list as long as the request `cwd` matches the session's `cwd`, and omitting the field or providing an empty array does not restore stored roots implicitly Clients **MUST** only send `additionalDirectories` when the Agent advertises `sessionCapabilities.additionalDirectories`. ## System prompt Agents that advertise `sessionCapabilities.systemPrompt` allow Clients to include system-level instructions on `session/new`, `session/load`, and `session/resume`. ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "session/new", "params": { "cwd": "/home/user/project", "mcpServers": [], "systemPrompt": { "mode": "append", "content": [ { "type": "text", "text": "You are a code review specialist. Focus on security issues." } ] } } } ``` `systemPrompt` has the following behavior: * `mode` is required and selects how the Agent combines `content` with its own instructions * `mode` values beginning with `_` are reserved for implementation-specific modes, and other unknown values for future ACP modes. Clients **MUST** only use a mode the Agent advertised. An Agent that receives a mode it does not support **MUST** return an error rather than treating it as `append` or `override` * `append` adds `content` to the Agent's own instructions rather than replacing them. The Agent **SHOULD** give it system-level precedence, for example in the model's system prompt or developer instructions rather than in user-turn content. Where it is placed and how it is formatted is up to the Agent * `override` replaces the Agent's built-in default instructions. It does not change tool availability, MCP servers, permissions, or session configuration. Context the Agent supplies from the workspace or environment, such as `AGENTS.md` files or skill listings, **MAY** still be included, and Agents **SHOULD** document what they keep. Clients that use `override` take responsibility for any tool guidance or safety instructions the Agent's default instructions provided * only `text` content blocks are supported for now: Agents **MUST** accept them, and Clients **MUST NOT** send other content block types until a future capability allows them * Clients **MUST NOT** send an empty `content` array. Agents **MAY** reject one with `-32602` without creating, loading, or resuming the session * omitting the field or setting it to `null` on `session/new` means the Agent uses its default instructions * on `session/load` and `session/resume`, Clients **SHOULD** send the same `systemPrompt` they used when the session was created. When it is omitted, the Agent may keep a prompt it stored with the session or use its default. When it differs, the Agent **SHOULD** apply it, and **MAY** defer the change until it next rebuilds its prompt (for example, after compaction) when applying it immediately would discard prompt caches or preserved reasoning * if the Agent cannot apply a supplied `systemPrompt`, for example because of an unadvertised mode, an unsupported content block type, or content that exceeds its limits, it **MUST** return an error and **MUST NOT** create, load, or resume the session. JSON-RPC `-32602` (Invalid params) is the **RECOMMENDED** error for malformed or unsupported values Clients **MUST** only send `systemPrompt` when the Agent advertises `sessionCapabilities.systemPrompt`, and **MUST** only use `override` mode when the Agent also advertises `sessionCapabilities.systemPrompt.mode.override`: ```json highlight={8-10} theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "sessionCapabilities": { "systemPrompt": { "mode": { "override": {} } } } } } } ``` Content delivered at system level carries more weight with the model than user turns or tool output. Clients **SHOULD** only send content they trust at that level. ## Session ID The session ID returned by `session/new` is a unique identifier for the conversation context. Clients use this ID to: * Send prompt requests via `session/prompt` * Cancel ongoing operations via `session/cancel` * Load previous sessions via `session/load` (if the Agent supports the `loadSession` capability) * Resume previous sessions via `session/resume` (if the Agent supports the `sessionCapabilities.resume` capability) * Close active sessions via `session/close` (if the Agent supports the `sessionCapabilities.close` capability) ## Working directory The `cwd` (current working directory) parameter establishes the primary file system context for the session. This directory: * **MUST** be an absolute path * **MUST** be used for the session regardless of where the Agent subprocess was spawned * **MUST** remain the base for relative-path resolution * **MUST** be part of the session's effective root set When `sessionCapabilities.additionalDirectories` is in use, the session's effective root set is `[cwd, ...additionalDirectories]`. This root set **SHOULD** serve as a boundary for tool operations on the file system. ### Workspace root security The root set declares the session's scope. It confines shell commands only when a sandbox enforces it. * Clients **SHOULD** only include directories the user expects the Agent to access, such as the workspace or directories the Client provides, like skills. * Agents **SHOULD NOT** treat model output, Agent content, or replayed history as granting access outside the root set. Access outside it goes through a permission request. * Implementations that enforce the root set **SHOULD** check the resolved path at the time of use, compare paths by component, and fail closed. ## MCP servers The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) allows Agents to access external tools and data sources. When creating a session, Clients **MAY** include connection details for MCP servers that the Agent should connect to. MCP servers can be connected to using different transports. All Agents **MUST** support the stdio transport, while HTTP and SSE transports are optional capabilities that can be checked during initialization. While they are not required to by the spec, new Agents **SHOULD** support the HTTP transport to ensure compatibility with modern MCP servers. ### Transport types #### Stdio transport All Agents **MUST** support connecting to MCP servers via stdio (standard input/output). This is the default transport mechanism. **name** `string` *required* A human-readable identifier for the server **command** `string` *required* The absolute path to the MCP server executable **args** `array` *required* Command-line arguments to pass to the server **env** `EnvVariable[]` Environment variables to set when launching the server **EnvVariable** **name** `string` *required* The name of the environment variable. **value** `string` *required* The value of the environment variable. Example stdio transport configuration: ```json theme={null} { "name": "filesystem", "command": "/path/to/mcp-server", "args": ["--stdio"], "env": [ { "name": "API_KEY", "value": "secret123" } ] } ``` #### HTTP transport When the Agent supports `mcpCapabilities.http`, Clients can specify MCP servers configurations using the HTTP transport. **type** `string` *required* Must be `"http"` to indicate HTTP transport **name** `string` *required* A human-readable identifier for the server **url** `string` *required* The URL of the MCP server **headers** `HttpHeader[]` *required* HTTP headers to include in requests to the server **HttpHeader** **name** `string` *required* The name of the HTTP header. **value** `string` *required* The value to set for the HTTP header. Example HTTP transport configuration: ```json theme={null} { "type": "http", "name": "api-server", "url": "https://api.example.com/mcp", "headers": [ { "name": "Authorization", "value": "Bearer token123" }, { "name": "Content-Type", "value": "application/json" } ] } ``` #### SSE transport When the Agent supports `mcpCapabilities.sse`, Clients can specify MCP servers configurations using the SSE transport. > [!WARNING] > > This transport was deprecated by the MCP spec. **type** `string` *required* Must be `"sse"` to indicate SSE transport **name** `string` *required* A human-readable identifier for the server **url** `string` *required* The URL of the SSE endpoint **headers** `HttpHeader[]` *required* HTTP headers to include when establishing the SSE connection **HttpHeader** **name** `string` *required* The name of the HTTP header. **value** `string` *required* The value to set for the HTTP header. Example SSE transport configuration: ```json theme={null} { "type": "sse", "name": "event-stream", "url": "https://events.example.com/mcp", "headers": [ { "name": "X-API-Key", "value": "apikey456" } ] } ``` ### Checking transport support Before using HTTP or SSE transports, Clients **MUST** verify the Agent's capabilities during initialization: ```json highlight={7-10} theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "mcpCapabilities": { "http": true, "sse": true } } } } ``` If `mcpCapabilities.http` is `false` or not present, the Agent does not support HTTP transport. If `mcpCapabilities.sse` is `false` or not present, the Agent does not support SSE transport. Agents **SHOULD** connect to all MCP servers specified by the Client. Clients **MAY** use this ability to provide tools directly to the underlying language model by including their own MCP server. ### Security MCP server configurations can launch processes, and their `env` and `headers` values are credentials. * Agents **SHOULD** launch `command` with `args` as separate arguments, without a shell. * Clients **SHOULD NOT** send a stdio server from workspace files or Agent output until the user has approved its exact command, arguments, and environment variable names. * Agents **SHOULD NOT** include `env` or `headers` values in session updates, errors, `_meta`, `session/list` results, replayed history, model context, or command lines, and **SHOULD NOT** log or persist them. * Agents **SHOULD** send `headers` only to the configured origin. * Clients that persist `mcpServers` **SHOULD** keep credentials in operating-system secret storage and **SHOULD NOT** log them. # Slash Commands Source: https://agentclientprotocol.com/protocol/v1/slash-commands Advertise available slash commands to clients Agents can advertise a set of slash commands that users can invoke. These commands provide quick access to specific agent capabilities and workflows. Commands are run as part of regular [prompt](/protocol/v1/prompt-turn) requests where the Client includes the command text in the prompt. ## Advertising commands After creating a session, the Agent **MAY** send a list of available commands via the `available_commands_update` session notification: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "available_commands_update", "availableCommands": [ { "name": "web", "description": "Search the web for information", "input": { "hint": "query to search for" } }, { "name": "test", "description": "Run tests for the current project" }, { "name": "plan", "description": "Create a detailed implementation plan", "input": { "hint": "description of what to plan" } } ] } } } ``` **availableCommands** `AvailableCommand[]` The list of commands available in this session ### AvailableCommand **name** `string` *required* The command name (e.g., "web", "test", "plan") **description** `string` *required* Human-readable description of what the command does **input** `AvailableCommandInput` Optional input specification for the command ### AvailableCommandInput Currently supports unstructured text input: **hint** `string` *required* A hint to display when the input hasn't been provided yet ## Dynamic updates The Agent can update the list of available commands at any time during a session by sending another `available_commands_update` notification. Agents can use this to add commands as context changes, remove commands that no longer apply, or update descriptions. ## Running commands Commands are included as regular user messages in prompt requests: ```json theme={null} { "jsonrpc": "2.0", "id": 3, "method": "session/prompt", "params": { "sessionId": "sess_abc123def456", "prompt": [ { "type": "text", "text": "/web agent client protocol" } ] } } ``` The Agent recognizes the command prefix and processes it accordingly. Commands may be accompanied by any other user message content types (images, audio, etc.) in the same prompt array. # Terminals Source: https://agentclientprotocol.com/protocol/v1/terminals Executing and managing terminal commands The terminal methods allow Agents to execute shell commands within the Client's environment. These methods enable Agents to run build processes, execute scripts, and interact with command-line tools while providing real-time output streaming and process control. ## Checking support Before attempting to use terminal methods, Agents **MUST** verify that the Client supports this capability by checking the [Client Capabilities](/protocol/v1/initialization#client-capabilities) field in the Client's `initialize` request: ```json highlight={8} theme={null} { "jsonrpc": "2.0", "id": 0, "method": "initialize", "params": { "protocolVersion": 1, "clientCapabilities": { "terminal": true } } } ``` If `terminal` is `false` or not present, the Agent **MUST NOT** attempt to call any terminal methods. ## Executing commands The `terminal/create` method starts a command in a new terminal: ```json theme={null} { "jsonrpc": "2.0", "id": 5, "method": "terminal/create", "params": { "sessionId": "sess_abc123def456", "command": "npm", "args": ["test", "--coverage"], "env": [ { "name": "NODE_ENV", "value": "test" } ], "cwd": "/home/user/project", "outputByteLimit": 1048576 } } ``` **sessionId** `SessionId` *required* The [Session ID](/protocol/v1/session-setup#session-id) for this request **command** `string` *required* The command to execute **args** `string[]` Array of command arguments **env** `EnvVariable[]` Environment variables for the command. Each variable has: * `name`: The environment variable name * `value`: The environment variable value **cwd** `string` Working directory for the command. Must be an absolute path. **outputByteLimit** `number` Maximum number of output bytes to retain. Once exceeded, earlier output is truncated to stay within this limit. When the limit is exceeded, the Client truncates from the beginning of the output to stay within the limit. The Client **MUST** ensure truncation happens at a character boundary to maintain valid string output, even if this means the retained output is slightly less than the specified limit. The Client returns a Terminal ID immediately without waiting for completion: ```json theme={null} { "jsonrpc": "2.0", "id": 5, "result": { "terminalId": "term_xyz789" } } ``` The command keeps running in the background while the Agent does other work. After creating the terminal, the Agent can use the `terminal/wait_for_exit` method to wait for the command to complete. > [!NOTE] > > The Agent **MUST** release the terminal using `terminal/release` when it's no > longer needed. ## Embedding in tool calls Terminals can be embedded directly in [tool calls](/protocol/v1/tool-calls) to provide real-time output to users: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "tool_call", "toolCallId": "call_002", "title": "Running tests", "kind": "execute", "status": "in_progress", "content": [ { "type": "terminal", "terminalId": "term_xyz789" } ] } } } ``` When a terminal is embedded in a tool call, the Client displays live output as it's generated and continues to display it even after the terminal is released. ## Getting output The `terminal/output` method retrieves the current terminal output without waiting for the command to complete: ```json theme={null} { "jsonrpc": "2.0", "id": 6, "method": "terminal/output", "params": { "sessionId": "sess_abc123def456", "terminalId": "term_xyz789" } } ``` The Client responds with the current output and exit status (if the command has finished): ```json theme={null} { "jsonrpc": "2.0", "id": 6, "result": { "output": "Running tests...\n✓ All tests passed (42 total)\n", "truncated": false, "exitStatus": { "exitCode": 0, "signal": null } } } ``` **output** `string` *required* The terminal output captured so far **truncated** `boolean` *required* Whether the output was truncated due to byte limits **exitStatus** `TerminalExitStatus` Present only if the command has exited. Contains: * `exitCode`: The process exit code (may be null) * `signal`: The signal that terminated the process (may be null) ## Waiting for exit The `terminal/wait_for_exit` method returns once the command completes: ```json theme={null} { "jsonrpc": "2.0", "id": 7, "method": "terminal/wait_for_exit", "params": { "sessionId": "sess_abc123def456", "terminalId": "term_xyz789" } } ``` The Client responds once the command exits: ```json theme={null} { "jsonrpc": "2.0", "id": 7, "result": { "exitCode": 0, "signal": null } } ``` **exitCode** `number` The process exit code (may be null if terminated by signal) **signal** `string` The signal that terminated the process (may be null if exited normally) ## Killing commands The `terminal/kill` method terminates a command without releasing the terminal: ```json theme={null} { "jsonrpc": "2.0", "id": 8, "method": "terminal/kill", "params": { "sessionId": "sess_abc123def456", "terminalId": "term_xyz789" } } ``` After killing a command, the terminal remains valid and can be used with: * `terminal/output` to get the final output * `terminal/wait_for_exit` to get the exit status The Agent **MUST** still call `terminal/release` when it's done using it. ### Building a timeout Agents can implement command timeouts by combining terminal methods: 1. Create a terminal with `terminal/create` 2. Start a timer for the desired timeout duration 3. Concurrently wait for either the timer to expire or `terminal/wait_for_exit` to return 4. If the timer expires first: * Call `terminal/kill` to terminate the command * Call `terminal/output` to retrieve any final output * Include the output in the response to the model 5. Call `terminal/release` when done ## Releasing terminals The `terminal/release` kills the command if still running and releases all resources: ```json theme={null} { "jsonrpc": "2.0", "id": 9, "method": "terminal/release", "params": { "sessionId": "sess_abc123def456", "terminalId": "term_xyz789" } } ``` After release the terminal ID becomes invalid for all other `terminal/*` methods. If the terminal was added to a tool call, the client **SHOULD** continue to display its output after release. ## Security The Client runs these commands itself, so it is responsible for checking them. A permission request from the Agent does not replace the Client's own checks. * Clients **SHOULD** require `cwd` to be inside the session's [root set](/protocol/v1/session-setup#workspace-root-security) and apply their own permission policy to the full `command`, `args`, and `env`. Clients that approve commands automatically **SHOULD** include `env` in what the policy matches. * Clients **SHOULD** display `terminal/output` with terminal control sequences neutralized, so that it cannot write the clipboard, send input or query responses, or open links without user action. # Tool Calls Source: https://agentclientprotocol.com/protocol/v1/tool-calls How Agents report tool call execution Tool calls are actions the language model asks the Agent to perform during a [prompt turn](/protocol/v1/prompt-turn), such as reading a file or running a command. The Agent executes them on the model's behalf. Agents report tool calls through [`session/update`](/protocol/v1/prompt-turn#3-agent-reports-output) notifications, which Clients use to show progress and results to users. Agents run tool calls themselves. They may use Client capabilities such as [permission requests](#requesting-permission) or [file system access](/protocol/v1/file-system). ## Creating When the language model requests a tool invocation, the Agent **SHOULD** report it to the Client: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "tool_call", "toolCallId": "call_001", "title": "Reading configuration file", "name": "read_file", "kind": "read", "status": "pending" } } } ``` **toolCallId** `ToolCallId` *required* A unique identifier for this tool call within the session **title** `string` *required* A human-readable title describing what the tool is doing **name** `string` The programmatic name of the invoked tool, such as `read_file`. This identifies which tool is being used. `title` describes this invocation for users, while `kind` provides a coarse presentation category. If omitted or `null` on the initial tool call, no name is provided. Names are opaque, informational metadata and do not advertise a capability or grant authorization. Agents **SHOULD** include the name when available and **SHOULD NOT** change it later except to correct metadata. **kind** `ToolKind` The category of tool being invoked. **kinds** * `read` - Reading files or data * `edit` - Modifying files or content * `delete` - Removing files or data * `move` - Moving or renaming files * `search` - Searching for information * `execute` - Running commands or code * `think` - Internal reasoning or planning * `fetch` - Retrieving external data * `switch_mode` - Switching the session mode * `other` - Other tool types (default) Tool kinds help Clients choose appropriate icons and optimize how they display tool execution progress. **status** `ToolCallStatus` The current [execution status](#status) (defaults to `pending`) **content** `ToolCallContent[]` [Content produced](#content) by the tool call **locations** `ToolCallLocation[]` [File locations](#following-the-agent) affected by this tool call **rawInput** `unknown` The raw input sent to the tool. Any JSON value is accepted, including objects, arrays, strings, numbers, booleans, and `null`. **rawOutput** `unknown` The raw output returned by the tool. Any JSON value is accepted, including objects, arrays, strings, numbers, booleans, and `null`. Omission and `null` are equivalent for `rawInput` and `rawOutput`. On an initial tool call, both mean no value is provided. On a tool call update, both leave the previously reported value unchanged. ## Updating As tools execute, Agents send updates to report progress and results. Updates use the `session/update` notification with `tool_call_update`: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "tool_call_update", "toolCallId": "call_001", "status": "in_progress", "content": [ { "type": "content", "content": { "type": "text", "text": "Found 3 configuration files..." } } ] } } } ``` All fields except `toolCallId` are optional in updates. Only the fields being changed need to be included. For `name`, a string sets or replaces the tool name. Omission and `null` both leave the existing name unchanged, so ACP v1 cannot clear a previously reported name. ## Requesting permission The Agent **MAY** request permission from the user before executing a tool call by calling the `session/request_permission` method: ```json theme={null} { "jsonrpc": "2.0", "id": 5, "method": "session/request_permission", "params": { "sessionId": "sess_abc123def456", "toolCall": { "toolCallId": "call_001" }, "options": [ { "optionId": "allow-once", "name": "Allow once", "kind": "allow_once" }, { "optionId": "reject-once", "name": "Reject", "kind": "reject_once" } ] } } ``` **sessionId** `SessionId` *required* The session ID for this request **toolCall** `ToolCallUpdate` *required* The tool call update containing details about the operation **options** `PermissionOption[]` *required* Available [permission options](#permission-options) for the user to choose from The Client responds with the user's decision: ```json theme={null} { "jsonrpc": "2.0", "id": 5, "result": { "outcome": { "outcome": "selected", "optionId": "allow-once" } } } ``` Clients **MAY** automatically allow or reject permission requests according to the user settings. If the current prompt turn gets [cancelled](/protocol/v1/prompt-turn#cancellation), the Client **MUST** respond with the `"cancelled"` outcome: ```json theme={null} { "jsonrpc": "2.0", "id": 5, "result": { "outcome": { "outcome": "cancelled" } } } ``` **outcome** `RequestPermissionOutcome` *required* The user's decision, either: - `cancelled` - The [prompt turn was cancelled](/protocol/v1/prompt-turn#cancellation) - `selected` with an `optionId` - The ID of the selected permission option ### Permission options Each permission option provided to the Client contains: **optionId** `string` *required* Unique identifier for this option **name** `string` *required* Human-readable label to display to the user **kind** `PermissionOptionKind` *required* A hint to help Clients choose appropriate icons and UI treatment for each option. * `allow_once` - Allow this operation only this time * `allow_always` - Allow this operation and remember the choice * `reject_once` - Reject this operation only this time * `reject_always` - Reject this operation and remember the choice The Agent owns remembered decisions. When the user selects an `allow_always` or `reject_always` option, the Agent stores the decision, decides its scope (for example a tool, a command, or a directory) and how long it lasts, and applies it by not asking again. `kind` is only a UI hint. The option `name` describes the scope. ### Security * Clients **SHOULD** describe the operation from the tool call's `kind`, `locations`, and content, present `title` as Agent-authored text, and show commands and paths in full. * Agents **SHOULD NOT** give an option a `name` that contradicts its `kind`, and **SHOULD** act on a selected option according to its known `kind`. * Automatic approval **SHOULD NOT** rely only on `title` or option `name`. * Agents **SHOULD NOT** treat an outcome they don't recognize as approval. * Agents **SHOULD** perform only the operation the approved request described, and **SHOULD** request again if the command or resolved target changes. * Agents **SHOULD** state the scope of a remembered decision (`allow_always`, `reject_always`) in the option `name` and **SHOULD NOT** apply it beyond that scope. * Agents **SHOULD NOT** switch to a mode or configuration that reduces user oversight without user action. ## Status Tool calls progress through different statuses during their lifecycle: **pending** The tool call hasn't started running yet because the input is either streaming or awaiting approval **in\_progress** The tool call is currently running **completed** The tool call completed successfully **failed** The tool call failed with an error ## Content Tool calls can produce different types of content: ### Regular content Standard [content blocks](/protocol/v1/content) like text, images, or resources: ```json theme={null} { "type": "content", "content": { "type": "text", "text": "Analysis complete. Found 3 issues." } } ``` ### Diffs File modifications shown as diffs: ```json theme={null} { "type": "diff", "path": "/home/user/project/src/config.json", "oldText": "{\n \"debug\": false\n}", "newText": "{\n \"debug\": true\n}" } ``` **path** `string` *required* The absolute file path being modified **oldText** `string` The original content (null for new files) **newText** `string` *required* The new content after modification ### Terminals Live terminal output from command execution: ```json theme={null} { "type": "terminal", "terminalId": "term_xyz789" } ``` **terminalId** `string` *required* The ID of a terminal created with `terminal/create` When a terminal is embedded in a tool call, the Client displays live output as it's generated and continues to display it even after the terminal is released. > [card] > > Learn more about Terminals > > [Open](/protocol/v1/terminals) ## Following the Agent Tool calls can report the file locations they're working with. Clients can use this to follow along, showing which files the Agent is reading or modifying as it works. ```json theme={null} { "path": "/home/user/project/src/main.py", "line": 42 } ``` **path** `string` *required* The absolute file path being accessed or modified **line** `integer | null` Optional 1-based line number within the file, represented as an unsigned 32-bit integer. Omission and `null` are equivalent and mean no specific line was provided. Locations are display metadata and do not grant file access. Clients **SHOULD NOT** automatically open locations outside the session's [root set](/protocol/v1/session-setup#workspace-root-security). # Transports Source: https://agentclientprotocol.com/protocol/v1/transports Mechanisms for agents and clients to communicate with each other ACP uses JSON-RPC to encode messages. JSON-RPC messages **MUST** be UTF-8 encoded. The protocol currently defines one transport mechanism for agent-client communication: [stdio](#stdio), communication over standard in and standard out. A remote transport based on Streamable HTTP is being specified in the [transport RFD](/rfds/streamable-http-websocket-transport). Agents and clients **SHOULD** support stdio whenever possible. It is also possible for agents and clients to implement [custom transports](#custom-transports). ## stdio In the **stdio** transport: * The client launches the agent as a subprocess. * The agent reads JSON-RPC messages from its standard input (`stdin`) and sends messages to its standard output (`stdout`). * Messages are individual JSON-RPC requests, notifications, or responses. * Messages are delimited by newlines (`\n`), and **MUST NOT** contain embedded newlines. * The agent **MAY** write UTF-8 strings to its standard error (`stderr`) for logging purposes. Clients **MAY** capture, forward, or ignore this logging. * The agent **MUST NOT** write anything to its `stdout` that is not a valid ACP message. * The client **MUST NOT** write anything to the agent's `stdin` that is not a valid ACP message. ```mermaid theme={null} sequenceDiagram participant Client participant Agent Process Client->>+Agent Process: Launch subprocess loop Message Exchange Client->>Agent Process: Write to stdin Agent Process->>Client: Write to stdout Agent Process--)Client: Optional logs on stderr end Client->>Agent Process: Close stdin, terminate subprocess deactivate Agent Process ``` ## Custom transports Agents and clients **MAY** implement additional custom transport mechanisms to suit their specific needs. The protocol is transport-agnostic and can be implemented over any communication channel that supports bidirectional message exchange. Implementers who choose to support custom transports **MUST** ensure they preserve the JSON-RPC message format and lifecycle requirements defined by ACP. Custom transports **SHOULD** document their specific connection establishment and message exchange patterns to aid interoperability. # Agent Plan Source: https://agentclientprotocol.com/protocol/v2/agent-plan How Agents communicate their execution plans A plan is the Agent's list of steps for a multi-step task. Each entry has a description, a priority, and a status. Agents may send plans to Clients through [`session/update`](/protocol/v2/prompt-lifecycle#3-agent-reports-output) notifications and update them as work progresses. `plan_update` carries a `plan` object with a `type` discriminator and a required `planId` so Clients can track multiple plans independently. The plan content type is `items`. Additional plan operations remain unstable while the Plan Operations RFD is in progress. ## Creating plans When the language model creates an execution plan, the Agent **SHOULD** report it to the Client with `plan_update`. ### Item-based plans ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "plan_update", "plan": { "type": "items", "planId": "plan-1", "entries": [ { "content": "Analyze the existing codebase structure", "priority": "high", "status": "pending" }, { "content": "Identify components that need refactoring", "priority": "high", "status": "pending" }, { "content": "Create unit tests for critical functions", "priority": "medium", "status": "pending" } ] } } } } ``` **plan.type** `string` *required* The plan content type. **plan.planId** `PlanId` *required* A unique identifier for this plan within the session. **plan.entries** `PlanEntry[]` *required* An array of [plan entries](#plan-entries) representing the tasks to be accomplished. ## Extensibility `plan.type` values can be custom or future variants when Clients can preserve or display them generically. Custom plan content types **MUST** begin with `_`. Unknown non-underscore plan content types are reserved for future ACP variants. Every plan content variant, including custom or future variants, **MUST** carry a `planId`. ## Plan entries Each plan entry represents a specific task or goal within the overall execution strategy: **content** `string` *required* A human-readable description of what this task aims to accomplish **priority** `PlanEntryPriority` *required* The relative importance of this task. * `high` * `medium` * `low` Custom or future priority values can be used for display hints. Custom priorities **MUST** begin with `_`. Unknown non-underscore priorities are reserved for future ACP variants. **status** `PlanEntryStatus` *required* The current execution status of this task * `pending` * `in_progress` * `completed` * `cancelled` Custom or future status values can be used when Clients can preserve or display a generic plan-entry state. Custom statuses **MUST** begin with `_`. Unknown non-underscore statuses are reserved for future ACP variants. ## Updating plans As the Agent progresses through the plan, it **SHOULD** report updates by sending more `session/update` notifications with the same `sessionUpdate: "plan_update"` structure and `planId`. Each `plan_update` replaces the whole plan with that `planId`, whatever its `type`, including when the type differs from the previous update. A Client that doesn't understand the new `type` still treats the update as replacing that plan, so it stops showing the previous content. For item-based plans, the Agent **MUST** send a complete list of all plan entries in each update and their current status. The Client **MUST** replace the current contents of that plan completely. An empty `entries` array empties the plan. Clients **MAY** hide an empty plan. ### Dynamic planning Plans can change during execution. The Agent **MAY** add, remove, or modify plan entries as it discovers new requirements or completes tasks. # Authentication Source: https://agentclientprotocol.com/protocol/v2/authentication Authenticating with agents and logging out ACP authentication is negotiated during [initialization](/protocol/v2/initialization). Agents advertise available authentication methods in `authMethods`. A non-empty list makes `auth/login` and `auth/logout` available, while each authentication method type defines whether the Client invokes `auth/login`. ```mermaid theme={null} sequenceDiagram participant Client participant Agent participant Login as Interactive login process Client->>Agent: initialize Agent-->>Client: initialize response (authMethods) alt Agent handles login Client->>Agent: auth/login (methodId) Agent-->>Client: auth/login response else Terminal authentication Client->>Login: launch configured Agent program Login-->>Client: login succeeds Client->>Agent: reconnect and initialize end Note over Client,Agent: Authenticated requests may proceed alt Agent advertises authMethods and user logs out Client->>Agent: auth/logout Agent-->>Client: auth/logout response end Note over Client,Agent: Authentication-gated requests require authentication again ``` ## Advertising authentication Agents advertise authentication options in the `authMethods` field of the `initialize` response. Every method has a `methodId`, but the Client sends that ID to `auth/login` only for a method whose type defines that protocol-driven flow. Returning a non-empty `authMethods` list advertises `auth/login` and `auth/logout`. Each `methodId` **MUST** be unique within the list. An Agent that does so **MUST** implement both `auth/login` and `auth/logout`. If `authMethods` is omitted or empty, the Agent does not advertise these methods and Clients **MUST NOT** call either one. `capabilities.auth` is orthogonal to this requirement. It advertises authentication-related extensions, not the availability of the baseline `auth/login` and `auth/logout` methods. ```json highlight={8-15} theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 2, "capabilities": {}, "authMethods": [ { "methodId": "agent-login", "name": "Agent login", "type": "agent", "description": "Sign in using the agent's login flow" } ], "info": { "name": "my-agent", "title": "My Agent", "version": "1.0.0" } } } ``` Because this response has a non-empty `authMethods` list, the Agent **MUST** support both `auth/login` and `auth/logout`. ### Authentication method types The standard authentication method type is `agent`, where the Agent handles authentication through `auth/login`. Every authentication method **MUST** include a `type` discriminator: ```json theme={null} { "methodId": "agent-login", "name": "Agent login", "type": "agent", "description": "Sign in using the agent's login flow" } ``` The `terminal` type tells the Client to run the configured Agent program interactively: ```json theme={null} { "methodId": "terminal-login", "name": "Log in from the terminal", "type": "terminal", "args": ["--login"], "env": [ { "name": "ACP_INTERACTIVE_LOGIN", "value": "1" } ] } ``` Authentication method `type` values can be custom or future variants. Custom method types **MUST** begin with `_`. Unknown non-underscore method types are reserved for future ACP variants. Clients that do not understand a method type **SHOULD** preserve the raw method payload when storing, replaying, proxying, or forwarding initialization data, and otherwise ignore the method or display it generically. Terminal authentication methods require Client support. Clients advertise this during initialization with `capabilities.auth.terminal`: ```json highlight={7-9} theme={null} { "jsonrpc": "2.0", "id": 0, "method": "initialize", "params": { "protocolVersion": 2, "capabilities": { "auth": { "terminal": {} } }, "info": { "name": "my-client", "title": "My Client", "version": "1.0.0" } } } ``` If `capabilities.auth.terminal` is omitted or `null`, the Client does not advertise support. Supplying `{}` means the Client can reproduce the configured Agent invocation in an interactive terminal. Agents **MUST NOT** advertise a `terminal` method unless this capability is present. Clients ignore `terminal` methods they did not enable. See the [schema](/protocol/v2/schema#authmethod) for the full `AuthMethod` definitions and the [Terminal Authentication RFD](/rfds/auth-methods) for the design. ## Agent-handled authentication When an Agent requires authentication and the selected method's type defines a protocol-driven login flow, the Client calls `auth/login` with that advertised method's ID: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "auth/login", "params": { "methodId": "agent-login" } } ``` **methodId** `string` *required* The ID of an advertised authentication method whose type defines the `auth/login` flow. Clients **MUST NOT** pass a `terminal` method. `auth/login` may stay pending while the user completes an interactive flow. The Agent can run that flow itself, for example by opening a local browser, or through a URL-mode [elicitation](/protocol/v2/elicitation) scoped to the `auth/login` request with `requestId`. Whether authentication outlasts the connection is up to the Agent. Credentials are often stored where other connections can use them. On success, the Agent returns an empty result: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": {} } ``` If `methodId` is not an advertised method whose type uses `auth/login`, the Agent responds with `-32602` (Invalid params). If login fails or the user abandons it, the Agent responds with `-32000` (Authentication required). A login cancelled with [`$/cancel_request`](/protocol/v2/cancellation) gets `-32800`. When the Agent requires authentication, any request except `initialize`, `auth/login`, and `auth/logout` may fail with `auth_required` (`-32000`). After successful authentication, the Client can create new sessions without receiving an `auth_required` error for authentication-gated requests. ## Terminal authentication For a `terminal` method, the Client: 1. Launches a separate interactive process using the same configured Agent program and base launch configuration as the ACP connection. 2. Appends the method's `args` and applies its `env`, overriding any same-named variables in the base launch configuration. Every `env` entry **MUST** have a unique `name`. 3. 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, retries an operation rejected for requiring authentication. The Client **SHOULD** first close the existing ACP connection, start and initialize a new one, and resume with `session/resume` any sessions it wants to keep, since the running Agent may not pick up the new credentials. It **MAY** instead retry on the existing connection first, and reconnect only if the retry still fails with `auth_required`. For an already-inserted prompt, see [Authentication failures during session work](#authentication-failures-during-session-work). The descriptor cannot provide a command. The Client derives the command from its own Agent configuration. Agents **SHOULD** provide arguments that enter a login-only flow and exit when it completes. ACP does not define an output pattern or other in-band success signal. Clients may recognize implementation-specific signals only as an extension. The terminal process is not the ACP connection, so the Client **MUST NOT** send an `auth/login` request for a terminal method. ### Launch safety * Clients **SHOULD** pass `args` as separate arguments rather than building a shell command line from them, and **SHOULD NOT** offer terminal authentication when the launch target re-parses arguments, such as a remote shell or a Windows batch file. * Clients **SHOULD NOT** apply `env` entries that change program lookup, dynamic loading, interpreter or shell startup, or proxy and TLS trust without user approval. Examples include `PATH`, `LD_*`, `DYLD_*`, `NODE_OPTIONS`, `PYTHONPATH`, `BASH_ENV`, `HTTPS_PROXY`, and `SSL_CERT_FILE`. * Clients **SHOULD** show the appended `args` and `env` before launch. `env` values **SHOULD NOT** contain secrets. ## Authentication failures during session work `auth_required` (`-32000`) applies in v2 both to rejected requests and to authentication failures that end foreground work. For `session/prompt`, the reporting channel depends on whether the user message was inserted: * Before insertion, the Agent returns an `auth_required` JSON-RPC error response. * After insertion, the Agent **MUST** respond successfully with the inserted `messageId`, even if authentication fails before the response is sent. If the failure terminates foreground work, the Agent **MUST** report `idle` and **SHOULD** include `stopReason: "error"` with `error.code: -32000`. Clients may prompt the user to complete an advertised authentication flow. Successful authentication does not itself restart work that already ended. Resending the prompt inserts a new message and does not undo the original insertion or any tool side effects. Clients **SHOULD NOT** automatically resubmit an inserted prompt as though it had been rejected. See [Failures](/protocol/v2/prompt-lifecycle#failures). ## Logging out The `auth/logout` method allows Clients to end the current authenticated state. Clients may call it only when the Agent advertised one or more authentication methods during initialization. There is no separate logout capability marker. ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "auth/logout", "params": {} } ``` On success, the Agent returns an empty result: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "result": {} } ``` After a successful `auth/logout`, authentication-gated requests will require the user to complete one of the advertised authentication flows again. ## Active sessions The protocol does not guarantee what happens to already-running sessions after `auth/logout`. Agents may terminate them, keep them running, or return `auth_required` errors for future session activity. Clients **SHOULD** be prepared for active session operations to fail with authentication-related errors after logout and **SHOULD** prompt the user to authenticate again when appropriate. # Cancellation Source: https://agentclientprotocol.com/protocol/v2/cancellation Mechanisms for request cancellation ACP uses JSON-RPC 2.0 for making requests and getting responses. The JSON-RPC specification doesn't define any standard mechanism for request cancellation and keeps it up to the implementation. ## `$/cancel_request` notification To make cancellation consistent, ACP defines a `$/cancel_request` notification that can be sent to cancel requests. Its `requestId` identifies a request that the sender of `$/cancel_request` issued. Receivers match it only against requests they received from that sender, since each side chooses its own request IDs. Cancellation remains optional as it might not be implementable in all clients or servers. For example if the implementation uses a single threaded synchronous programming language then there is little it can do to react to a `$/cancel_request` notification. When a `$/cancel_request` notification is received by a supporting implementation, the implementation: * **MAY** cancel the corresponding request activity and all nested activities related to that request * **MAY** finish sending any pending notifications before responding * **MUST** still send a response for the original request If the request already finished, or the receiver doesn't cancel it, the receiver sends its normal response. Receivers **MUST** ignore a `$/cancel_request` for a request ID that is unknown or already answered, and **MUST NOT** send a second response for it. If the receiver does cancel the request, it sends one of these responses: * A successful response, where the method defines one for cancellation: `session/prompt` after its user message is inserted (with its `messageId`), `session/request_permission` with the `cancelled` outcome, or `elicitation/create` with the `cancel` action * An error response with code [`-32800` (Request Cancelled)](/protocol/v2/schema#errorcode) A sender that stops waiting for a response, for example after a timeout or because the work that needed it ended, **SHOULD** send `$/cancel_request` for that request so the receiver can stop work or dismiss UI. The calling side **MAY** implement graceful cancellation processing by waiting for the response from the remote side. Cancellation **MAY** also be done explicitly on a per-feature basis within the protocol to cover specific scenarios, such as cancellation of [active session work](/protocol/v2/prompt-lifecycle#cancellation). `session/cancel` and `$/cancel_request` have different scopes. Cancelling one permission or elicitation request does not automatically cancel the whole foreground workflow or determine its state. The Agent applies the aggregate [state-transition rules](/protocol/v2/prompt-lifecycle#state-transitions). On `session/cancel`, the Agent stops waiting for pending permission requests of the cancelled foreground work and **SHOULD** cancel each of them with `$/cancel_request`. Clients **MAY** answer such a request with the `cancelled` outcome without waiting for `$/cancel_request`. After cancellation completes, Agents **SHOULD** ignore late answers rather than use them to resume the cancelled work. After aborting active foreground work and sending its final updates, the Agent **MUST** report `idle` with `stopReason: "cancelled"`. No additional completion update is required if no foreground work was active. See [Elicitation Cancellation](/protocol/v2/elicitation#session-cancellation) for selective cancellation of related requests and external URL interactions. ## Internal cancellation Requests can also be cancelled internally by the executing party without receiving `$/cancel_request`: * On the Client, the user closes the IDE or switches projects, or a file becomes unavailable. * On the Agent, the LLM context limit is reached, an internal timeout fires, or resources run out. When internal cancellation occurs, the executing party **SHOULD**: * Send the same response it would send for `$/cancel_request`: the method's defined cancellation result where one exists (an inserted prompt's `messageId`, a `cancelled` permission outcome, or an elicitation `cancel` action), otherwise `-32800` (Request Cancelled) * Ensure consistent behavior regardless of cancellation source Both kinds of cancellation answer `session/prompt` with `-32800` only before the user message is inserted. Once it is inserted, the Agent responds successfully with its `messageId`, and the work it started is stopped with [`session/cancel`](/protocol/v2/prompt-lifecycle#cancellation) or ends with the matching [stop reason](/protocol/v2/prompt-lifecycle#stop-reasons). See [Prompt Accepted](/protocol/v2/prompt-lifecycle#2-prompt-accepted). ## Example: cascading cancellation flow Sending `session/cancel` does not automatically cancel outstanding Agent-to-Client requests. The Agent sends `$/cancel_request` for the permission requests of the cancelled work, as specified in [active session work cancellation](/protocol/v2/prompt-lifecycle#cancellation), and the Client answers each one with the `cancelled` outcome. ```mermaid theme={null} sequenceDiagram participant Client participant Agent Note over Client,Agent: 1. Session prompt in progress Client->>Agent: session/prompt (id=1, "Analyze file X") Agent-->>Client: response to id=1 (messageId) Agent->>Client: session/update (user_message) Agent->>Client: session/update (state_update: running) Note over Client,Agent: 2. Agent makes concurrent permission requests Agent->>Client: session/request_permission (id=2, "read sensitive file") Agent->>Client: session/request_permission (id=3, "apply workspace changes") Note over Client,Agent: 3. Client cancels active session work Client->>Agent: session/cancel (sessionId) Note over Client,Agent: 4. Agent cancels pending permission requests Agent->>Client: $/cancel_request (requestId=2) Agent->>Client: $/cancel_request (requestId=3) Client->>Agent: response to id=2 (outcome: cancelled) Client->>Agent: response to id=3 (outcome: cancelled) Note over Client,Agent: 5. Agent stops active work and reports cancellation completion Agent->>Client: session/update (state_update: idle, stopReason: "cancelled") ``` # Content Source: https://agentclientprotocol.com/protocol/v2/content Understanding content blocks in the Agent Client Protocol A content block is one piece of user-facing content: text, an image, audio, a link to a resource, or an embedded resource. Content blocks appear in: * User prompts sent via [`session/prompt`](/protocol/v2/prompt-lifecycle#1-user-message) * Language model output reported through [`session/update`](/protocol/v2/prompt-lifecycle#3-agent-reports-output) notifications as message updates or streamed chunks * Progress updates and results from [tool calls](/protocol/v2/tool-calls), including streamed tool-call content chunks ## Content types Content from the Agent is untrusted. See [Rendering Agent Content](/protocol/v2/security#rendering-agent-content) and [URIs and Remote Resources](/protocol/v2/security#uris-and-remote-resources). ACP's `ContentBlock` is compatible with, and a superset of, the [Model Context Protocol (MCP) 2026-07-28 `ContentBlock`](https://modelcontextprotocol.io/specification/2026-07-28/schema#contentblock), so Agents can forward content from MCP tool outputs unchanged. ACP adds an optional `uri` on image content, `_meta` on icons and annotations, extensible `Role` and `IconTheme` values, and the open `type` fallback described below. A content type from a later MCP revision that ACP doesn't define isn't forwarded as is. Agents convert it to a supported type, such as an embedded resource, or omit it. Content block `type` values can be custom or future variants when the receiver can preserve or display them generically. Custom content block types **MUST** begin with `_`. Unknown non-underscore content block types are reserved for future ACP variants. In prompts, Clients send only baseline content types (`text` and `resource_link`) and content types the Agent advertised, including custom types advertised through a [custom capability](/protocol/v2/extensibility#advertising-custom-capabilities), and Agents reject others with `-32602`. When displaying Agent output, Clients **SHOULD** show text content. For image, audio, resource, and resource link content they can't render, Clients **SHOULD** show a placeholder with whatever identifies it, such as its name, title, URI, or MIME type, and **SHOULD NOT** drop it silently. Agents that need content to reach the user in a particular form **SHOULD** also include it as text. `annotations` are hints with [MCP semantics](https://modelcontextprotocol.io/specification/2026-07-28/schema#annotations). In `audience`, `user` means the person using the Client and `assistant` means the Agent's model. `priority` ranges from 0 (least important) to 1 (most important). Clients **MAY** collapse or hide content whose `audience` doesn't include `user`, which is an exception to the display rule above. ### Text content Text may be plain text or Markdown. Clients **SHOULD** render it as [CommonMark](https://spec.commonmark.org/), and **MAY** support [GitHub Flavored Markdown](https://github.github.com/gfm/) extensions such as tables. This applies wherever a text block appears, including user messages, thoughts, and tool-call content. See [Rendering Agent Content](/protocol/v2/security#rendering-agent-content) for raw HTML. ```json theme={null} { "type": "text", "text": "What's the weather like today?" } ``` All Agents **MUST** support text content blocks when included in prompts. **text** `string` *required* The text content to display **annotations** `Annotations` Optional metadata about how the content should be used or displayed. [Learn more](https://modelcontextprotocol.io/specification/2026-07-28/schema#annotations). ### Image content Images can be included for visual context or analysis. ```json theme={null} { "type": "image", "mimeType": "image/png", "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB..." } ``` Requires the `image` [prompt capability](/protocol/v2/initialization#session-prompt-capabilities) when included in prompts. **data** `string` *required* Base64-encoded image data **mimeType** `string` *required* The MIME type of the image (e.g., "image/png", "image/jpeg") **uri** `string` Optional URI reference for the image source **annotations** `Annotations` Optional metadata about how the content should be used or displayed. [Learn more](https://modelcontextprotocol.io/specification/2026-07-28/schema#annotations). ### Audio content Audio data for transcription or analysis. ```json theme={null} { "type": "audio", "mimeType": "audio/wav", "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAAB..." } ``` Requires the `audio` [prompt capability](/protocol/v2/initialization#session-prompt-capabilities) when included in prompts. **data** `string` *required* Base64-encoded audio data **mimeType** `string` *required* The MIME type of the audio (e.g., "audio/wav", "audio/mp3") **annotations** `Annotations` Optional metadata about how the content should be used or displayed. [Learn more](https://modelcontextprotocol.io/specification/2026-07-28/schema#annotations). ### Embedded resource Complete resource contents embedded directly in the message. ```json theme={null} { "type": "resource", "resource": { "uri": "file:///home/user/script.py", "mimeType": "text/x-python", "text": "def hello():\n print('Hello, world!')" } } ``` This is the preferred way to include context in prompts, such as when using @-mentions to reference files or other resources. By embedding the content directly in the request, Clients can include context from sources that the Agent may not have direct access to. Requires the `embeddedContext` [prompt capability](/protocol/v2/initialization#session-prompt-capabilities) when included in prompts. **resource** `EmbeddedResourceResource` *required* The embedded resource contents, which can be either: **Text Resource** **uri** `string` *required* The URI identifying the resource **text** `string` *required* The text content of the resource **mimeType** `string` Optional MIME type of the text content **Blob Resource** **uri** `string` *required* The URI identifying the resource **blob** `string` *required* Base64-encoded binary data **mimeType** `string` Optional MIME type of the blob **annotations** `Annotations` Optional metadata about how the content should be used or displayed. [Learn more](https://modelcontextprotocol.io/specification/2026-07-28/schema#annotations). ### Resource link References to resources that the receiver may be able to read. All Agents **MUST** support resource links when included in prompts. ```json theme={null} { "type": "resource_link", "uri": "file:///home/user/document.pdf", "name": "document.pdf", "mimeType": "application/pdf", "icons": [ { "src": "https://example.com/icons/pdf.png", "mimeType": "image/png", "sizes": ["48x48"] } ], "size": 1024000 } ``` **uri** `string` *required* The URI of the resource **name** `string` *required* A human-readable name for the resource **mimeType** `string` The MIME type of the resource **title** `string` Optional display title for the resource **description** `string` Optional description of the resource contents **icons** `Icon[]` Optional icons Clients can display for this resource. Each icon requires a `src` URI and may include `mimeType`, `sizes`, and `theme`. **size** `integer` Optional size of the resource in bytes **annotations** `Annotations` Optional metadata about how the content should be used or displayed. [Learn more](https://modelcontextprotocol.io/specification/2026-07-28/schema#annotations). # Elicitation Source: https://agentclientprotocol.com/protocol/v2/elicitation Requesting structured information from users Elicitation lets an Agent ask a user for structured information through the Client. It is based on the locked [MCP 2026-07-28 elicitation specification](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation) and supports two modes: * **Form mode** collects non-sensitive data using a restricted JSON Schema. * **URL mode** opens an out-of-band interaction for sensitive or externally hosted workflows such as OAuth. ## User interaction requirements Clients **MUST** clearly identify the Agent requesting information, respect user privacy, and provide clear decline and cancel controls. For form mode, Clients **MUST** let users review and modify responses before sending them. For URL mode, Clients **MUST** display the target host and obtain consent before navigating to it. Clients **SHOULD** present the request's `message` so users understand what is requested and why. ## Checking support Clients advertise elicitation support in `capabilities.elicitation` during [initialization](/protocol/v2/initialization#client-capabilities). ```json theme={null} { "capabilities": { "elicitation": { "form": {}, "url": {} } } } ``` Capability objects have the following semantics: * An omitted or `null` top-level `elicitation` field means elicitation is unsupported. * Form support exists only when `form` is explicitly present and non-null. URL support exists only when `url` is explicitly present and non-null. * An omitted or `null` mode field means that mode is not advertised. * A present capability object may advertise zero, one, or both modes. `{}` and `{"form":null,"url":null}` advertise no supported modes. This deliberately differs from MCP 2026-07-28, where an empty elicitation capability retains the original form-only meaning. ACP requires each supported mode to be explicit. An Agent that forwards elicitation for an MCP server **MUST NOT** copy the Client's capability object to that server unchanged. It advertises each mode the Client supports explicitly, and omits the MCP `elicitation` capability when the Client advertises no modes. Agents **MUST NOT** request a mode the Client has not advertised. Agents **SHOULD** provide a graceful fallback when the required mode is unavailable. If an Agent sends `elicitation/create` anyway, a Client with no `elicitation` capability (omitted or `null`) responds with `-32601`, as for any [capability-gated method](/protocol/v2/error#unknown-methods) it did not advertise. A Client that advertised `elicitation` but not the requested mode responds with `-32602` (Invalid params). ## Creating an elicitation The Agent sends an `elicitation/create` request directly over the ACP connection. This adapts the MCP 2026-07-28 data model. ACP also requires `mode` explicitly. It does not apply MCP's omitted-mode form default. Scope is represented with flattened fields. Exactly one of `sessionId` or `requestId` **MUST** be present: * `sessionId` for a session-scoped request. It can also include `toolCallId` to associate the request with a tool call in that session. * `requestId` for a request-scoped interaction outside a session. It **MUST** be the ID of a Client-to-Agent request on the same connection that the Agent has not yet responded to. The Agent **MUST** cancel any pending request-scoped elicitations before it responds to their request. Agents **MUST** bind each elicitation and related state to the receiving Client connection and, when authentication exists, the verified user identity. A `sessionId` alone or an unverified Client-provided identity is not sufficient. ### Foreground state A session-scoped elicitation follows the aggregate [foreground-state contract](/protocol/v2/prompt-lifecycle#waiting-for-user-action). When foreground work cannot progress without user action, the Agent **SHOULD** report `requires_action`. Once reported, it **MUST** report `running` when progress resumes, or `idle` if the work ends without resuming. An elicitation does not by itself start foreground work. Requests for independent background activity can be presented while the session remains `idle`. Request-scoped elicitations outside a session do not change any session's foreground state. Multiple outstanding requests are tracked individually, but their creation and responses do not each cause state updates. The Agent remains `running` while other foreground work can progress, and remains `requires_action` while the foreground workflow is still blocked. In URL mode, `accept` only means consent to open the URL. If foreground work still needs the user to finish the external interaction, a reported `requires_action` remains unchanged. The Agent reports `running` when foreground progress actually resumes. `elicitation/complete` is not itself a state update. ### Form mode ```json theme={null} { "jsonrpc": "2.0", "id": 43, "method": "elicitation/create", "params": { "sessionId": "sess_abc123", "mode": "form", "message": "How should I approach this refactoring?", "requestedSchema": { "type": "object", "properties": { "strategy": { "type": "string", "enum": ["conservative", "balanced", "aggressive"] } }, "required": ["strategy"] } } } ``` `requestedSchema` is a flat object with `type: "object"`, `properties`, and optional `required`, `title`, and `description`. Each property is one of: | Property | Schema | Optional keywords | | - | - | - | | Text | `type: "string"` | `minLength`, `maxLength`, `pattern`, `format` (`email`, `uri`, `date`, `date-time`), `default` | | Single select | `type: "string"` with `enum` (values) or `oneOf` (`const` and `title` options) | `default` | | Number | `type: "number"` or `type: "integer"` | `minimum`, `maximum`, `default` | | Boolean | `type: "boolean"` | `default` | | Multi select | `type: "array"` with `items` of `{ "type": "string", "enum": [...] }` or `{ "anyOf": [...] }` (`const` and `title` options) | `minItems`, `maxItems`, `default` | Every property may also have `title` and `description`. `pattern` uses ECMA-262 regular expression syntax, as in JSON Schema. Clients treat an unknown `format` as plain text. Accepted `content` maps each answered property name to its value: a string for text and single-select properties, a number for `number` and `integer`, a boolean for `boolean`, and an array of strings for multi-select. Unanswered properties are omitted, not set to `null`. Custom or future property types may use other JSON values. Clients **SHOULD** validate submitted values before responding, and Agents **SHOULD** validate them again. If a Client cannot render a form, it **SHOULD** respond with `-32602` (Invalid params), not `decline` or `cancel`, which report a user's choice. This includes a required property of an unknown type, a `required` entry with no matching property, and a property that sets both `enum` and `oneOf`. Clients **MAY** leave out optional properties of unknown types and render the rest. Clients **SHOULD** ignore a `default` that does not match its property schema. Clients that support schema defaults **SHOULD** pre-populate form fields with their declared default values. Form mode **MUST NOT** be used to request secrets or credentials that grant access or authorize transactions, such as passwords, API keys, access or refresh tokens, private keys, recovery codes, or payment credentials. Ordinary profile information such as a name, email address, or username is not categorically prohibited. Agents **MUST** use URL mode for sensitive interactions. If the Client does not support URL mode, the Agent **MUST NOT** fall back to form mode. It **MUST** use another safe flow or fail the operation. ### URL mode ```json theme={null} { "jsonrpc": "2.0", "id": 44, "method": "elicitation/create", "params": { "requestId": 12, "mode": "url", "elicitationId": "github-oauth-001", "url": "https://agent.example.com/connect?elicitationId=github-oauth-001", "message": "Please authorize access to your repositories." } } ``` An `accept` response means the user consented to open the URL. It does not mean the external interaction completed. URL mode is not a substitute for authorizing the Client's access to the Agent. An Agent can still use it during `auth/login` to sign in to its own provider. Agents **MUST NOT** send credentials or tokens obtained through URL mode back over ACP or place them in Client or model context. ## Responses The Client responds with one of three actions: * `accept`: the user submitted or consented to the interaction. * `decline`: the user explicitly declined. * `cancel`: the user dismissed the interaction without choosing. Agents **MUST** handle an unknown action as `cancel`. The `content` field is optional on `accept`. Receivers treat omission and `null` equivalently. It is only meaningful for `accept`. Receivers ignore it for `decline` and `cancel`. For an accepted form elicitation, `content` **SHOULD** conform to the requested schema. Receivers accept any JSON value in `content` and validate it against the schema, so an unexpected value invalidates only that property, not the whole response. For an accepted URL elicitation, clients normally omit `content` because the interaction happens out of band. Agents **MUST NOT** assume an elicitation succeeds. They **MUST** handle `decline`, `cancel`, and failures by safely falling back, retrying, or failing the originating operation as appropriate. ### URL completion Unlike MCP 2026-07-28, ACP retains an `elicitationId` and completion notification for its direct request flow. The Agent **MUST** keep each `elicitationId` unique among outstanding URL elicitations on that Agent-Client connection, and the Client **MUST** treat it as opaque. The Agent **MAY** send `elicitation/complete` after the external interaction finishes. It **MUST** send that notification only to the same Client that received the original request and include the original `elicitationId`. Clients **MUST** ignore unknown or already-completed IDs. On receiving it, Clients **MAY** retry the original operation, update the UI, or otherwise continue. They **SHOULD** still let the user retry or cancel if the notification never arrives. ## Session cancellation [`session/cancel`](/protocol/v2/prompt-lifecycle#cancellation) does not automatically cancel every elicitation scoped to the session. `sessionId` and `toolCallId` identify context, not a cancellation instruction. When cancelling work makes a pending elicitation no longer relevant, the Agent **SHOULD** cancel that individual request using [`$/cancel_request`](/protocol/v2/cancellation). An elicitation can depend on the affected work with or without a `toolCallId`. Clients handle individual cancellation using the existing request-cancellation rules rather than infer it from session scope. Request-scoped elicitations outside the session are unaffected by `session/cancel`. [`session/close`](/protocol/v2/session-setup#closing-active-sessions) is different: before responding, the Agent **MUST** cancel every pending elicitation scoped to that session. Clients **SHOULD** dismiss elicitation UI for a closed session. Clients **SHOULD** dismiss interaction UI they know is no longer relevant. An accepted URL interaction may continue externally after its create request has returned. Cancelling foreground work does not guarantee that an external browser page closes or undo external side effects. A repeated or resume idle snapshot carrying a previous `cancelled` stop reason does not cancel a current interaction. A response or external completion can race with cancellation. After foreground cancellation completes, the Agent **SHOULD NOT** use late responses or external completions to resume the cancelled work. An external URL workflow may still complete independently. Cancellation can finish without waiting for it. ## URL security Agents and Clients implementing URL mode **MUST** follow these requirements: These requirements adapt MCP's [Safe URL Handling](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation#safe-url-handling) rules to ACP. * Agents **MUST NOT** put credentials, personal data, or pre-authenticated access in the URL and **SHOULD** use HTTPS outside development. * Agents **SHOULD NOT** include URLs intended to be clickable in any field of a form-mode request. * Clients **MUST NOT** prefetch the URL or open it without explicit user consent. They **MUST** show the full URL before asking for consent. * Clients **MUST** open the URL in a secure context that prevents the Client or Agent's language model from inspecting the page or user input. * Clients **SHOULD** highlight the domain and warn about suspicious or ambiguous URLs, including Punycode domains. * Clients **SHOULD NOT** render a URL as clickable in any elicitation field except the `url` field of a URL-mode request, subject to the restrictions above. * When the Agent has an authenticated user, it **MUST** verify that the user who started the elicitation is the same user who completes the external interaction. Without one, such as during `auth/login`, the Agent **MUST** tie completion to the elicitation it issued and the connection it issued it on, for example with an unguessable single-use `state` value in the URL, and **MUST NOT** apply the result to a different connection. See the [schema reference](/protocol/v2/schema#elicitation%2Fcreate) for the complete request and response types. # Errors Source: https://agentclientprotocol.com/protocol/v2/error Error handling in the Agent Client Protocol Failed requests return a [JSON-RPC 2.0 error object](https://www.jsonrpc.org/specification#error_object): * `code`: an integer identifying the kind of error * `message`: a short human-readable description * `data` (optional): additional information whose shape depends on the code ```json theme={null} { "jsonrpc": "2.0", "id": 3, "error": { "code": -32002, "message": "Resource not found", "data": { "sessionId": "sess_abc123def456" } } } ``` ## Error codes | Code | Message | Meaning | | - | - | - | | `-32700` | Parse error | The message is not valid JSON. | | `-32600` | Invalid request | The message is not a valid request object, a request other than `initialize` arrived before initialization, or `initialize` was repeated after another request. | | `-32601` | Method not found | The receiver does not implement the method. | | `-32602` | Invalid params | The parameters are malformed or contain a value the receiver does not support. | | `-32603` | Internal error | The receiver failed unexpectedly. | | `-32800` | Request cancelled | The request was [cancelled](/protocol/v2/cancellation). | | `-32000` | Authentication required | The request requires [authentication](/protocol/v2/authentication) first, or an `auth/login` attempt failed. | | `-32002` | Resource not found | A referenced resource, such as a session, does not exist. | | `-32022` | Unsupported protocol version | The Agent supports no [protocol version](/protocol/v2/initialization#version-negotiation) at or below the requested one. | Receivers **MUST** treat an unrecognized code as a generic failure. Implementation-specific errors **SHOULD** use codes outside `-32768` to `-32000` and `-32899` to `-32800`, which are reserved for JSON-RPC and ACP. ACP takes `-32800` (Request cancelled) from the second range, which LSP also reserves. ## Common cases ### Unknown methods A receiver that does not implement a method, or receives a capability-gated method it did not advertise, **MUST** respond with `-32601`. This applies to custom and standard methods alike. Notifications can't be answered, so receivers **SHOULD** ignore unknown ones. ### Invalid parameters Malformed parameters and unsupported values get `-32602`. For example, an invalid `session/list` cursor, or in `session/set_config_option` an unknown `configId`, an invalid value, or a value `type` that is unsupported or doesn't match the option. A `systemPrompt` the Agent cannot apply gets an error, and `-32602` is recommended. See [System prompt](/protocol/v2/session-setup#system-prompt). ### Unknown sessions If a session-scoped request names a session that does not exist or is not active on the connection, the Agent **MUST** respond with `-32002` and set `data.sessionId` to the requested ID. A session is active once it is created or resumed on the connection, until it is closed or the connection ends. See [Session Lifecycle](/protocol/v2/session-setup#session-lifecycle). This applies to `session/prompt` and `session/set_config_option`, and to `session/resume` of a session that does not exist or was deleted. `session/close` and `session/delete` are exceptions: Agents **SHOULD** still return success when closing a session that does not exist or is not active, or deleting one that does not exist. Clients **SHOULD** treat a `-32002` response to either as success. See [Closing Active Sessions](/protocol/v2/session-setup#closing-active-sessions) and [Deleting Sessions](/protocol/v2/session-delete). ### Requests before initialization Agents **MUST** reject any request other than `initialize` that arrives before initialization completes with `-32600`, and ignore notifications. They also reject an `initialize` repeated after another request with `-32600`. See [Before Initialization Completes](/protocol/v2/initialization#before-initialization-completes). # Extensibility Source: https://agentclientprotocol.com/protocol/v2/extensibility Adding custom data and capabilities Implementations can add custom behavior without breaking peers that don't know about it. They can attach custom data in `_meta` fields, define custom methods and enum values whose names start with `_`, and advertise custom capabilities during initialization. ## Experimental features and negotiation **Stability**, **support**, and **forward compatibility** are separate: * Stability describes whether a feature is part of the baseline schema or is an experimental addition that may change or be removed. * Support describes whether a peer implements the feature's behavior, as advertised by its capability or another explicitly documented negotiation mechanism. * Forward compatibility describes whether a receiver can safely accept a field or variant without implementing its behavior. Negotiating `protocolVersion: 2` selects the v2 protocol, not all experimental features in `schema/v2/schema.unstable.json`. There is no connection-wide "unstable schema" flag. Implementations **MUST NOT** infer peer support from their own schema selection, generated types, or local feature flags. ### When a capability is required Each feature defines its negotiation requirements, whether stable or experimental: * **Optional operations requiring peer participation** need an advertised capability or another explicitly documented negotiation mechanism. Callers **MUST** follow that feature's requirements. An omitted or `null` support marker means unsupported. * **Informational additions with a safe fallback** may be sent without a capability when the feature explicitly permits it. A receiver may ignore or generically display them. Senders **MUST NOT** depend on feature-specific presentation, acknowledgement, or action. * **Local feature flags** control implementation and rollout. They neither advertise peer support nor replace a required capability. For example: | Feature | Negotiation and receiver behavior | | - | - | | [Session deletion](/protocol/v2/session-delete) | The Agent advertises `session.delete`. Clients must not call `session/delete` without it. | | [Elicitation](/protocol/v2/elicitation#checking-support) | The Client advertises each supported mode under `elicitation`. Agents must not request other modes. | | [Notices](/protocol/v2/prompt-lifecycle#session-notices) and [compaction](/protocol/v2/prompt-lifecycle#session-compaction) | No Client capability is required in v2. Clients without feature-specific handling may preserve, ignore, or generically display the updates. | These rules are specific to v2. Features with capability gates in v1 retain those gates on v1 connections. Experimental schema revisions may disagree about a feature's shape or semantics. A capability advertises the behavior defined for that feature, not compatibility with every revision of the unstable schema. Experiments that require matching revisions should define feature-specific revision negotiation rather than rely on a global unstable-schema flag. ### Validation Receivers **MUST** accept unknown fields and genuinely unknown discriminator values where their schema permits them. Closed discriminators remain closed. For open tagged unions, receivers validate the fallback's required envelope fields, then [preserve unknown payloads or use safe generic handling](#enum-and-tagged-union-variants). Accepting an unknown variant does not advertise support for its behavior. A malformed value for a discriminator recognized by the receiver **MUST NOT** fall through to the unknown-variant fallback. Validate recognized variants against their defined shapes. Forward compatibility does not make operational request parameters permissive. If a request can't be fulfilled without understanding an unknown variant, the receiver **MUST** reject it with `-32602` (Invalid params). Otherwise, it degrades gracefully as the field documents, for example by ignoring the variant or displaying it generically. Payload validation and capability checks are separate. A schema-valid request is not necessarily supported or permitted on the connection. ## The `_meta` field Protocol object types that define a `_meta` field can use it to attach custom information. This includes requests, responses, notifications, and nested object types such as content blocks, tool calls, plan entries, and capability objects. Primitive types and object types that do not define `_meta` cannot carry it. `_meta` is an object with string keys (`{ [key: string]: unknown }`). Receivers treat any other value as omitted. Except for [metadata patches](#metadata-patches), omitted and `null` are equivalent and mean no metadata. Metadata on a chunk is scoped to that chunk and does not patch stored metadata. ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "session/prompt", "params": { "sessionId": "sess_abc123def456", "prompt": [ { "type": "text", "text": "Hello, world!" } ], "_meta": { "traceparent": "00-80e1afed08e019fc1110464cfa66635c-7a085853722dc6d2-01", "com.example/debugMode": true } } } ``` Clients may propagate fields to the agent for correlation purposes, using a namespaced key such as `com.example/requestId`. The following root-level keys in `_meta` are reserved, as in MCP, for interop with MCP implementations and OpenTelemetry tooling. When present, their values **MUST** use the corresponding W3C format: * `traceparent` and `tracestate`: [W3C Trace Context](https://www.w3.org/TR/trace-context/) * `baggage`: [W3C Baggage](https://www.w3.org/TR/baggage/) Other unprefixed `_meta` keys, and keys whose prefix has `agentclientprotocol` as its second label (such as `io.agentclientprotocol/`), are reserved for ACP. Keys and prefixes that MCP reserves keep their MCP meaning, and Agents preserve them when forwarding MCP content. Extension keys **SHOULD** use a reverse-DNS prefix the implementer controls, as described below. Implementations **MUST NOT** add any custom fields at the root of a type that's part of the specification. All possible names are reserved for future protocol versions. ### Metadata patches Upsert updates carry a top-level `_meta` that the Client stores with the entity they create or update: `tool_call_update` (including the `toolCall` of a permission request's `tool_call` subject), `terminal_update`, `user_message`, `agent_message`, `agent_thought`, `session_info_update`, and `compaction_update`. Clients apply this `_meta` as a patch, one top-level key at a time, using the same rule as the update's other fields: * Omit `_meta` to leave the stored metadata unchanged. * Set `_meta` to `null` to clear all stored metadata. * Send an object to patch the stored metadata: * Keys the object omits keep their stored values, so `_meta: {}` changes nothing. * A key set to `null` is removed. Removing a key that is not stored does nothing. * Any other value replaces that key's stored value whole. Clients **MUST NOT** merge nested objects, and a `null` nested inside the value is ordinary data. For example, if a tool call's stored `_meta` is: ```json theme={null} { "com.example/progress": 0.5, "org.example/review": { "state": "pending" } } ``` and a later update sends: ```json theme={null} { "sessionUpdate": "tool_call_update", "toolCallId": "call_001", "_meta": { "com.example/progress": null, "org.example/review": { "reviewer": "sam" }, "net.example/route": "edge" } } ``` the stored `_meta` becomes: ```json theme={null} { "org.example/review": { "reviewer": "sam" }, "net.example/route": "edge" } ``` A key set to `null` never holds stored data, including on the first update for an entity, so a key cannot store a literal JSON `null`. An extension that needs one can wrap it, for example `{ "value": null }`. Stored metadata with no keys is the same as no metadata. Because each top-level key is replaced whole, the implementation that owns a key, such as an extension using a namespaced key, can set, replace, or remove it without knowing the other keys. This does not resolve conflicts between writers: updates to the same key apply in receive order, and `_meta: null` clears every key. Replay and resynchronization apply these patches exactly as live delivery does and never reset metadata implicitly. An update that replaces another field, such as a message update with `content`, leaves the `_meta` keys it does not mention. To send the current metadata of an entity the Client may already hold, the Agent removes stale keys: it either sets each one to `null` alongside the current keys, or sends `_meta: null` and then the current object in a later update. The second form is not atomic, so the Client may briefly hold no metadata. Send `_meta: null`, not `{}`, when the current metadata is empty. Intermediaries that combine updates **MUST** keep removals and clears. Other `_meta` fields are not patches, including the `_meta` of `plan_update`. Metadata on requests, responses, notification params, chunks, content items, snapshots, and other nested objects describes only the object that carries it, and a key set to `null` there is ordinary data. Do not copy such metadata into a patch unchanged, for example from a `session/list` entry into a `session_info_update`: its `null` key values would become removals. Put data about a single notification, rather than the entity, in the `session/update` notification's `params._meta`. ## Unknown object fields Receivers **MUST** ignore unrecognized properties of protocol-defined objects, including properties nested within capability objects. An otherwise valid message **MUST NOT** be rejected solely because it contains unrecognized properties. Ignoring a property means not assigning protocol behavior to it. It does not imply support for the feature it describes. This rule does not relax validation of known properties or change their documented handling of malformed values. Unknown enum values, discriminator values, and method names follow their own rules. They are not unknown object fields. A malformed value for a known discriminator **MUST NOT** be treated as an unknown variant. Ignoring an unknown property means not interpreting it. Implementations are not required to remove it from the message. ## Extension methods The protocol reserves any method name starting with an underscore (`_`) for custom extensions, so custom methods can't conflict with methods added in future protocol versions. Names starting with `$/` are reserved for protocol-level messages such as [`$/cancel_request`](/protocol/v2/cancellation), and all other names are reserved for ACP. Extension methods follow standard [JSON-RPC 2.0](https://www.jsonrpc.org/specification) semantics: * **[Requests](https://www.jsonrpc.org/specification#request_object)** - Include an `id` field and expect a response * **[Notifications](https://www.jsonrpc.org/specification#notification)** - Omit the `id` field and are one-way ### Custom requests In addition to the requests specified by the protocol, implementations **MAY** expose and call custom JSON-RPC requests as long as their name starts with an underscore (`_`). ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "_com.example/workspace/buffers", "params": { "language": "rust" } } ``` Upon receiving a custom request, implementations **MUST** respond accordingly with the provided `id`: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "buffers": [ { "id": 0, "path": "/home/user/project/src/main.rs" }, { "id": 1, "path": "/home/user/project/src/editor.rs" } ] } } ``` If the receiving end doesn't recognize the custom method name, it **MUST** respond with the standard "Method not found" error: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "error": { "code": -32601, "message": "Method not found" } } ``` To avoid such cases, extensions **SHOULD** advertise their [custom capabilities](#advertising-custom-capabilities) so that callers can check their availability first and adapt their behavior or interface accordingly. ### Custom notifications Custom notifications are regular JSON-RPC notifications that start with an underscore (`_`). Like all notifications, they omit the `id` field: ```json theme={null} { "jsonrpc": "2.0", "method": "_com.example/file_opened", "params": { "path": "/home/user/project/src/editor.rs" } } ``` Unlike with custom requests, implementations **SHOULD** ignore any notification they don't recognize, whether it is custom or from a later ACP version. ## Enum and tagged-union variants ACP also reserves `_`-prefixed values for implementation-specific extensions in enum-like fields and tagged unions that define a custom or future fallback. * Values beginning with `_` are reserved for implementation-specific extensions. * Unknown values that do not begin with `_` are reserved for future ACP variants. * Extensions **MUST NOT** define custom non-underscore values. * Implementations **MUST NOT** treat unknown non-underscore values as custom extensions. This rule applies only where the schema defines a fallback path. Most enums and tagged unions have one. The following are closed, and receivers reject values outside them: * `ElicitationSchema.type`, which is always `object`. * Embedded resource contents, which are text or blob contents, as in MCP. * Select config option `options`, which are a flat list of values or a list of groups. * The elicitation scope, which is either `sessionId` or `requestId`. When storing, replaying, proxying, or forwarding data, implementations **SHOULD** preserve unknown values and any raw tagged-union payloads. When displaying an unknown value, implementations **SHOULD** fall back to generic UI behavior that matches the field's purpose. ## Advertising custom capabilities Implementations **SHOULD** advertise support for extensions and their methods using namespaced entries in capability objects' `_meta` fields: * Use `capabilities._meta` for standalone extensions or extensions that apply across capability groups. * Use a nested capability object's `_meta`, where that object defines one, for extensions scoped to that capability. For example, an extension to session prompting belongs in `capabilities.session.prompt._meta`. * Creating a standard capability object to carry `_meta` still advertises the standard support associated with that object. An Agent **MUST NOT** send `capabilities.session: { "_meta": ... }` unless it supports all seven baseline session methods. To avoid collisions with other extensions, follow [MCP's naming convention](https://modelcontextprotocol.io/specification/2026-07-28/basic/index): prefix extension names with dot-separated labels in reverse-DNS order of a domain you control, followed by `/`. For example, use `com.example/` for `_meta` keys, including capability entries, and `_com.example/` for custom methods and custom enum values. Custom capability names **MUST NOT** be added as properties directly on either the root capability object or nested protocol-defined capability objects. Both sides advertise an extension under the same namespaced key, each using the nested capability object's `_meta` where its side has one and `capabilities._meta` otherwise. An extension's documentation states where each side advertises it. For example, an Agent can advertise an independent workspace extension without advertising session support: ```json theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 2, "capabilities": { "_meta": { "com.example/workspace": true, "com.example/fileNotifications": true } }, "info": { "name": "my-agent", "title": "My Agent", "version": "1.0.0" } } } ``` Implementations can then negotiate custom features during initialization without breaking standard Clients and Agents. # Initialization Source: https://agentclientprotocol.com/protocol/v2/initialization How all Agent Client Protocol connections begin The Initialization phase allows [Clients](/protocol/v2/overview#client) and [Agents](/protocol/v2/overview#agent) to negotiate protocol versions, capabilities, and authentication methods. ```mermaid theme={null} sequenceDiagram participant Client participant Agent Note over Client, Agent: Connection established Client->>Agent: initialize Note right of Agent: Negotiate protocol
version & capabilities Agent-->>Client: initialize response Note over Client,Agent: Ready for session setup ``` Before a Session can be created, Clients **MUST** initialize the connection by calling the `initialize` method with: * The latest [protocol version](#protocol-version) supported * The [capabilities](#client-capabilities) supported * The [implementation information](#implementation-information) for the Client ```json theme={null} { "jsonrpc": "2.0", "id": 0, "method": "initialize", "params": { "protocolVersion": 2, "capabilities": { "auth": { "terminal": {} } }, "info": { "name": "my-client", "title": "My Client", "version": "1.0.0" } } } ``` The Agent **MUST** respond with the chosen [protocol version](#protocol-version), the [capabilities](#agent-capabilities) it supports, and its [implementation information](#implementation-information): ```json theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 2, "capabilities": { "session": { "prompt": { "image": {}, "audio": {}, "embeddedContext": {} }, "mcp": { "stdio": {}, "http": {} } } }, "info": { "name": "my-agent", "title": "My Agent", "version": "1.0.0" }, "authMethods": [] } } ``` `authMethods` is optional. Returning a non-empty list means the Agent **MUST** implement both `auth/login` and `auth/logout`. If `authMethods` is omitted or empty, Clients **MUST NOT** call either method. `capabilities.auth` is separate from `authMethods`. It advertises authentication-related extensions and does not change the availability rules for `auth/login` or `auth/logout`. ## Before initialization completes Initialization completes when the Agent responds successfully to `initialize`. Until then: * Clients **MUST NOT** send requests other than `initialize`. Agents reject them with `-32600` and ignore notifications. See [Requests Before Initialization](/protocol/v2/error#requests-before-initialization). * Agents **MUST NOT** send requests or notifications. * If `initialize` fails, the connection is still uninitialized, and the Client **MAY** send `initialize` again, for example after correcting invalid params. After initialization completes, the Client can repeat `initialize` only as described in [Repeating Initialization](#repeating-initialization). ## Protocol version The protocol versions that appear in the `initialize` requests and responses are a single integer that identifies a **MAJOR** protocol version. This version is only incremented when breaking changes are introduced. Clients and Agents **MUST** agree on a protocol version and act according to its specification. See [Capabilities](#capabilities) to learn how non-breaking features are introduced. ### Version negotiation The `initialize` request **MUST** include the latest protocol version the Client supports. The Agent **MUST** read `protocolVersion` before validating any other parameter. Missing, non-integer, or out-of-range values are malformed parameters and **MUST** receive `-32602` (`Invalid params`). The Agent **MUST** select the highest protocol version it supports that is less than or equal to the requested version. If it supports the requested version, this selects that version. A successful `initialize` response **MUST NOT** select a version higher than the requested version and **MUST** use the selected version's initialization response shape. If no supported version is less than or equal to the requested version, the Agent **MUST** reject `initialize` with error code `-32022` (`Unsupported protocol version`). The error's `data` **MUST** be an object containing the required, non-null fields `requested` (the requested protocol version) and `supported` (an array of the protocol versions the Agent supports). An empty `supported` array means the endpoint has no protocol implementations configured. ```json theme={null} { "jsonrpc": "2.0", "id": 0, "error": { "code": -32022, "message": "Unsupported protocol version", "data": { "requested": 1, "supported": [2] } } } ``` A version-mismatch error does not initialize the connection. The Agent **MUST NOT** begin version-specific operations on that connection, and the Client **SHOULD** close it and inform the user. The Agent validates the remaining parameters against the selected version. If the requested version is newer than the selected one, the request was written for a version the Agent doesn't know, so the Agent **MUST** ignore parameters it can't parse under the selected version instead of rejecting the request. The Client **MUST** check that it supports the version in a successful response. Advertising a latest version does not imply support for every earlier version. If the Client does not support the selected version, it **SHOULD** close the connection and inform the user. #### Repeating initialization When the Agent selects a lower version than requested, it may have ignored parts of the Client's request, such as capabilities. The Client **MAY** then send `initialize` again with the selected version and that version's parameters. The Client **MAY** repeat `initialize` any number of times before its first other request, waiting for each response before sending the next. The Agent handles each one like the first and treats the latest successful `initialize` as authoritative. A repeat that fails leaves the previous successful initialization in effect. `initialize` **MUST NOT** be repeated after any other request. Agents that implement only v1 may not accept a repeated `initialize`. To change its parameters with such an Agent, the Client opens a new connection. ## Capabilities Capabilities describe features supported by the Client and the Agent. All capabilities included in the `initialize` request or response are **OPTIONAL**. Clients and Agents **SHOULD** support all possible combinations of their peer's capabilities. The introduction of new capabilities is not considered a breaking change. Therefore, Clients and Agents **MUST** treat all capabilities omitted in the `initialize` request or response as **UNSUPPORTED**. A capability may advertise a group of methods, such as the `session/*` methods, or a nested feature that only applies when its parent capability is supported. Capabilities may specify the availability of protocol methods, notifications, or a subset of their parameters. They may also signal behaviors of the Agent or Client implementation. Receivers **MUST** ignore unknown capability fields at every nesting level, as described in [Unknown Object Fields](/protocol/v2/extensibility#unknown-object-fields). Unknown fields do not advertise support for any capability the receiver understands. Implementations can also [advertise custom capabilities](/protocol/v2/extensibility#advertising-custom-capabilities) using the `_meta` field to indicate support for protocol extensions. Experimental features follow their own documented negotiation requirements, not a connection-wide unstable-schema flag. See [Experimental Features and Negotiation](/protocol/v2/extensibility#experimental-features-and-negotiation) for the distinction between capability-gated operations and capability-free informational additions. ### Client capabilities Clients **MAY** include defined capability fields in `capabilities`. Omitted fields mean unsupported. Extension-specific capabilities belong in `_meta`. #### Terminal authentication **auth.terminal** `TerminalAuthCapabilities Object` The Client can reproduce the configured Agent invocation in an interactive terminal. Omitted or `null` means unsupported. Supplying `{}` means the Agent may advertise `type: "terminal"` authentication methods. > [card] > > Learn more about Terminal Authentication > > [Open](/protocol/v2/authentication) #### Elicitation **elicitation** `ElicitationCapabilities Object` The Client advertises its supported `elicitation/create` modes. Omitted or `null` means no modes are advertised. A present object advertises each mode only through its corresponding non-null `form` or `url` field. Empty and all-null objects are valid but advertise no supported modes. Unlike MCP, ACP does not treat `{}` as form support. > [card] > > Learn more about Elicitation > > [Open](/protocol/v2/elicitation) ### Agent capabilities The Agent **SHOULD** specify whether it supports the following capabilities: **session** `SessionCapabilities Object` The Agent supports the `session/*` methods. Omitted or `null` means the Agent does not support session methods. Supplying `{}` means the Agent supports the baseline session methods: `session/new`, `session/list`, `session/resume`, `session/close`, `session/prompt`, `session/cancel`, and `session/update`. **auth** `AgentAuthCapabilities Object` Authentication-related extensions supported by the Agent. This field is orthogonal to `authMethods` and does not advertise the availability of `auth/login` or `auth/logout`. #### Session capabilities Supplying `session: {}` means the Agent supports `session/new`, `session/list`, `session/resume`, `session/close`, `session/prompt`, `session/cancel`, and `session/update`. Optionally, Agents **MAY** support prompt extensions, MCP server transports, and additional session methods such as `session/delete` by specifying nested capabilities. Agents that advertise [config options](/protocol/v2/session-config-options#setting-a-config-option) **MUST** also support `session/set_config_option`. **prompt** `PromptCapabilities Object` Object indicating the different types of [content](/protocol/v2/content) that may be included in `session/prompt` requests. Omitted or `null` means the Agent does not advertise any prompt extensions beyond the baseline text and resource-link content required by `session/prompt`. **mcp** `McpCapabilities Object` Object indicating the MCP server transports that may be included in session lifecycle requests. Omitted or `null` both mean the Agent does not advertise MCP server transport support for sessions. **delete** `SessionDeleteCapabilities Object` The [`session/delete`](/protocol/v2/session-delete) method is available. Omitted or `null` both mean the Agent does not advertise support. Supplying an empty object means the Agent supports deleting sessions from `session/list`. **additionalDirectories** `SessionAdditionalDirectoriesCapabilities Object` The Agent supports `additionalDirectories` on supported session lifecycle requests. Omitted or `null` both mean the Agent does not advertise support. Supplying `{}` means the Agent supports additional workspace roots. **systemPrompt** `SessionSystemPromptCapabilities Object` The Agent supports [`systemPrompt`](/protocol/v2/session-setup#system-prompt) on session lifecycle requests. Omitted or `null` both mean the Agent does not advertise support. Supplying `{}` means the Agent supports `append` mode. Supplying `{ "mode": { "override": {} } }` also advertises `override` mode. #### Session prompt capabilities As a baseline, Agents that advertise `session` **MUST** support `text` and `resource_link` content blocks in `session/prompt` requests. Optionally, they **MAY** support richer types of [content](/protocol/v2/content) by specifying the following capabilities: **image** `PromptImageCapabilities Object` The prompt may include `image` content blocks. Omitted or `null` means the Agent does not advertise support. Supplying `{}` means the Agent supports image content in prompts. **audio** `PromptAudioCapabilities Object` The prompt may include `audio` content blocks. Omitted or `null` means the Agent does not advertise support. Supplying `{}` means the Agent supports audio content in prompts. **embeddedContext** `PromptEmbeddedContextCapabilities Object` The prompt may include `resource` content blocks. Omitted or `null` means the Agent does not advertise support. Supplying `{}` means the Agent supports embedded context in prompts. #### Session MCP capabilities **stdio** `McpStdioCapabilities Object` The Agent supports connecting to MCP servers over stdio. Omitted or `null` means the Agent does not advertise support. Supplying `{}` means the Agent supports stdio MCP server transports. **http** `McpHttpCapabilities Object` The Agent supports connecting to MCP servers over HTTP. Omitted or `null` means the Agent does not advertise support. Supplying `{}` means the Agent supports HTTP MCP server transports. > [card] > > Learn more about Authentication > > [Open](/protocol/v2/authentication) ## Implementation information Both Clients and Agents **MUST** provide information about their implementation in the `info` field. It takes the following three fields: **name** `string` *required* Intended for programmatic or logical use, but can be used as a display name fallback if title isn't present. **title** `string` Intended for UI and end-user contexts and optimized to be human-readable and easily understood. Optional. Omitted and `null` are equivalent. If not provided, the name **SHOULD** be used for display. **version** `string` *required* Version of the implementation. Can be displayed to the user or used for debugging or metrics purposes. *** Once the connection is initialized, you're ready to [create a session](/protocol/v2/session-setup) and begin the conversation with the Agent. # Migrating from v1 Source: https://agentclientprotocol.com/protocol/v2/migration A complete guide to ACP v2 for implementers familiar with v1: breaking changes, new features, and step-by-step migration ACP v2 is a consolidation release. It redesigns the prompt lifecycle, unifies streaming and non-streaming updates, makes the schema forward-compatible by default, and removes Client APIs that few implementations used. Migrating does not mean dropping v1. v1-only Agents and Clients will remain common for some time, so implementers should support both versions side by side: negotiate the version per connection, keep your v1 support working, and add v2 behind feature flags until it stabilizes. See [Supporting v1 and v2 side by side](#supporting-v1-and-v2-side-by-side) for how to structure this. If you only remember five things, remember these: 1. **The `session/prompt` response no longer ends the turn.** It acknowledges acceptance. Foreground progress and completion arrive as `state_update` notifications, and the stop reason moved there too, including failures after acceptance. 2. **Updates are upserts.** Messages and tool calls are patched by ID with uniform semantics: omitted field = unchanged, `null` = cleared, value = replaced, chunks append. Plans are replaced whole by `planId`. 3. **The Client file system, terminal execution, and session modes APIs are gone.** Agent-owned terminal output is a separate, display-only v2 feature. Use client-provided MCP servers when the Agent needs Client-side tools. 4. **Capabilities were reorganized.** One `capabilities` + required `info` field on both sides, session-scoped groups nested under `session`, object support markers instead of booleans, and a required baseline of session methods. 5. **Everything is extensible now.** Almost all enums and tagged unions accept unknown values. `_`-prefixed values are yours, the rest are reserved for future ACP versions. ## Scope: stable v2 and draft features This guide describes the stable v2 baseline (`schema/v2/schema.json`). v2 as a whole is still labeled draft, so gate **v2 support behind explicit version negotiation and feature flags until it stabilizes.** The unstable schema (`schema/v2/schema.unstable.json`) layers experimental features on top of that baseline. Negotiating `protocolVersion: 2` does **not** imply support for them. Follow each feature's documented negotiation requirements: optional operations requiring peer participation use explicit capabilities or another documented mechanism, while informational additions with safe forward-compatible handling may be sent without a capability when the feature permits it. Local feature flags control rollout, not peer support. See [Experimental Features and Negotiation](/protocol/v2/extensibility#experimental-features-and-negotiation). ## Version negotiation The Client sends the latest protocol version it supports in `initialize`. An Agent implementing v2 selects the highest supported version at or below the requested version, or rejects initialization with `-32022` (`Unsupported protocol version`) and structured `requested` and `supported` data if none exists. To use v2, send `"protocolVersion": 2`. A legacy v1-only Agent can return `"protocolVersion": 1` to a Client requesting v2. The Client continues only if it supports v1, otherwise it disconnects. A v1 Agent reads a v2 request without the v1 `clientCapabilities` and `clientInfo`, so file system, terminal, and terminal authentication support are lost on that connection. A Client that needs them reconnects with a v1 `initialize`. Conversely, a v1 Client talking to a v2-only Agent receives an ordinary initialization error. It does not need to understand the new error code to report that initialization failed. Treat v2 support as additive. Keep serving `protocolVersion: 1` peers when you add v2: an Agent that drops v1 cuts itself off from existing Clients, and a Client that drops v1 loses access to existing Agents. Each side picks its v1 or v2 handlers per connection based on the negotiated version. v2 keeps the underlying JSON-RPC framing, except that request IDs can no longer be `null` and JSON-RPC batches are not used (see [Transports](/protocol/v2/transports#no-batches)), so a single connection always speaks exactly one negotiated version after `initialize`. ## At a glance ### Method changes | v1 method | v2 | | - | - | | `initialize` | Unchanged name. Params and result restructured | | `authenticate` | Renamed to `auth/login` for protocol-driven authentication methods | | `logout` (gated by `agentCapabilities.auth.logout`) | Renamed to `auth/logout`. Required when `authMethods` is non-empty. No logout capability marker | | `session/new` | `mcpServers` now optional. Response no longer includes `modes` | | `session/load` | **Removed**. Use `session/resume` with `"replayFrom": { "type": "start" }` | | `session/resume` | Gains optional `replayFrom`. Required (no capability marker) | | `session/list` | Required. No capability | | `session/close` | Required. No capability. Cancels ongoing work like `session/cancel`: the final updates and idle `cancelled` state come before the close response, and prompts not yet inserted get `-32800` | | `session/delete` | Still optional via `session.delete`. Deleting a session active on any connection now cancels its work as if closed, and later requests for it, including `session/resume`, fail with `-32002` | | `session/prompt` | Unchanged shape. **Response semantics redesigned** (see [Prompt lifecycle](#the-new-prompt-lifecycle)) | | `session/cancel` | Unchanged name. Completion now reported via `state_update` instead of the prompt response. Prompts not yet inserted get `-32800` | | `session/set_mode` | **Removed**. Use `session/set_config_option` | | `session/set_config_option` | Required when the Agent advertises config options. No capability. Params use `configId` and a required `type` discriminator (see [Config options](#session-modes-become-config-options)) | | `session/request_permission` | Unchanged name. Params restructured (required `title`, optional `subject`) | | `session/update` | Unchanged name. Update variants changed (see below) | | `elicitation/create` | Unchanged shape. Exactly one of `sessionId` or `requestId` is required. Session-scoped requests follow the foreground-state contract (`requires_action`). An unknown action is handled as `cancel` | | `elicitation/complete` | Unchanged | | `fs/read_text_file`, `fs/write_text_file` | **Removed** | | `terminal/create`, `terminal/output`, `terminal/release`, `terminal/wait_for_exit`, `terminal/kill` | **Removed** | | `$/cancel_request` | Unchanged, except for an inserted `session/prompt` (see Cancellation) | ### `session/update` variant changes | v1 `sessionUpdate` | v2 | | - | - | | `user_message_chunk` | Kept. `messageId` now required | | `agent_message_chunk` | Kept. `messageId` now required | | `agent_thought_chunk` | Kept. `messageId` now required | | - | **New:** `user_message`, `agent_message`, `agent_thought` whole-message upserts | | - | **New:** foreground `state_update` (`running`, `idle`, `requires_action`) with stop reasons | | `tool_call` | **Removed**. The first `tool_call_update` for a `toolCallId` creates the tool call | | `tool_call_update` | Kept. Now an explicit upsert with omit/`null`/value patch semantics | | - | **New:** `tool_call_content_chunk` for streaming individual content items | | - | **New:** `terminal_update` for Agent-owned display terminal state and replay | | - | **New:** `terminal_output_chunk` for appending display terminal bytes | | `plan` | Replaced by `plan_update` with a `planId` and a `type` discriminator | | `current_mode_update` | **Removed**. Modes are config options. Use `config_option_update` | | `available_commands_update` | Kept. Commands and their `input` now carry a required `type` discriminator | | `config_option_update` | Kept. Options use `configId` instead of `id` and groups use `groupId` instead of `group` | | `session_info_update` | Kept. Top-level `_meta` is now a key-level [patch](/protocol/v2/extensibility#metadata-patches) | | `usage_update` | Kept. `cost` is a patch: omitted leaves it unchanged, `null` clears it | | `notice` | Kept. No Client capability required | | `compaction_update`, `compaction_summary_chunk` | Kept. No Client capability required. Top-level `_meta` on `compaction_update` is a key-level [patch](/protocol/v2/extensibility#metadata-patches) | ## Initialization ### Role-agnostic `info` and `capabilities` v1 used role-specific field names: the Client sent `clientCapabilities` and optional `clientInfo`, and the Agent returned `agentCapabilities` and optional `agentInfo`. v2 uses the same two field names in both directions (`capabilities` and `info`), and `info` is now **required** on both sides. ```json v1 request theme={null} { "jsonrpc": "2.0", "id": 0, "method": "initialize", "params": { "protocolVersion": 1, "clientCapabilities": { "fs": { "readTextFile": true, "writeTextFile": true }, "terminal": true }, "clientInfo": { "name": "my-client", "version": "1.0.0" } } } ``` ```json v2 request theme={null} { "jsonrpc": "2.0", "id": 0, "method": "initialize", "params": { "protocolVersion": 2, "info": { "name": "my-client", "title": "My Client", "version": "1.0.0" }, "capabilities": {} } } ``` ```json v1 response theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "loadSession": true, "promptCapabilities": { "image": true, "embeddedContext": true }, "mcpCapabilities": { "http": true, "sse": false }, "sessionCapabilities": { "list": {}, "resume": {}, "close": {} } }, "authMethods": [], "agentInfo": { "name": "my-agent", "version": "0.3.0" } } } ``` ```json v2 response theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 2, "info": { "name": "my-agent", "title": "My Agent", "version": "0.3.0" }, "capabilities": { "session": { "prompt": { "image": {}, "embeddedContext": {} }, "mcp": { "stdio": {}, "http": {} }, "delete": {}, "additionalDirectories": {} } }, "authMethods": [] } } ``` Both responses above have an empty `authMethods` array. In v2, omitting `authMethods` has the same availability meaning: the Agent does not advertise `auth/login` or `auth/logout`, and Clients **MUST NOT** call `auth/login` or `auth/logout`. ### Support markers are objects, not booleans In v1, capability support was a mix of booleans (`"image": true`) and objects (`"list": {}`). In v2, every support marker is an object: supplying `{}` (or an object with fields) means supported, and omitting the key or supplying `null` means unsupported. This means checks like `promptCapabilities.image === true` become presence checks: `capabilities.session.prompt.image != null`. The object shape leaves room for each capability to grow fields or extend with `_meta` without another breaking change. ### Capability reorganization * All session-scoped capability groups now live under `capabilities.session`. What was `agentCapabilities.promptCapabilities` is now `capabilities.session.prompt`, and `agentCapabilities.mcpCapabilities` is now `capabilities.session.mcp`. * `capabilities.session` itself is **optional**, so agents that don't do session-based prompting (for example, agents that only serve extension methods) can omit it entirely. Currently there isn't protocol support for this, but several experiments are in flight and we are making sure non-session components can be expressed via capabilities. * `loadSession` is gone along with `session/load` (see [Session setup](#session-setup-and-lifecycle)). * The individual `list`, `resume`, and `close` markers are gone: advertising `capabilities.session` at all now **requires** supporting the baseline methods `session/new`, `session/list`, `session/resume`, `session/close`, `session/prompt`, `session/cancel`, and `session/update`. Optional extras such as `session.delete`, `session.additionalDirectories`, `session.prompt`, and `session.mcp` keep their own markers. * The v1 Client capabilities `fs` and `terminal` are removed entirely (see [Client file system and terminal execution](#client-file-system-and-terminal-execution-removed)). Stable v2 defines Client `auth` and `elicitation` capability groups. Agent-owned terminal display is baseline behavior, not a Client execution capability. ### Complete v1 → v2 capability mapping The tables below cover the capability fields in the stable and draft schemas. Paths in the first column are relative to v1 `agentCapabilities` or `clientCapabilities`. Paths in the second are relative to v2 `capabilities`. A **Draft only** row does not become available merely by negotiating v2. Convert a boolean support marker from `true` to `{}` and from `false` to an omitted key or `null` only where the table defines a corresponding v2 marker. Object support markers remain objects. Do not copy removed v1 fields into v2 capabilities or move them into `_meta` as though they were standard v2 capabilities. A removed marker may mean the feature is now baseline, not that the feature was removed. #### Agent capability fields | v1 Agent field | v2 Agent field or behavior | | - | - | | Baseline session support (implicit in v1) | Advertise `session: {}` only when all seven v2 baseline session methods are implemented. | | `loadSession` | Removed with `session/load`. Migrate restoration to `session/resume`. | | `promptCapabilities.image` | `session.prompt.image`. Boolean → object marker. | | `promptCapabilities.audio` | `session.prompt.audio`. Boolean → object marker. | | `promptCapabilities.embeddedContext` | `session.prompt.embeddedContext`. Boolean → object marker. | | MCP stdio support (implicit in v1) | Explicit `session.mcp.stdio: {}` marker. Advertise only if supported. | | `mcpCapabilities.http` | `session.mcp.http`. Boolean → object marker. | | `mcpCapabilities.sse` | Removed with the legacy SSE transport. Use HTTP when supported. | | `mcpCapabilities.acp` | **Draft only.** `session.mcp.acp`. Boolean → object marker. | | `sessionCapabilities.list` | Marker removed. `session/list` is required when `session` is advertised. | | `sessionCapabilities.resume` | Marker removed. `session/resume` is required when `session` is advertised. | | `sessionCapabilities.close` | Marker removed. `session/close` is required when `session` is advertised. | | `sessionCapabilities.delete` | `session.delete`. | | `sessionCapabilities.additionalDirectories` | `session.additionalDirectories`. | | `sessionCapabilities.systemPrompt`, including `mode.override` | `session.systemPrompt`, including `mode.override`. Object markers unchanged. | | `sessionCapabilities.fork` | **Draft only.** `session.fork`. | | `auth.logout` | Marker removed. A non-empty `authMethods` list requires both `auth/login` and `auth/logout`. | | `auth` | `auth` remains a group for authentication-related extensions, not method availability. | | `providers` | **Draft only.** `providers`. Object marker unchanged. | #### Client capability fields | v1 Client field | v2 Client field or behavior | | - | - | | `fs.readTextFile`, `fs.writeTextFile` | Removed with Client file-system methods. Expose Client-provided file tools through MCP if needed. | | `terminal` | Removed with Client terminal-control methods. Agent-owned terminal display does not require a Client capability. | | `auth.terminal` | `auth.terminal`. Boolean → object marker. This is distinct from the removed execution `terminal` capability. | | `elicitation.form`, `elicitation.url` | `elicitation.form`, `elicitation.url`. Object markers unchanged. An empty `elicitation` object advertises no modes. | | `session.configOptions.boolean` | Marker removed. v2 supports boolean config options without Client capability negotiation. | | `session.notices` | Marker removed. v2 notices require no Client capability and may be ignored. | | `session.compaction` | Marker removed. v2 compaction updates require no Client capability. | | `session` | Group removed. Its standard children have the behavior described above. | | `plan` | Marker removed. `plan_update` is stable in v2 without Client capability negotiation. `plan_removed` remains **Draft only**. | | `subagents` | Marker removed. Subagent updates and session-directed messages remain **Draft only** in v2 but require no Client `subagents` marker. | The draft per-child-session `capabilities.cancel` marker in `subagent_update` is unchanged. It is not an initialize capability. For surviving capability objects, move `_meta` with its owning group (for example, Agent `promptCapabilities._meta` → `capabilities.session.prompt._meta`). Root capability metadata moves to `capabilities._meta`. For removed groups or markers, review extension semantics and choose a supported root or nested `_meta` location explicitly. See [Advertising Custom Capabilities](/protocol/v2/extensibility#advertising-custom-capabilities). Receivers **MUST** ignore unknown fields, including nested capability fields, but this does not make v1 field names valid v2 advertisements. See [Unknown Object Fields](/protocol/v2/extensibility#unknown-object-fields). ## Authentication The auth methods are grouped under an `auth/` prefix: * `authenticate` → `auth/login`. The params are unchanged (`methodId` selecting an advertised method whose type defines a protocol-driven login flow). The descriptor's identifier field is renamed from `id` to `methodId` to match, and its `type` discriminator is now required. * `logout` → `auth/logout`. In v1, logout support was opt-in via a capability marker. In v2, returning a non-empty `authMethods` list advertises `auth/login` and `auth/logout`, and the Agent **MUST** implement both `auth/login` and `auth/logout`. If `authMethods` is omitted or empty, Clients **MUST NOT** call either method. There is no logout support marker. `capabilities.auth` remains orthogonal and advertises only authentication-related extensions. ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "auth/login", "params": { "methodId": "agent-login" } } ``` ### Auth methods Each entry in `authMethods` now uses `methodId` instead of `id`, and carries a required `type` discriminator so future auth flows can be introduced without breaking existing implementations: ```json theme={null} { "methodId": "agent-login", "type": "agent", "name": "Agent login", "description": "Sign in using the agent's login flow" } ``` Because this entry makes `authMethods` non-empty, the Agent must support both `auth/login` and `auth/logout`. `type: "agent"` is the method type that uses `auth/login`'s protocol-driven flow. Stable v2 defines two types: `agent` and `terminal`. Custom types **MUST** begin with `_`. Unknown values without a leading `_` are reserved for future ACP versions. ### Terminal auth methods `terminal` methods work as in v1: the Client launches the configured Agent program interactively with the method's `args` and `env`, and never sends `auth/login` for them. Besides the `methodId` rename, two things changed shape: * `env` is an array of `{ "name", "value" }` entries with unique names, instead of an object that maps names to values. * The Client advertises terminal auth support with the support marker `capabilities.auth.terminal: {}` instead of `clientCapabilities.auth.terminal: true` (see [Support markers](#support-markers-are-objects-not-booleans)). ```json v1 theme={null} { "id": "terminal-login", "name": "Log in from the terminal", "type": "terminal", "args": ["--login"], "env": { "ACP_INTERACTIVE_LOGIN": "1" } } ``` ```json v2 theme={null} { "methodId": "terminal-login", "name": "Log in from the terminal", "type": "terminal", "args": ["--login"], "env": [{ "name": "ACP_INTERACTIVE_LOGIN", "value": "1" }] } ``` ## The new prompt lifecycle This is the most significant semantic change in v2. Read this section even if you skim the rest. In short, foreground progress and completion moved from the pending `session/prompt` request into `session/update` notifications, while the response now acknowledges user-message insertion: | Foreground signal | v1 | v2 | | - | - | - | | Prompt inserted | Implicit | `session/prompt` response with `messageId` | | User message in history | Implicit (the request itself) | `user_message` update with agent-owned `messageId` | | Foreground work running | `session/prompt` still pending | `state_update` with `state: "running"` | | Foreground work waiting | Implicit (pending permission request) | `state_update` with `state: "requires_action"` | | Foreground work ended | `session/prompt` response with `stopReason` | `state_update` with `state: "idle"` and `stopReason` | | Cancellation confirmed | Prompt response with `stopReason: "cancelled"` | Idle `state_update` with `stopReason: "cancelled"` | | Foreground work failed | `session/prompt` error response | Idle `state_update` with `stopReason: "error"` and `error` | ### v1: the response is the turn In v1, `session/prompt` stayed pending for the entire turn. The Agent streamed `session/update` notifications while working, and the eventual response carried the `stopReason` that ended the turn: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "result": { "stopReason": "end_turn" } } ``` This entangled prompt acceptance with turn completion, which made replay, multi-client sessions, background work, and queued messages awkward to express. ### v2: the response acknowledges insertion In v2, acceptance means insertion of the user message into the ACP conversation. The Agent **MUST** respond to `session/prompt` once the message has been inserted, without waiting for foreground processing to finish. Merely receiving, queueing, or assigning an ID to the input does not justify a successful response: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "result": { "messageId": "msg_user_8f7a1" } } ``` `messageId` is a required, non-null string identifying the inserted user message. The request is unchanged. Clients do not generate this ID. The unstable v1 `usage` field on the prompt response has moved: in the unstable v2 schema, end-turn usage is an optional `usage` on the idle `state_update`. Insertion adds a logical user message with an ID and a position relative to other messages. See [Prompt Accepted](/protocol/v2/prompt-lifecycle#2-prompt-accepted) for adapter examples. Clients may send `session/prompt` while foreground work is active. Unlike many v1 Agents, a v2 Agent **MUST NOT** reject a prompt only because work is active: it inserts it right away or holds it and inserts it later, in the order received. A held prompt's response stays pending until insertion. See [Prompts During Active Work](/protocol/v2/prompt-lifecycle#prompts-during-active-work). Everything else happens through `session/update` notifications: 1. **User message update.** The Agent **MUST** report the inserted message's content and placement, either as a `user_message` update with a full `content` array or as streamed `user_message_chunk` updates. These use the same agent-owned `messageId` as the response. The response and updates describe the same insertion, but updates may arrive before or after the response: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123", "update": { "sessionUpdate": "user_message", "messageId": "msg_user_8f7a1", "content": [{ "type": "text", "text": "Can you analyze this code?" }] } } } ``` 2. **Active state.** When foreground work starts, the Agent **MUST** report `running`, or `requires_action` if it starts blocked on user action. After reporting `requires_action`, it **MUST** report `running` when foreground progress resumes. Active state reporting may precede insertion, for example while a foreground hook runs. It is not acknowledgment of insertion. 3. **Output.** Messages, thoughts, plans, and tool calls stream as before (with the changes described in the following sections). 4. **Completion.** When foreground work ends, the Agent **MUST** report `idle` and **SHOULD** include the stop reason: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123", "update": { "sessionUpdate": "state_update", "state": "idle", "stopReason": "end_turn" } } } ``` Clients reconcile their submitted input with the response's `(sessionId, messageId)`, including when the message update arrived first. They must not match by content or assume that a successful response means the session is idle. SDKs must keep the session's processing and notification handling alive after the prompt RPC completes. An Agent may know it is idle without knowing why the work stopped. Clients **MUST** recognize idle even when the stop reason is omitted, `null`, malformed, or unknown. They cannot infer success or failure without a recognized stop reason. User messages, including [locally handled commands](/protocol/v2/slash-commands#running-commands), must be reported live but need not be retained. If an Agent retains and replays an inserted user message, it must reuse the response's ID. A lost prompt response remains ambiguous. Neither replay omission nor an identical message proves which submission was inserted, and retrying is not automatically safe. Pre-insertion rejection receives a JSON-RPC error response with no user-message updates for that submission. State updates still describe actual foreground work, independently of the request outcome. See [Prompts that are never inserted](/protocol/v2/prompt-lifecycle#prompts-that-are-never-inserted). ### Session states `state_update` is new in v2 and reports foreground work, whether or not a prompt started it, using one of three stable states (extensible like all v2 enums): * `running`: Foreground work is in progress. * `idle`: No foreground work is active. Background activity may continue. Agents **SHOULD** include a `stopReason` when the transition ends foreground work. * `requires_action`: Foreground work as a whole is blocked on user action. Agents **SHOULD** send this when blocked, including on elicitations. Once reported, they **MUST** send `running` when foreground progress resumes, or `idle` if the work ends without resuming. Foreground work is the Agent's active response or workflow in the session, including model processing, tool execution, and waiting for user action needed to continue. Agent-initiated work, such as pursuing an ongoing goal or following up on a completed background task, **MUST** use the same foreground lifecycle as prompt-driven work, with the same guidance for stop reasons. It does not require a prompt request or a synthetic user message. Background activity can continue and emit other `session/update` notifications while the Agent reports `idle`. A detached task's progress, completion, or permission request does not by itself change the foreground state. If the Agent starts a response or workflow to act on a background result, it **MUST** report an active state and report `idle` when that work ends, and **SHOULD** include a stop reason on the idle update. See [Foreground and Background Work](/protocol/v2/prompt-lifecycle#foreground-and-background-work) for contrasting examples. State updates may also carry a [`background`](/protocol/v2/prompt-lifecycle#background-work) list of the work still running, so Clients can tell an idle session with running work from a quiet one. `session/cancel` leaves that work running and no longer cancels permission requests for it. States are aggregate snapshots, not per-request events. Clients **MUST** apply repeats idempotently, without counting additional work, completions, or usage. With concurrent user-action requests, resolving one does not emit `running` unless foreground progress actually resumes. If other foreground work can progress, the state remains `running` while requests are pending. The Agent **MUST** report idle when no foreground activity remains, even between immediately consecutive turns. Completing an individual prompt or command while other foreground activity continues does not require a boundary. Accepted local slash commands **MUST** also report an active state and completion when handled from idle, even without model work. A command with no user-action wait uses `running` → `idle`. New sessions default to idle until a state update reports otherwise. Updates may arrive before the new-session response, which does not overwrite them. Every successful `session/resume` **MUST** be preceded by a current-state snapshot, after any requested replay. Resume does not imply idle, and Agents **MUST NOT** replay historical state updates as current activity. See [Current-State Synchronization](/protocol/v2/session-setup#current-state-synchronization) and the [transition table and lifecycle examples](/protocol/v2/prompt-lifecycle#state-transitions). The v1 stop reasons (`end_turn`, `max_tokens`, `max_turn_requests`, `refusal`, `cancelled`) are unchanged. They just moved from the `session/prompt` response to the idle `state_update` and describe why foreground work stopped. v2 adds the `error` stop reason. v1 reported a failure during the turn as an error response to the pending `session/prompt`. In v2, once the user message is inserted, a failure ends foreground work with an idle `state_update` whose `stopReason` is `error` and whose optional `error` field carries the same JSON-RPC error object. An error response to `session/prompt` now always means the message was not inserted. See [Failures](/protocol/v2/prompt-lifecycle#failures). ### Cancellation `$/cancel_request` and internal request cancellation can no longer answer an inserted `session/prompt` with `-32800`: once the user message is inserted, the Agent responds with its `messageId`, so an error response always means the message was not inserted. Stop the work it started with `session/cancel`. `session/cancel` is unchanged as a notification, but confirmation moved with the rest of the lifecycle: when active foreground work is cancelled, the Agent **MUST** finish sending any pending updates and then send an idle `state_update` with the `cancelled` stop reason. The Agent stops waiting for the cancelled work's pending `session/request_permission` requests. Agents **SHOULD** cancel those requests, and pending elicitations the work no longer needs, individually with `$/cancel_request` rather than cancel every request with that session ID. Clients **SHOULD** accept tool-call updates that arrive after sending `session/cancel`. The Agent **MUST** answer pending prompts it has not inserted, including held prompts, with `-32800`. `session/close` cancels ongoing work the same way, and unlike `session/cancel` it also stops the session's background work. When it cancels active foreground work, the Agent sends the final updates and the idle `cancelled` state before responding to `session/close`, and answers prompts it never inserted with `-32800`. After cancellation completes, Agents **SHOULD** ignore late answers and external completions rather than use them to resume the cancelled work. Responses can race with cancellation before completion. A repeated or resume snapshot carrying an old `cancelled` stop reason does not cancel a current interaction. If no foreground work was active, no additional completion update is required. ### Replay and Agent-initiated work Because foreground progress is now expressed entirely in notifications, the same message flow works for history replay on `session/resume` and agent-initiated work. It also supports future queued-work flows. ## Messages and message IDs ### Message IDs are required Every message chunk and message update in v2 **MUST** carry a `messageId`. In v1, `messageId` was optional on chunks. Message IDs are opaque strings generated by the Agent: the Agent owns session history, so it is the single source of message identity. All chunks of one message share one `messageId`. Chunks for different messages can interleave, and a new `messageId` does not end earlier messages. An entity keeps the timeline position of its first update. See [Entity IDs](/protocol/v2/prompt-lifecycle#entity-ids). Message IDs are unique per message type within a session, not across types: a user message, an Agent message, and an Agent thought may share the same `messageId` and remain distinct messages. The same applies to other entity IDs such as `toolCallId` and `planId`. Clients key entities by type and ID. See [Entity IDs](/protocol/v2/prompt-lifecycle#entity-ids). ### Whole-message upserts Alongside the chunk updates, v2 adds `user_message`, `agent_message`, and `agent_thought` updates that carry a full `content` **array** (chunks carry a single content block). These are upserts keyed by `messageId`, with three-state patch semantics: * **Omitted** `content` leaves existing content unchanged (useful for updating `_meta` or other fields without resending content). * `content: null` **or** `content: []` clears the message content. * A **concrete array** replaces all content currently stored for that message, including content accumulated from earlier chunks. Chunks always **append** to whatever content is current. For example: `agent_message` with `content: [A]`, then `agent_message_chunk` with `B` renders as `[A, B]`. A later `agent_message` with `content: [C]` resets the message to `[C]`, and subsequent chunks append to that. Use chunks for streaming, and whole-message updates for output that is already complete, such as corrections or replay. ## Tool calls ### One upsert notification v1 had `tool_call` (create) and `tool_call_update` (modify). In practice the split bought nothing, so v2 keeps only `tool_call_update`. The first update with an unseen `toolCallId` creates the tool call. Subsequent updates patch it. Only `toolCallId` is required, but the Agent **SHOULD** include `title` on the first report: ```json theme={null} { "sessionUpdate": "tool_call_update", "toolCallId": "call_001", "name": "read_file", "title": "Reading configuration file", "kind": "read", "status": "pending" } ``` The patch semantics are the same three-state model as messages: omitted fields stay unchanged, `null` explicitly clears a field, and concrete values replace. Array fields such as `content` and `locations` are replaced wholesale when present. The optional `name` metadata is available in both versions. Concrete names map directly between versions, but v2's `name: null` clear cannot be represented by a v1 update because v1 treats `null` like omission. A strict adapter must reject that conversion, while an intentionally lossy adapter may omit the clear. The remaining fields (`title`, `kind`, `status`, `content`, `locations`, `rawInput`, `rawOutput`) and `kind` values are unchanged from v1. The `status` enum adds `cancelled`, and both enums are now extensible. Top-level `_meta` is now stored tool-call state, too. v1 gave no rule for keeping a `tool_call_update`'s `_meta`, so Agents could use it for data about one report. In v2, a concrete `_meta` patches the tool call's stored metadata by top-level key: keys it omits keep their stored values, a key set to `null` is removed, and any other value replaces that key whole (see [Metadata Patches](/protocol/v2/extensibility#metadata-patches)). A key sent on an earlier report therefore stays until the Agent sets it to `null` or clears `_meta`. Put data about a single report in the `session/update` notification's `params._meta` instead. ### Streaming tool-call content v2 adds `tool_call_content_chunk`, which **appends** a single `ToolCallContent` item to a tool call instead of resending the whole array: ```json theme={null} { "sessionUpdate": "tool_call_content_chunk", "toolCallId": "call_001", "content": { "type": "content", "content": { "type": "text", "text": "Checked syntax..." } } } ``` Chunks and updates compose exactly like message chunks and updates: a `tool_call_update` that includes `content` replaces the accumulated content. Later chunks append to it. ### Agent-owned terminal display v2 retains a `terminal` `ToolCallContent` shape, but changes its ownership and meaning. It is now only a reference to a display terminal owned by the Agent: ```json theme={null} { "type": "terminal", "terminalId": "term_001" } ``` The reference contains no mutable state. The Agent reports that separately with a `terminal_update` upsert keyed by `terminalId`: ```json theme={null} { "sessionUpdate": "terminal_update", "terminalId": "term_001", "command": "cargo test", "cwd": "/workspace/project", "size": { "cols": 120, "rows": 40 }, "output": { "data": "cnVubmluZyAxMjMgdGVzdHMNCg==" }, "exitStatus": { "exitCode": 0, "signal": null } } ``` Only `terminalId` is required. `command`, `cwd`, `size`, `output`, `exitStatus`, and `_meta` are patch fields: omission leaves the stored value unchanged, `null` clears it, and a concrete value replaces it, except that a `_meta` object patches stored metadata by top-level key. On a first-seen terminal, omitted fields start unknown or empty. Every supplied `cwd` must be absolute. `size` is the terminal size in character cells, with required `cols` and `rows`. When present, Clients can use it to render output as the program wrote it. `output` is an authoritative replacement snapshot for replay, correction, or resynchronization. Its required `data` field is RFC 4648 base64-encoded bytes and is the complete byte sequence the Agent wants the Client to retain for the terminal at that point. A concrete snapshot replaces all previously stored bytes. Clients must not merge or splice bytes from the previous snapshot into it. Optional nullable `output._meta` is snapshot-scoped. Omission and `null` both mean no snapshot metadata was provided. A concrete `exitStatus` marks the terminal as exited. Its optional nullable `exitCode` and `signal` fields use omission or `null` when unavailable. Optional nullable `exitStatus._meta` is scoped to that exit information and likewise treats omission and `null` as equivalent. Conventional POSIX signal names include `SIGTERM`, `SIGKILL`, and `SIGINT`. Other platforms may use platform-specific names. For example: `"exitStatus": { "signal": "SIGTERM" }`. For efficient live output, the Agent sends append updates: ```json theme={null} { "sessionUpdate": "terminal_output_chunk", "terminalId": "term_001", "data": "cGFzc2VkDQo=" } ``` Each chunk's `data` is independently base64-encoded. Decode each chunk separately, then append the resulting bytes in received order for that terminal. Do not concatenate encoded strings before decoding. Chunk boundaries may split UTF-8 code points and ANSI escape sequences, so text and terminal parsers retain state between chunks. A later `terminal_update.output` snapshot replaces all bytes accumulated so far, and subsequent chunks append to that replacement. A Client may use an isolated terminal emulator, but it only needs to provide a safe sanitized transcript fallback. The terminal is display-only: it has no input, resize, interrupt, wait, release, or execution semantics. The one control is opt-in cancellation, where an Agent lets the Client stop the process with [`terminal/cancel`](/protocol/v2/tool-calls#cancelling-terminals). ## Diff content The v1 diff shape (a single `path` with `oldText`/`newText`) could not distinguish a deleted file from an emptied one, had no way to express renames, copies, or binary changes, and forced clients to compute renderable diffs themselves. v2 replaces it with structured changes plus optional renderable patch text: ```json theme={null} { "type": "diff", "changes": [ { "operation": "modify", "path": "/home/user/project/src/config.json", "fileType": "text", "mimeType": "application/json" } ], "patch": { "format": "git_patch", "text": "diff --git /home/user/project/src/config.json /home/user/project/src/config.json\n--- /home/user/project/src/config.json\n+++ /home/user/project/src/config.json\n@@ -1,3 +1,3 @@\n {\n- \"debug\": false\n+ \"debug\": true\n }\n" } } ``` * `changes` (required) is the authoritative list of file-level operations. `add`, `delete`, and `modify` carry a `path`. `move` and `copy` carry `oldPath` and `path`. Each change may carry an optional `fileType` (`text`, `binary`, `directory`, `symlink`) and `mimeType`. Clients can build file trees and summaries from `changes` without parsing any patch text. * `patch` (optional) carries renderable text for some or all changes and **MUST** be consistent with `changes`. Stable v2 defines `git_patch` as one or more `diff --git` sections in Git's `--patch` (`-p`) text format. Unlike Git's repository-relative paths, every path **MUST** be absolute, including in `rename from`, `rename to`, `copy from`, and `copy to` lines, with no prefix such as Git's default `a/` and `b/`. Otherwise paths follow Git, including `/dev/null` for the missing side of an added or deleted file and Git's quoting of unusual paths. See [Diffs](/protocol/v2/tool-calls#diffs) for producing this with `git diff`. Surrounding commit metadata and email envelopes **MUST NOT** be included. Agents **SHOULD** provide `patch` whenever feasible. Clients **MUST** handle diffs where `patch` is omitted or `null` (binary changes, symlink retargets, and similar cases have no useful text rendering). A deleted file is now simply: ```json theme={null} { "type": "diff", "changes": [ { "operation": "delete", "path": "/home/user/project/old_file.txt", "fileType": "text" } ] } ``` There is no mechanical mapping from v2 diffs back to `oldText`/`newText`. When migrating a v1 client, render `patch.text` according to `patch.format`, using `changes` for headers, file trees, and non-text cases. ### Edits known only as a snippet Many v1 Agents filled `oldText` and `newText` with just the replaced snippet, such as an edit tool's `old_string` and `new_string`, without reading the file. v2 has no form for a snippet: a `git_patch` hunk needs line numbers, and each entry in `changes` needs an operation, which a snippet does not always tell. An edit with an empty `old_string`, for example, is an `add` or a `modify` depending on whether the file exists. A tool that writes a whole file has the same gap: its input has the new contents, but not the old ones or the operation. Such an Agent has two options: * Read the file before the tool runs, and compute `changes` and `patch` from its contents. * Send no diff until the change is done. Until then, `locations` can still point the Client at the file. Read the file somewhere the tool waits on, so it still holds its contents from before the change. Reading once the tool input is complete races an auto-approved edit, which may already have run, and the patch would then be computed against the edited file. A permission check is safe, but auto-approved edits skip it, so they need a hook that runs before the tool, such as Claude Code's `PreToolUse` hook. ## Permission requests `session/request_permission` no longer takes a bare `toolCall`. The prompt copy and the subject of the request are now separate concerns: ```json theme={null} { "jsonrpc": "2.0", "id": 5, "method": "session/request_permission", "params": { "sessionId": "sess_abc123", "title": "Run this script?", "description": "The agent wants to execute scripts/setup.sh in your project.", "subject": { "type": "tool_call", "toolCall": { "toolCallId": "call_001", "title": "Execute setup script", "kind": "execute", "status": "pending" } }, "options": [ { "optionId": "allow", "name": "Allow once", "kind": "allow_once" }, { "optionId": "deny", "name": "Deny", "kind": "reject_once" } ] } } ``` * `title` is **required**: human-readable text for the permission prompt itself. It does not update any tool call's displayed title. * `description` is optional supporting copy. * `subject` is an optional tagged union describing *what* needs permission. Stable v2 defines `type: "tool_call"`, whose `toolCall` payload is the same `ToolCallUpdate` upsert shape used in session updates, and `type: "command"`, which describes an Agent-executed command. Requests may omit `subject` entirely for approvals without structured context, and unknown subject types should be preserved when proxying and either rendered generically or declined by policy. In v1, agents routinely stuffed permission prompt text into the tool call's `title`, mutating displayed tool state as a side effect. In v2, put prompt copy in `title`/`description` and let `subject.toolCall` carry only genuine tool-call state. A command permission subject is self-contained rather than a patch: ```json theme={null} { "type": "command", "command": "cargo test", "cwd": "/workspace/project", "toolCallId": "call_001", "terminalId": "term_001" } ``` `command` and `cwd` are required, and `cwd` must be absolute. `toolCallId`, `terminalId`, and `_meta` are optional and nullable. Omission and `null` are equivalent and mean the value was not provided. The IDs only associate the permission with displayed state and may be absent when permission is requested before execution. Approval authorizes the Agent to execute the command. It never asks the Client to execute it. `options` and the response shape are unchanged: options carry `optionId`, `name`, and `kind` (`allow_once`, `allow_always`, `reject_once`, `reject_always`), and the response outcome is `{ "outcome": "selected", "optionId": ... }` or `{ "outcome": "cancelled" }`. Both unions are extensible in v2, with one safety rule: an Agent that receives an outcome it does not understand **MUST NOT** treat it as approval. In v1, `cancelled` meant the prompt turn was cancelled. In v2 the Client also sends it when the user dismisses the prompt or the Client declines it by policy. The Agent **MUST NOT** proceed with that operation, but `cancelled` alone doesn't mean the foreground work is ending. Cancellation is reported separately. While foreground work as a whole is blocked on a permission response, the Agent **SHOULD** report `state_update` with `requires_action`. Once reported, it **MUST** report `running` when foreground progress resumes, or `idle` if the work ends without resuming. A permission request for independent background activity does not by itself change the foreground state, and resolving a permission request does not itself imply `running`. Apply the [aggregate transition rules](/protocol/v2/prompt-lifecycle#waiting-for-user-action), including with concurrent requests and late answers. ## Plans The v1 `plan` update was a flat entries list with no identity and no room to grow. v2 replaces it with `plan_update`, whose payload is a tagged union keyed by a required `planId`: ```json v1 theme={null} { "sessionUpdate": "plan", "entries": [ { "content": "Check for syntax errors", "priority": "high", "status": "pending" } ] } ``` ```json v2 theme={null} { "sessionUpdate": "plan_update", "plan": { "type": "items", "planId": "plan-1", "entries": [ { "content": "Check for syntax errors", "priority": "high", "status": "pending" } ] } } ``` Stable v2 defines the `items` plan type. The entry shape (`content`, `priority`, `status`, all required) is unchanged from v1. Entry priorities and statuses are now extensible enums, and `status` adds `cancelled`. Each `plan_update` for a given `planId` replaces that plan's entries (send `entries: []` to empty it), and the `planId` allows multiple plans per session and future plan content types (such as markdown or file-backed plans, which remain unstable) without another breaking change. ## Session setup and lifecycle ### `session/load` is gone. `session/resume` does both v1 had two ways to reattach to a session: `session/load` (replays full history, gated by `loadSession`) and `session/resume` (no replay, gated by `sessionCapabilities.resume`). v2 keeps only `session/resume` with an optional `replayFrom` cursor: ```json theme={null} { "jsonrpc": "2.0", "id": 3, "method": "session/resume", "params": { "sessionId": "sess_abc123", "cwd": "/home/user/project", "replayFrom": { "type": "start" } } } ``` * Omit `replayFrom` (or send `null`) for v1 `resume` behavior: reattach without replay. * `"replayFrom": { "type": "start" }` for v1 `load` behavior: the Agent replays all retained conversation history as `session/update` notifications (using the same updates as live traffic) before responding. The Agent can send current state, such as a terminal `output` snapshot, instead of every historical update. See [Replay Contents](/protocol/v2/session-setup#replay-contents). The cursor is a tagged union so future versions can add replay-from-a-point variants without new methods. The schema accepts custom and future cursor types for preservation by intermediaries, but Agents **MUST** reject unsupported types or malformed cursors with `-32602` (Invalid params), not silently fall back to another replay mode. Retained user messages **MUST** preserve the ID returned by `session/prompt`. Agents **SHOULD** preserve agent and thought message IDs when possible, but Clients cannot assume those IDs remain stable across reconnects or restarts. The same applies to `toolCallId`, `terminalId`, and `planId`. For full replay, Clients **SHOULD** rebuild messages, tool calls, terminals, and plans rather than merge them into existing state by ID. If you replay messages as chunks, as many v1 Agents do, start each one with a message update carrying `content: []` so the chunks don't append to content the Client already holds, or send the message as one whole-message update instead. This empty-content primer resets only the ID used in that replay. It cannot clear a message previously delivered under another ID. See [Resuming Sessions](/protocol/v2/session-setup#resuming-sessions). ### Consistent lifecycle requests `session/new` and `session/resume` take the same shape of environment parameters: a required `cwd` (absolute path), plus optional `additionalDirectories` and `mcpServers`. Note that `mcpServers` was required (even if empty) on `session/new` in v1 and is now optional. Omitting it and sending `[]` are equivalent. Both responses **MAY** include the session's `configOptions` and initial `availableCommands`. Neither carries `modes` anymore. `additionalDirectories` still requires the `session.additionalDirectories` capability and absolute paths, and each `session/resume` must send the full intended additional-root list. Omitting the field or sending `[]` activates no additional roots rather than restoring previous ones. The same applies to `mcpServers` on resume. ### Baseline methods As covered under [Initialization](#capability-reorganization), advertising `capabilities.session` commits the Agent to `session/new`, `session/list`, `session/resume`, `session/close`, `session/prompt`, `session/cancel`, and `session/update`. Clients can rely on listing, resuming, and closing sessions without probing individual capability markers. `session/delete` remains optional behind `session.delete`. ## Session modes become config options The dedicated modes API is removed: the `modes` field on session responses, `session/set_mode`, the `current_mode_update` notification, and all `SessionMode*` types. Mode-like state (and model selection, thinking level, and similar knobs) is expressed through session config options, which already existed in v1: ```json theme={null} { "configId": "mode", "name": "Session Mode", "category": "mode", "type": "select", "currentValue": "ask", "options": [ { "value": "ask", "name": "Ask" }, { "value": "code", "name": "Code" } ] } ``` * The option's identifier field is renamed from `id` to `configId`, matching the parameter name used by `session/set_config_option`. * The stable `category` values are `mode`, `model`, `model_config`, and `thought_level`. Clients can use them for UX affordances (placement, shortcuts) and must tolerate unknown categories. * Clients change values with `session/set_config_option` (`sessionId`, `configId`, `type`, `value`). The required `type` discriminator is `"id"` with a string option ID or `"boolean"` with a boolean value. The response returns the full updated `configOptions` array, since one change can affect other options. Agent-initiated changes arrive as `config_option_update` session updates, which replace the v1 `current_mode_update`. The `switch_mode` tool kind stays, and now means changing the `mode`-category config option. ## Client file system and terminal execution removed v2 removes all of the v1 Client-provided file and terminal methods: * `clientCapabilities.fs` and the `fs/read_text_file` / `fs/write_text_file` methods * `clientCapabilities.terminal` and the `terminal/create`, `terminal/output`, `terminal/release`, `terminal/wait_for_exit`, `terminal/kill` methods In practice these methods were inconsistently implemented outside of a few IDEs, and agents already needed their own file and execution handling for clients that didn't offer it. Clients that want to expose file access, unsaved editor state, or command execution to agents should do so by providing an **MCP server** to the session (via `mcpServers` on `session/new` / `session/resume`), which puts those tools on the same footing as every other tool the Agent uses. Agent-side, drop the capability checks and the dual execution paths. Report file changes through [diff content](#diff-content). When byte-faithful command display matters, report output through the new Agent-owned terminal stream. The v2 `terminal` content reference does not restore Client-side execution. It only anchors display state supplied by the Agent. ## MCP server configuration MCP transport configuration is aligned with the current MCP transport model: * Every server config **MUST** carry a `type` discriminator. In v1, stdio configs had no `type` field. In v2 they are `"type": "stdio"`. Unknown transport types can then be carried as extension variants instead of failing to parse. * The deprecated HTTP+SSE transport (`"type": "sse"`) is **removed**. * Support is advertised per transport under `capabilities.session.mcp`: `stdio` is now an explicit capability (`session.mcp.stdio`), so agents that cannot launch subprocesses can opt out, and `session.mcp.http` covers remote servers. * Each server `name` **MUST** be unique within `mcpServers`, and Agents reject duplicates with `-32602`. * On `session/resume`, `mcpServers` is the complete set of Client-provided servers, like `additionalDirectories`. Servers from earlier requests are not restored. * Empty arrays are no longer required: `args` and `env` on stdio configs and `headers` on HTTP configs are optional in v2 (v1 required `args`, `env`, and `headers` even when empty). ```json theme={null} { "mcpServers": [ { "type": "stdio", "name": "filesystem", "command": "/usr/local/bin/mcp-fs", "args": ["--root", "/home/user/project"] }, { "type": "http", "name": "linear", "url": "https://mcp.linear.app/mcp" } ] } ``` ## Content blocks The five content block types are unchanged: `text`, `image`, `audio`, `resource_link`, and `resource`. v2 realigns their fields with [MCP 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28/schema#contentblock). Notably, `resource_link` gains an optional `icons` array (each icon has a required `src` URI plus optional `mimeType`, `sizes`, and `theme` of `light`/`dark`), and the `type` discriminator is extensible like every other v2 enum, so unknown block types no longer break deserialization for receivers that have a fallback. `IconTheme` and annotation `Role` values are extensible too, and icons and annotations accept `_meta`. If you maintain a validator or generated models, v2 also tightens schema-level details that v1 left loose: base64 payloads (image/audio and terminal `data`, resource `blob`) are marked with `contentEncoding: "base64"`, URI fields are marked `format: "uri"`, `SessionInfo.updatedAt` is marked `format: "date-time"`, `annotations.priority` is bounded to the inclusive range 0–1, multi-select elicitation `items` need at least one option, `session/prompt` `prompt` needs at least one content block, form-mode `requestedSchema` requires `type: "object"` and `properties`, and setup-response `configOptions` is no longer nullable: omit it rather than sending `null`. ## Slash commands Agents **MAY** now return initial `availableCommands` alongside `configOptions` in `session/new` and `session/resume` responses. The draft `session/fork` response also supports commands for the newly created session when forking is supported. This avoids requiring command notifications before the `session/new` response. See the [setup response example](/protocol/v2/session-setup#initial-session-state). In setup responses, `availableCommands` is an optional array: omission or `[]` means no initial commands are advertised, and empty lists are omitted when serializing. `null` is not a valid outbound value. `available_commands_update` notifications remain supported for advertising commands later or changing them. Each notification replaces the complete list previously advertised in a response or notification. `[]` clears it. A command still carries `name` and `description`, but each command and its optional `input` specification are now tagged unions. Commands gain a required `type: "command"` discriminator so other kinds of commands can be added later, and the v1 untagged unstructured input gains an explicit `type: "text"` discriminator so richer input types can be added later: ```json v1 theme={null} { "name": "search", "description": "Search the codebase", "input": { "hint": "query to search for" } } ``` ```json v2 theme={null} { "type": "command", "name": "search", "description": "Search the codebase", "input": { "type": "text", "hint": "query to search for" } } ``` As with other extensible unions, unknown command and input types should be preserved when proxying. Every command type carries `name` and `description`, so a client that doesn't understand a command type can ignore it or display it as a plain command. A client that can't render an input type can fall back to plain text input or hide the command's input hint. ## Consistent ID naming v2 applies one naming rule across the schema: a field that identifies a protocol entity or references one is named after its domain (`sessionId`, `messageId`, `toolCallId`, `planId`, `optionId`), never a generic `id`. The concrete renames from v1: | Where | v1 | v2 | | - | - | - | | Auth method descriptor | `id` | `methodId` | | Session config option | `id` | `configId` | | Session config select group | `group` | `groupId` | New entities introduced in v2 follow the same rule (`messageId` on messages, `planId` on plans). A few schema definition names also changed without any wire-format change, which matters only to schema-codegen consumers: the `session/update` and `session/cancel` payload types are now `UpdateSessionNotification` and `CancelSessionNotification`, the auth request/response types follow the new method names (`LoginAuthRequest`/`LoginAuthResponse`, `LogoutAuthRequest`/`LogoutAuthResponse`), and the Client auth capability type is now `ClientAuthCapabilities`. Definitions tied to wire changes are renamed or removed along with them, for example `UnstructuredCommandInput` → `TextCommandInput`, `Plan` → `PlanUpdate`, `ToolCall` → `ToolCallUpdate`, and `McpServerSse` removed. These lists are not exhaustive. Compare the `$defs` of the two schemas for the complete set. ## Extensibility and forward compatibility v2 makes the whole schema forward-compatible by convention: * **Open enums and tagged unions.** Enum-like strings and tagged unions accept unknown values, except the few [closed ones](/protocol/v2/extensibility#enum-and-tagged-union-variants). Values beginning with `_` are reserved for implementation-specific extensions (e.g. `_com.example/widget`). Unknown values *without* a leading `_` are reserved for future ACP versions. Receivers **SHOULD** preserve unknown values when storing, replaying, proxying, or forwarding, and either render them generically or fall back safely. Do not mint non-underscore custom values. * **`_meta` everywhere.** As in v1, `_meta` objects carry implementation metadata. In v2's upsert-style updates, top-level `_meta` is a patch: omitted means unchanged, `null` clears it, and an object patches stored metadata by top-level key, where a key set to `null` is removed and any other value replaces that key whole (see [Metadata Patches](/protocol/v2/extensibility#metadata-patches)). Metadata nested in a snapshot, exit-status object, content item, command permission subject, or chunk is scoped to that object. Omission and `null` are equivalent. * **Custom methods** still use the `_` prefix, unchanged from v1. ## Transports stdio remains the primary transport and is unchanged. Each message is a single JSON-RPC object. ACP does not use JSON-RPC batches, and receivers reject an array with `-32600`. Apply a session's `session/update` notifications in the order received. See [Transports](/protocol/v2/transports#no-batches). A standard remote transport (streamable HTTP with SSE streams, plus WebSocket) is being specified in its own RFD and is not part of core v2. See the [transport RFD](/rfds/streamable-http-websocket-transport) for its current state. ## Errors Several error rules that were SHOULD in v1 are MUST in v2, and v2 adds one. Agents and Clients **MUST**: * respond with `-32601` to a method they don't implement, or to a capability-gated method they didn't advertise * respond with `-32002`, with `data.sessionId`, to a session-scoped request for a session that doesn't exist or isn't active on the connection * reject a request other than `initialize` that arrives before initialization completes with `-32600`, and also an `initialize` repeated after another request See [Errors](/protocol/v2/error). ## Migration checklist: Agents 1. **Initialization.** Read `params.capabilities` / `params.info`. Return `capabilities` and a required `info`. Restructure your capability object: nest prompt and MCP capabilities under `session`, convert boolean markers to `{}` objects, drop `loadSession` and the `list`/`resume`/`close` markers. 2. **Implement the baseline.** If you advertise `session`, implement `session/new`, `session/list`, `session/resume`, `session/close`, `session/prompt`, `session/cancel`, and `session/update`. On `session/close`, finish cancelled foreground work (final updates and the idle `cancelled` state) before responding. 3. **Auth.** Rename `authenticate` → `auth/login` for method types that define protocol-driven login. If you return a non-empty `authMethods` list, implement both `auth/login` and `auth/logout`. If you omit the field or return an empty array, Clients **MUST NOT** call either method. Do not add a logout support marker: `capabilities.auth` is only for authentication-related extensions. Add `type` and `methodId` to your auth method descriptors, and send terminal method `env` as `{ "name", "value" }` entries. 4. **Prompt lifecycle.** Respond to an accepted `session/prompt` with `{ "messageId": "…" }`, carrying the agent-generated ID of the inserted user message. Emit a `user_message` (or streamed `user_message_chunk`) acknowledgment with the same `messageId`, a `running` state update when foreground work starts (or `requires_action` if it starts blocked, then `running` when progress resumes), and an idle `state_update` carrying the stop reason when it ends, including `cancelled` after `session/cancel`. Don't reject a prompt only because work is active: insert or hold it, and answer prompts not yet inserted with `-32800` on `session/cancel` or `session/close`. Report a failure after insertion as an idle `state_update` with `stopReason: "error"` and the JSON-RPC error in `error`, never as an error response to the prompt. Background updates may continue while idle. 5. **Message IDs.** Generate and attach a `messageId` to every message chunk and update. 6. **Tool calls.** Stop sending `tool_call`. Send `tool_call_update` for creation and patches. Use `tool_call_content_chunk` to stream content. Respect omit/`null`/value patch semantics, including key-level `_meta` patches. 7. **Terminal output.** Add `terminal` content references for Agent-owned display terminals. Send `terminal_update` for command, absolute cwd, size, snapshots, and exit state. Send independently base64-encoded `terminal_output_chunk` values for live bytes. Do not expect Client control methods or capability negotiation. 8. **Diffs.** Replace `oldText`/`newText` with `changes` (+ `fileType`/`mimeType` where known) and provide `patch` in `git_patch` format whenever feasible. If a tool's input describes an edit only as a snippet, read the file somewhere the tool waits on, before it can run, or send no diff until the change is done (see [Edits known only as a snippet](#edits-known-only-as-a-snippet)). 9. **Permissions.** Put prompt copy in required `title` (+ optional `description`). Use the `tool_call` subject for tool-call state and the `command` subject for a command, required absolute cwd, and optional tool-call/terminal associations. Treat a `cancelled` outcome as "don't proceed with this operation", not as the turn ending. 10. **Plans.** Send `plan_update` with `{ "sessionUpdate": "plan_update", "plan": { "type": "items", "planId": ..., "entries": [...] } }`. 11. **Modes and config options.** Drop `session/set_mode`, `modes`, and `current_mode_update`. Expose the same state as config options with `category: "mode"` and emit `config_option_update`. Rename option `id` to `configId` and group `group` to `groupId`, and require the `type` discriminator (`"id"` or `"boolean"`) on `session/set_config_option`. 12. **Replay.** Handle `replayFrom` on `session/resume`. Replay history as ordinary `session/update` notifications when asked, current-state snapshots such as terminal `output` are fine. When the Client may already hold an entity's `_meta`, remove stale keys explicitly, since an `_meta` object no longer replaces them. Start chunked messages with an empty-content update. Remove `session/load`. 13. **Client file and terminal methods.** Remove all `fs/*` and `terminal/*` calls. The new terminal content is Agent-owned display state, not a Client resource. 14. **MCP config.** Require and emit `type` discriminators. Reject SSE and unadvertised transports with `-32602`. Advertise `session.mcp.stdio` / `session.mcp.http` as appropriate. 15. **Slash commands.** Add the `type: "command"` discriminator to each advertised command and the `type: "text"` discriminator to command `input` specifications. Optionally advertise initial commands in setup responses via `availableCommands`, and use complete-replacement `available_commands_update` notifications for later changes. 16. **Parsing.** Make enum handling open: preserve unknown variants where a safe fallback exists. 17. **Errors.** Return the now-required [error codes](#errors): `-32601`, `-32002` with `data.sessionId`, and `-32600` before initialization or for a late `initialize`. ## Migration checklist: Clients 1. **Initialization.** Send `protocolVersion: 2`, required `info`, and `capabilities` (drop `fs`/`terminal`, and advertise terminal auth as `auth.terminal: {}`). Read the Agent's capabilities from `result.capabilities` with presence checks instead of boolean checks. 2. **Rely on the baseline.** When `capabilities.session` is present, use list/resume/close/prompt/cancel without probing markers. Keep checking `session.delete` and other optional extras. 3. **Prompt lifecycle.** Don't treat the `session/prompt` response as turn completion. Drive UI from `state_update` (`running` / `idle` / `requires_action`), take the stop reason from the idle update, and render the user's message from the `user_message` acknowledgment (which carries its canonical `messageId`). Treat `stopReason: "error"` as a failed outcome and read its details from the idle update's `error`. An error response to `session/prompt` means the message was not inserted. Keep accepting background updates while idle. 4. **Messages.** Track messages by required `messageId`. Implement upsert semantics: whole-message updates replace content (or clear it with `null`/`[]`), chunks append. 5. **Tool calls.** Create tool calls on first-seen `toolCallId` in `tool_call_update`. Apply omit/`null`/value patches, and patch top-level `_meta` by key. Append `tool_call_content_chunk` items. Replace accumulated content when an update carries `content`. 6. **Terminal output.** Maintain Agent-owned terminal state by `terminalId`. Apply update patch and snapshot-replacement semantics, and use the reported `size` for rendering when present. Independently decode and append chunk bytes. Render them in an isolated terminal emulator or sanitized transcript, with no input or process controls. 7. **Diffs.** Render `patch.text` when present. Drive file trees and summaries from `changes`. Handle patch-less diffs (binary, symlink, directory). 8. **Permissions.** Render `title`/`description`. Apply `tool_call` subjects like ordinary tool-call updates, and render `command` subjects from their command, required absolute cwd, and optional associations. Show a generic prompt for absent or unknown subjects. Answer `cancelled` when the user dismisses the prompt or policy declines it. 9. **Plans.** Handle `plan_update` keyed by `planId`. Each update replaces that plan's entries. 10. **Notices and compaction.** Handle `notice`, `compaction_update`, and `compaction_summary_chunk`, or ignore them. v2 sends them without a Client capability. 11. **Modes and config options.** Drop `session/set_mode` and `current_mode_update` handling. Drive mode/model UI from `configOptions` (using `category`) via `session/set_config_option` and `config_option_update`. Read `configId` and `groupId`, render `boolean` options, and send `session/set_config_option` with a `type` of `"id"` or `"boolean"`. 12. **Resume.** Replace `session/load` with `session/resume` + `replayFrom: { "type": "start" }`, and plain reconnects with `session/resume` without `replayFrom`. 13. **Client file and terminal methods.** Remove `fs/*` and `terminal/*` implementations for v2 connections. Expose Client-side tools through MCP servers passed in `mcpServers`, using only transports the Agent advertises under `session.mcp`. Do not treat display terminals as Client resources. 14. **Cancellation.** After `session/cancel`, keep accepting updates and wait for the idle `state_update` with `stopReason: "cancelled"` as confirmation. 15. **Parsing.** Preserve unknown enum variants, tolerate unknown `sessionUpdate` types, and read commands and their `input` as tagged unions. Read initial `availableCommands` from setup responses and replace the list on each `available_commands_update`, including `[]` to clear it. ## Migration checklist: SDKs 1. **Separate the versions.** Keep v1 and v2 schemas, generated models, and test fixtures fully separate. Exposing unstable-v2 types does not advertise support. Enforce each feature's documented negotiation requirements independently of `protocolVersion: 2`. 2. **Three-state fields.** Model omitted vs `null` vs concrete values distinctly wherever v2 defines patch semantics. A plain nullable/optional type erases a distinction the protocol depends on. Apply the top-level `_meta` of upserts as a key-level patch rather than a replacement. 3. **Strict where it counts.** Reject malformed payloads for *known* discriminator values instead of demoting them to the unknown-variant fallback. The fallback exists only for genuinely unknown values. 4. **Preserve what you don't understand.** Round-trip `_`-prefixed extension values, unknown future variants, and `_meta` when storing, replaying, proxying, or forwarding. 5. **Fixtures.** Cover the full prompt lifecycle, resume replay, cancellation, permission flow, message replacement and clearing, tool-call content chunks, terminal snapshot replacement, split and invalid UTF-8 bytes, exit state, command subjects, and structured diffs. 6. **Stop reasons.** Model the idle update's stop reason as a union tagged by `stopReason` and flattened into the update, so a stop reason can carry fields of its own, such as the `error` stop reason's `error`. Keep unknown stop reasons with their fields, and treat a missing, `null`, or non-string `stopReason` as no stop reason rather than rejecting the update. ## Supporting v1 and v2 side by side Supporting both versions is the recommended path, not an edge case: v1 peers will remain in the wild well after v2 stabilizes, and dropping v1 support means losing them. Version negotiation gives you one protocol version per connection, so the cleanest approach is to keep two thin protocol layers behind shared application logic and select one after `initialize`. ### Negotiate once, then use the selected version The [v2 version negotiation rules](/protocol/v2/initialization#version-negotiation) apply to Agent endpoints implementing v2, including dual-stack endpoints. They do not impose new requirements on legacy v1-only Agents: * The Client **MUST** request the latest version it supports. * An Agent implementing v2 **MUST** select the highest supported version at or below the requested version. If none exists, it **MUST** return `-32022` with `requested` and `supported` data instead of a higher-version success response. * Both peers **MUST** use the selected version's specification for subsequent traffic. A Client that cannot support the returned version **SHOULD** close the connection and inform the user. For an Agent supporting both v1 and v2, a v1 request selects v1, a v2 request selects v2, and a request for a newer unsupported version selects v2. An Agent supporting only v1 returns v1 to a Client requesting v2. The returned version is a selection, not a promise that the Agent will translate subsequent v2 messages into v1. Keep initialization separate from session setup. Prepare handlers for both versions before connecting, but dispatch subsequent traffic through only the selected version's handlers. Inspect the selected version before sending `session/new` or interpreting capabilities. The request uses the Client's requested-version initialization shape, while the response uses the Agent's selected-version shape. For example, a v2 request carries `info` and `capabilities`, while a v1 response carries `agentInfo` and `agentCapabilities`. A version-specific SDK Client API is not necessarily a dual-stack Client: it may reject a response selecting the other version. Use the SDK's negotiation support where available. If falling back requires a new SDK connection, close the first connection and initialize the replacement with the selected version's API. An Agent implementing v2 also accepts a [repeated `initialize`](/protocol/v2/initialization#repeating-initialization) before any other request. A legacy v1-only Agent may not. ### Agent routing in the SDKs The TypeScript SDK exposes the router through its experimental v2 entry point: ```typescript theme={null} import * as v2 from "@agentclientprotocol/sdk/experimental/v2"; // v1Agent and v2Agent implement their respective protocol versions. v2.agentProtocolRouter().withV1(v1Agent).withV2(v2Agent).connect(stream); ``` The [runnable dual-version TypeScript agent](https://github.com/agentclientprotocol/typescript-sdk/blob/main/src/examples/dual-version-agent.ts) shows both implementations on one stdio endpoint, including their different prompt lifecycles. From a checkout of the TypeScript SDK with dependencies installed, run `npm run build`, then configure your Client to launch `node dist/examples/dual-version-agent.js` from that checkout. The Rust SDK provides the corresponding builder with the `unstable_protocol_v2` crate feature: ```rust theme={null} use agent_client_protocol::Agent; let agent = Agent .protocol_router() .with_v1(v1_agent) .with_v2(v2_agent); ``` See the Rust SDK's [protocol v2 guide](https://agentclientprotocol.github.io/rust-sdk/protocol-v2.html#version-routing) for agent routing and Client-side fallback. These routers select a version-specific implementation and normalize initialization parameters for it. They do not translate later requests, notifications, or responses. A standalone v2 Agent API can negotiate v2 with a Client requesting a newer version, but it does not provide a v1 implementation. Register both implementations to serve v1 Clients. ### Version mismatch is an initialization failure A v2-only endpoint rejects a v1 request with `-32022` and `data: { "requested": 1, "supported": [2] }`. It does not need to invoke the v2 initialization handler or require v2's Client identity just to report this mismatch. The connection is not initialized, and the Client should close it. A v2-aware Client can display the supported versions, while an existing v1 Client can report the initialization error generically. A request for a newer version can still select v2. A v1-only endpoint can select v1 for a v2 request. In either case, the Client must check whether it supports the selected version before proceeding. The latest-version integer does not advertise a complete set of supported versions. Do not confuse version mismatch with malformed initialization parameters. A missing, non-integer, or out-of-range `protocolVersion`, or malformed parameters for a supported version, remains `-32602` (`Invalid params`). Agents read `protocolVersion` first, so a version mismatch is never reported as `-32602`, and parameters written for a newer version are not rejected. Use the SDK routers to negotiate before dispatching to a version-specific implementation. ### Share application logic, not wire shapes Keep business logic, tool execution, and any shared persistence behind version-specific adapters. Each adapter owns its protocol's capabilities, validation, and lifecycle: * **Prompt completion:** v1 keeps `session/prompt` pending until the turn ends. v2 acknowledges insertion and reports foreground completion through an idle `state_update`. * **Conversation updates:** v1 streams chunks, while v2 also supports identified entities, replacements, clearing, and replay. A v1 projection must not assume it can represent every v2 update. * **Client tools:** v1 may use Client file system and terminal methods. v2 uses MCP servers for Client-side tools. Agent-owned display terminals are not a replacement execution API. Advertise only what each adapter implements. Negotiating v2 does not enable unstable features, and sharing a session store does not automatically make every session resumable through both versions. Define cross-version session access explicitly if your application offers it. General-purpose v1↔v2 struct conversions cannot implement these lifecycle differences or represent every state. Prefer adapters over blanket conversions. Any shared conversion helper should have a narrow contract and report unsupported or lossy mappings explicitly rather than silently dropping behavior. ### Validate the dual-stack endpoint Exercise the same published endpoint with both v1 and v2 Clients: 1. Check that each Client reaches the matching implementation and receives that version's capabilities. 2. Check fallback from a v2 Client to a v1-only Agent, including whether the Client continues with v1 or disconnects. 3. Send a higher requested version, including parameters the Agent can't parse, and check that the Agent selects its latest supported version. 4. Run prompt completion and cancellation through both versions, and assert each version's completion signal, not just successful initialization. 5. Check that disabling draft v2 support leaves the v1 endpoint working. 6. Send a v1 request without Client identity to a v2-only endpoint. Check for `-32022` with `requested: 1` and `supported: [2]`, and check that no v2 session work starts. # Overview Source: https://agentclientprotocol.com/protocol/v2/overview How the Agent Client Protocol works The Agent Client Protocol allows [Agents](#agent) and [Clients](#client) to communicate by exposing methods that each side can call and sending notifications to inform each other of events. ## Communication Model The protocol follows the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification with two types of messages: * Methods are request-response pairs that expect a result or error. * Notifications are one-way messages that don't expect a response. Unlike base JSON-RPC, request IDs **MUST** be a string or an integer, never `null`. An error response has `id: null` only when the request ID could not be determined. Both sides send requests, and each side chooses IDs for its own requests independently, so the same ID can be in use in both directions. A sender **MUST NOT** reuse an ID while a request with that ID is still awaiting a response. Unlike base JSON-RPC, ACP does not use batches. See [Transports](/protocol/v2/transports#no-batches). ## Message flow A typical flow follows this pattern: **1. Initialization Phase** * Client → Agent: `initialize` to establish connection * Client: completes an advertised authentication flow if required. For example, `auth/login` for an Agent-handled method or launch and reconnect for a terminal method **2. Session Setup - either:** * Client → Agent: `session/new` to create a new session * Client → Agent: `session/resume` to resume an existing session **3. Prompt Lifecycle** * Client → Agent: `session/prompt` to send user message * Agent → Client: `session/prompt` response once the prompt is accepted * Agent → Client: `session/update` notifications for accepted messages, state updates, progress updates, and user-facing notices * Agent → Client: Permission requests as needed * Client → Agent: `session/cancel` to cancel foreground work if needed * Agent → Client: An idle `state_update` with a stop reason when foreground work ends, even if background activity continues ## Agent Agents are programs that use generative AI to autonomously modify code. They typically run as subprocesses of the Client. ### Baseline methods Some baseline methods are optional as a group. An Agent that returns a non-empty `authMethods` list **MUST** implement both `auth/login` and `auth/logout`. If `authMethods` is omitted or empty, Clients **MUST NOT** call either method. The `session/*` methods require `capabilities.session`. **initialize** [Negotiate versions and exchange capabilities.](/protocol/v2/initialization). **auth/login** Authenticate with the Agent (if required). **auth/logout** [End the current authenticated state](/protocol/v2/authentication#logging-out). **session/new** [Create a new conversation session](/protocol/v2/session-setup#creating-a-session). **session/prompt** [Send user prompts](/protocol/v2/prompt-lifecycle#1-user-message) to the Agent. **session/list** [List known sessions](/protocol/v2/session-list). **session/resume** [Resume an existing session, optionally replaying history](/protocol/v2/session-setup#resuming-sessions). **session/close** [Close an active session](/protocol/v2/session-setup#closing-active-sessions). ### Optional methods **session/set\_config\_option** [Change a session configuration option](/protocol/v2/session-config-options#from-the-client) (required when the Agent advertises config options). **session/delete** [Delete a session](/protocol/v2/session-delete) (requires the `session.delete` capability). ### Notifications **session/cancel** [Cancel the session's foreground work](/protocol/v2/prompt-lifecycle#cancellation) (no response expected). ## Client Clients provide the interface between users and agents. They are typically code editors (IDEs, text editors) but can also be other UIs for interacting with agents. Clients manage the environment, handle user interactions, and control access to resources. ### Baseline methods **session/request\_permission** [Request user authorization](/protocol/v2/tool-calls#requesting-permission) for operations such as tool calls and commands. ### Optional methods **elicitation/create** [Request structured information from the user](/protocol/v2/elicitation) (requires the matching `elicitation` mode capability). ### Notifications **elicitation/complete** [Report completion of an out-of-band URL interaction](/protocol/v2/elicitation#url-completion) (no response expected). **session/update** [Send session updates](/protocol/v2/prompt-lifecycle#3-agent-reports-output) to inform the Client of changes (no response expected). This includes [message updates and chunks](/protocol/v2/content), [tool calls, updates, and content chunks](/protocol/v2/tool-calls), [display-only terminal state and output chunks](/protocol/v2/tool-calls#display-only-terminals), [plans](/protocol/v2/agent-plan), [available commands updates](/protocol/v2/slash-commands#advertising-commands), [config option updates](/protocol/v2/session-config-options#from-the-agent), [context compactions](/protocol/v2/prompt-lifecycle#session-compaction), and [user-facing notices](/protocol/v2/prompt-lifecycle#session-notices). ## Request cancellation Either side can send [`$/cancel_request`](/protocol/v2/cancellation) to cancel a request it sent (no response expected). ## Argument requirements * All file paths in the protocol **MUST** be absolute, in the native syntax of the machine the Agent runs on (for example `/home/user/project`, `C:\Users\user\project`, or `\\server\share\project`), and are not URIs. * Line numbers are 1-based ## Error handling All methods follow standard JSON-RPC 2.0 [error handling](https://www.jsonrpc.org/specification#error_object): * Successful responses include a `result` field * Errors include an `error` object with `code` and `message` * Notifications never receive responses (success or error) See [Errors](/protocol/v2/error) for the error codes ACP uses and when to use them. ## Conventions Unless explicitly defined otherwise in the schema, ACP-defined JSON object property keys use `camelCase`. String values carried by discriminator fields use `snake_case`. The JSON-RPC envelope fields (`jsonrpc`, `id`, `method`, `params`, `result`, and `error`) follow the JSON-RPC 2.0 specification. For an optional field whose schema allows `null`, omitting it and setting it to `null` are equivalent, unless the field says otherwise. Optional fields whose schema does not allow `null`, such as most arrays and objects, are omitted rather than sent as `null`. Upsert updates are the exception: there an omitted field leaves the stored value unchanged and `null` clears it. Selected enum-like fields and tagged unions can define custom or future fallbacks. For those fields, `_`-prefixed values are reserved for implementation-specific extensions, while unknown non-underscore values are reserved for future ACP variants. ## Extensibility Implementations can extend the protocol without breaking compatibility: * Add custom data using `_meta` fields * Create custom methods by prefixing their name with underscore (`_`) * Advertise custom capabilities during initialization See [Extensibility](/protocol/v2/extensibility) for details. ## Next steps * [Security Considerations](/protocol/v2/security) covers the trust model. Read it before shipping an Agent or Client. * [Initialization](/protocol/v2/initialization) covers version and capability negotiation. * [Session Setup](/protocol/v2/session-setup) covers creating, resuming, and closing sessions. * [Prompt Lifecycle](/protocol/v2/prompt-lifecycle) covers how prompts run and how Agents report progress. * [Extensibility](/protocol/v2/extensibility) covers custom data, methods, and capabilities. * The [Test Compatibility Kit](/libraries/testing) checks an Agent implementation against the protocol. # Prompt Lifecycle Source: https://agentclientprotocol.com/protocol/v2/prompt-lifecycle How prompts, state updates, and completion fit together A prompt starts or contributes to [foreground work](#foreground-and-background-work) in a session. Foreground work can also start without a prompt, such as when the Agent follows up on a background task that finished. It reports the same states either way. The [Agent](/protocol/v2/overview#agent) may continue that work until it reports `idle`, including across multiple model exchanges and tool invocations. `session/prompt` lasts until the Agent inserts the user message into the ACP conversation. This is what acceptance means for a prompt. The response returns that message's `messageId`. The Agent reports its content and placement, foreground state, output, and completion through `session/update` notifications. Before sending prompts, Clients **MUST** first complete the [initialization](/protocol/v2/initialization) phase and [session setup](/protocol/v2/session-setup). ## Session updates Agents send `session/update` notifications to report streamed content, tool activity, and changes to session state. The `sessionUpdate` field inside `params.update` identifies the variant: | `sessionUpdate` value | Description | | - | - | | `user_message_chunk` | A streamed chunk of a user message. | | `user_message` | Creates or updates a user message identified by `messageId`. | | `agent_message_chunk` | A streamed chunk of the Agent's response. | | `agent_message` | Creates or updates an Agent message identified by `messageId`. | | `agent_thought_chunk` | A streamed chunk of the Agent's reasoning. | | `agent_thought` | Creates or updates an Agent reasoning message identified by `messageId`. | | `state_update` | A snapshot of the Agent's [foreground activity](#session-states). | | `tool_call_content_chunk` | Appends a [content chunk to a tool call](/protocol/v2/tool-calls#streaming-content). | | `tool_call_update` | Creates or updates a [tool call](/protocol/v2/tool-calls#reporting). | | `terminal_update` | Creates or updates an [Agent-owned terminal](/protocol/v2/tool-calls#display-only-terminals). | | `terminal_output_chunk` | Appends output bytes to an [Agent-owned terminal](/protocol/v2/tool-calls#display-only-terminals). | | `plan_update` | Creates or updates the [content of a plan](/protocol/v2/agent-plan) identified by ID. | | `available_commands_update` | The set of [available slash commands](/protocol/v2/slash-commands) is ready or has changed. | | `config_option_update` | The session's [configuration options](/protocol/v2/session-config-options#from-the-agent) have changed. | | `session_info_update` | [Session metadata](/protocol/v2/session-list#updating-session-metadata), such as the title or last update time, has changed. | | `usage_update` | The session's [context window usage and cumulative cost](#session-usage-updates). | | `notice` | A live [user-facing notice](#session-notices) that is not part of session history. | | `compaction_update` | Creates or updates a [context compaction](#session-compaction). | | `compaction_summary_chunk` | Appends content to a [compaction's retained summary](#session-compaction). | This is the complete set of standard variants defined in the current [`SessionUpdate` schema](/protocol/v2/schema#sessionupdate), which describes each payload in detail. The walkthrough below illustrates common uses of these updates. The protocol also supports [custom and future variants](/protocol/v2/extensibility#enum-and-tagged-union-variants). Clients that do not understand an update **SHOULD** preserve its raw payload when storing, replaying, proxying, or forwarding session history, and otherwise ignore it or display it generically. Live-only [notices](#session-notices) **SHOULD NOT** be [replayed](/protocol/v2/session-setup#replay-contents), even when preserved as unknown updates. Session updates are not limited to prompt-driven foreground work. For example, Agents may advertise commands after creating a session, and background activity may emit updates while the Agent is [idle](#session-states). ### Entity IDs Messages, tool calls, terminals, plans, and compactions are entities that the Agent creates and then updates by ID across multiple session updates. An entity is identified by its type together with its ID, not by its ID alone: | Entity type | Session updates | ID field | | - | - | - | | User message | `user_message`, `user_message_chunk` | `messageId` | | Agent message | `agent_message`, `agent_message_chunk` | `messageId` | | Agent thought | `agent_thought`, `agent_thought_chunk` | `messageId` | | Tool call | `tool_call_update`, `tool_call_content_chunk` | `toolCallId` | | Terminal | `terminal_update`, `terminal_output_chunk` | `terminalId` | | Plan | `plan_update` | `planId` | | Compaction | `compaction_update`, `compaction_summary_chunk` | `compactionId` | An ID is unique among entities of the same type within a session, not across all entity types, so the same string can identify one entity of each type. User messages, Agent messages, and Agent thoughts are separate types even though they share the `messageId` field. For example, an Agent may report a thought and a response derived from the same model output with the same `messageId`. They remain two distinct entities. The Agent **MUST NOT** reuse an ID for a different entity of the same type within a session. Clients **MUST** key entities by both type and ID. An update applies only to the entity of its own type: an `agent_thought` whose `messageId` matches an existing Agent message creates or updates a thought and leaves the message unchanged. Likewise, a field that references an entity identifies an entity of one specific type. For example, the `messageId` returned by `session/prompt` identifies a user message. An update or chunk for an ID the Client hasn't seen creates the entity with its defaults and then applies, so a chunk can arrive before any full update. Clients **MUST NOT** drop it. An entity's first update or chunk fixes its timeline position in receive order: it follows previously received timeline content and precedes content first received later. Later updates and chunks patch the entity in place without moving it, including after the session reports `idle`. Updates for different entities may interleave, and a new ID does not end any other entity. Clients that show an entity outside the timeline, such as a plan panel, may ignore its position. ## Foreground and background work **Foreground work** is the Agent's active response or workflow in the session, including model processing, tool execution, and waiting for user action needed to continue that work. The Agent **MUST** treat that work as foreground whether it was started by a user prompt or by the Agent, for example to pursue an ongoing goal, continue earlier work, or act on a completed background task. **Background activity** runs independently of the active response or workflow. A detached task continuing to run, its progress or completion updates, and session metadata updates do not by themselves start foreground work. If the Agent begins a response or workflow to act on a background result, that work is foreground work. The same lifecycle requirements apply regardless of what started foreground work: * When foreground work starts, the Agent **MUST** report `running`, or `requires_action` if the work starts blocked on user action. * While foreground work is blocked on user action, the Agent **SHOULD** report `requires_action`. Once reported, it **MUST** report `running` when foreground progress resumes. * When foreground work ends, the Agent **MUST** report `idle`, even if background activity continues, and **SHOULD** include the corresponding [stop reason](#stop-reasons). Agent-initiated work does not require a `session/prompt` request or a synthetic user message. State updates describe the session's foreground work, not individual model exchanges, tool calls, or prompt requests. For example, when a background task completes and the Agent starts a follow-up response: ```text theme={null} Agent → Client: state_update (running) Agent → Client: agent_message / tool_call_update / … Agent → Client: state_update (idle, stopReason: end_turn) ``` In contrast, if the Agent only reports a detached task's progress or completion while idle: ```text theme={null} Agent → Client: tool_call_update (in_progress) Agent → Client: tool_call_update (completed) Session remains idle; no foreground work started or ended. ``` A permission request or [elicitation](/protocol/v2/elicitation) does not by itself change the foreground state. If it blocks foreground work, the Agent **SHOULD** report `requires_action`. If it belongs only to independent background activity, the session may remain `idle`. Resolving a request does not itself imply `running`: the state changes only if foreground activity changes. See [Waiting for User Action](#waiting-for-user-action) and [Requesting Permission](/protocol/v2/tool-calls#requesting-permission). ### Background work Background work is session-owned work running independently of foreground work. It is represented by entities the Client already tracks: * **Terminals.** A process that keeps running after its tool call returns control to the model, such as a backgrounded shell or dev server, is a [terminal](/protocol/v2/tool-calls#display-only-terminals). It is live until its `terminal_update` reports `exitStatus`. While it is listed, the Agent **SHOULD** keep its output current whenever it can read the process output. Output is not a liveness signal: a Client **MUST NOT** treat a terminal as hung or exited because its output is missing or stale. * **Tool calls.** Work without a process of its own, such as a watcher, a workflow, or a scheduled wakeup, keeps reporting [status](/protocol/v2/tool-calls#status) on its tool call. `pending` and `paused` tool calls are still live. Work without a process stays on the tool call that started it. When the Agent knows that a tool call's work continues after the call returns control to the model, it **SHOULD** keep that tool call `pending`, `in_progress`, or `paused` and list it, instead of giving it a final status. Some background work has no such tool call. No tool call started it, such as a task that a hook started, or the Agent learned of the work only after its tool call reached a final status. The Agent **MAY** start a tool call of its own for such work, with a title that describes the work, and list it. It sends that tool call like any other, before the first list that names it, even while the session is `idle`. The Agent does not reopen a tool call that has a final status. It starts a new one instead. Background work is work the user can reason about: something the user or the model started, which the user may want to stop or leave to finish. The Agent **SHOULD NOT** list housekeeping it starts on its own, such as memory consolidation. If housekeeping needs to be visible, the Agent represents it as a tool call. `running`, `requires_action`, and `idle` state updates carry an optional `background` list of the work currently running independently of foreground work: ```json theme={null} { "sessionUpdate": "state_update", "state": "idle", "stopReason": "end_turn", "background": [ { "type": "terminal", "terminalId": "term_003" }, { "type": "tool_call", "toolCallId": "call_012" } ] } ``` * **It is a snapshot.** A concrete list replaces the previous one, and `[]` means no background work is running. * **Omitted or `null` means not reported**, not that nothing is running. An Agent that reports background work **MUST** include `background` on every `state_update` for the session. If a later snapshot omits it, or it is malformed, the Client treats background work as unknown until a list is reported again. * **The Agent re-sends the state when the list changes.** When background work starts or ends, the Agent **SHOULD** send a repeated `state_update` with the current state and the updated list. A repeated snapshot is not a [state transition](#state-transitions), and a repeated `idle` without a new stop reason is not a new completion. * **Items are announced before they are listed and finalized before they are removed.** The Agent **MUST** send a `terminal_update` for a terminal or a `tool_call_update` for a tool call before the first snapshot that lists it. It **MUST** send a terminal's `exitStatus` or a tool call's final status before the snapshot that removes it. * **Known follow-up work is reported with the removal.** When finished background work starts new foreground work and the Agent knows this when it removes the item, the Agent **SHOULD** report `running` in the same snapshot that removes the item, or earlier. An Agent that only learns of the follow-up later, for example because the underlying agent decides after the work ends, reports `running` when that work starts. Clients cover that gap with the grace period described below. * **Only background work is listed, and only once.** A terminal or tool call that foreground work is waiting on is foreground work and is not listed. Process-backed work is listed as its terminal, and the Agent **MUST NOT** also list a tool call whose only live work is a listed terminal. * **Unknown items still count.** An item with an unknown `type` does not invalidate the list. It still means background work is running. The Client uses the list to tell: * **Whether the session is quiet.** Nothing is running when the state is `idle` and `background` is `[]`. When the list only contains `pending` or `paused` tool calls, work is scheduled or suspended but nothing is running now. A Client that frees resources when a session becomes quiet **SHOULD** wait a short grace period after the snapshot that empties the list, since finished work may start a follow-up. * **What closing will stop**, so it can warn before [`session/close`](/protocol/v2/session-setup#closing-active-sessions). * **Which unfinished tool calls and terminals are still live.** Once the session is `idle`, a Client **MAY** treat a `pending`, `in_progress`, or `paused` tool call, or a terminal without `exitStatus`, that is not in the latest reported list as abandoned. A tool call that references a listed terminal is live. A Client **MUST NOT** treat anything as abandoned when `background` is not reported. ## Prompt lifecycle The diagram shows one possible ordering. See [Insertion and ordering](#insertion-and-ordering). ```mermaid theme={null} sequenceDiagram participant Client participant Agent Note over Agent,Client: Session ready Note left of Client: User sends message Client->>Agent: session/prompt (user message) Note right of Agent: Insert user message Agent-->>Client: "session/prompt response (messageId)" Agent->>Client: session/update (user_message) Agent->>Client: session/update (state_update: running) loop While foreground work is in progress Note right of Agent: LLM responds with
content/tool calls Agent->>Client: session/update (plan_update) Agent->>Client: session/update (agent_message) opt Tool calls requested Agent->>Client: session/update (tool_call_update) opt Permission required Agent->>Client: session/request_permission Agent->>Client: session/update (state_update: requires_action) Note left of Client: User grants/denies Client-->>Agent: Permission response Agent->>Client: session/update (state_update: running) end Agent->>Client: session/update (tool_call_update status: in_progress) Note right of Agent: Execute tool Agent->>Client: session/update (tool_call_content_chunk) Agent->>Client: session/update (tool_call_update status: completed) Note right of Agent: Send tool results
back to LLM end opt User cancelled during execution Note left of Client: User cancels work Client->>Agent: session/cancel Note right of Agent: Abort operations Agent->>Client: session/update (state_update: idle, stopReason: cancelled) end opt Work fails after insertion Note right of Agent: Stop work Agent->>Client: session/update (state_update: idle, stopReason: error) end end Agent->>Client: session/update (state_update: idle, stopReason) ``` ### 1. User message The Client sends a user message with `session/prompt`: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "session/prompt", "params": { "sessionId": "sess_abc123def456", "prompt": [ { "type": "text", "text": "Can you analyze this code for potential issues?" }, { "type": "resource", "resource": { "uri": "file:///home/user/project/main.py", "mimeType": "text/x-python", "text": "def process_data(items):\n for item in items:\n print(item)" } } ] } } ``` **sessionId** `SessionId` *required* The [ID](/protocol/v2/session-setup#session-id) of the session to send this message to. **prompt** `ContentBlock[]` *required* The contents of the user message, e.g. text, images, files, etc. Clients **MUST NOT** send an empty `prompt` array. Agents **MAY** reject one with `-32602` without inserting it. Clients **MUST** restrict types of content according to the [Prompt Capabilities](/protocol/v2/initialization#session-prompt-capabilities) established during [initialization](/protocol/v2/initialization). Agents **MUST** reject a prompt containing a content type that is neither baseline (`text`, `resource_link`) nor advertised, or that they don't understand with `-32602`, without inserting it. Custom content types need a [custom capability](/protocol/v2/extensibility#advertising-custom-capabilities), such as an entry in `capabilities.session.prompt._meta`. > [card] > > Learn more about Content > > [Open](/protocol/v2/content) ### 2. Prompt accepted **Acceptance means insertion**: the Agent has logically added a user message to the ACP conversation, with a `messageId` and a position relative to other messages. Receipt, queueing, and assigning an ID are not insertion. The Agent **MUST** respond successfully once the message is inserted, without waiting for foreground work to finish, and **MUST NOT** do so before insertion. Once inserted, it **MUST NOT** return an error response, even if failure or [request cancellation](/protocol/v2/cancellation) occurs before the response is sent. It returns the `messageId`. Subsequent work outcomes are reported as described in [Failures](#failures) and [Cancellation](#cancellation). An adapter can use a runtime's user-message echo or insertion event as evidence of insertion. For a [locally handled command](/protocol/v2/slash-commands#running-commands) that the runtime does not record, it can instead insert a live-only ACP user message. The response contains the inserted user message's agent-generated `messageId`: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "result": { "messageId": "msg_user_8f7a1" } } ``` **messageId** `MessageId` *required* The opaque ID of the inserted user message. This field is a required, non-null string. Omission and explicit `null` are invalid. The Agent **MUST** also report the inserted user message through a `user_message` update with the full `content` array or streamed `user_message_chunk` updates. All updates for that message **MUST** use the returned `messageId` and **MUST NOT** precede insertion. Clients **MUST** tolerate the updates arriving before or after the response. ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "user_message", "messageId": "msg_user_8f7a1", "content": [ { "type": "text", "text": "Can you analyze this code for potential issues?" } ] } } } ``` The Client uses the JSON-RPC response ID to identify its submission, then associates it with `(sessionId, messageId)`. If the message update arrived first, the Client reconciles with that existing message rather than creating a duplicate. Agents **MUST** assign distinct message IDs to distinct inserted submissions, even if their content is identical. Clients must not infer the association from content or arrival order. Insertion is not a promise of durable storage or model consumption. Every inserted input, including a locally handled command, is reported live, but Agents are not required to persist it or retain it for any minimum period. If the message is retained and replayed, the Agent **MUST** use the same ID. See [Resuming Sessions](/protocol/v2/session-setup#resuming-sessions). A successful prompt response is not an `idle` signal. Session work and notifications continue independently of the completed prompt request. The response has no fixed order relative to other session updates: the `user_message` acknowledgment, Agent output, and even the `idle` `state_update` that ends the resulting work may arrive before or after it. Clients **MUST NOT** infer ordering between them. If the response is lost, the submission's outcome remains uncertain: replay may omit live-only or discarded messages, and a retry can create another submission. The same insertion boundary applies when [closing the session](/protocol/v2/session-setup#closing-active-sessions) cancels a pending prompt: if closing prevents insertion, the request receives `-32800` (Request Cancelled). If the message has already been inserted, it receives a successful `messageId` response. Prompt responses need not precede the close response. #### Insertion and ordering `running` reports foreground work, not insertion. It may precede insertion, the prompt response, and user-message updates, for example while a foreground hook runs. It does not acknowledge a pending prompt's insertion. #### Prompts during active work Clients **MAY** send `session/prompt` in any state, including while foreground work is `running` or `requires_action`. The Agent either inserts the prompt right away or holds it and inserts it later. Held prompts are inserted in the order they were received. What inserting during active work means, such as steering the current turn or starting the next one, is up to the Agent. Agents **MUST NOT** reject a prompt only because foreground work is active. A held prompt's response stays pending until the prompt is inserted. The Client can withdraw it with [`$/cancel_request`](/protocol/v2/cancellation), and [`session/cancel`](#cancellation) and `session/close` answer prompts that haven't been inserted with `-32800`. Future capabilities may let Agents advertise steering or queueing behavior. #### Prompts that are never inserted If a request is rejected before insertion, including by a hook or early failure, the Agent **MUST** return a JSON-RPC error response and **MUST NOT** emit user-message updates for that submission. [Request cancellation](/protocol/v2/cancellation) before insertion uses `-32800`. The [foreground lifecycle](#foreground-and-background-work) applies independently of the request outcome: report `idle` when no foreground work remains, not merely because a prompt was rejected. A failed foreground hook can therefore require both a prompt error response and an idle update. If no foreground work started, rejection requires no state transition. ### 3. Agent reports output When foreground work starts, the Agent **MUST** report its active state. Usually this is a `state_update` notification with `state: "running"`. Work that starts blocked on user action may report `requires_action` directly. When progress resumes after a reported `requires_action`, the Agent **MUST** report `running`: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "state_update", "state": "running" } } } ``` The language model **MAY** respond with text content, tool calls, or both. The Agent reports the model's output to the Client via `session/update` notifications. This may include the Agent's plan for accomplishing the task: ```json expandable theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "plan_update", "plan": { "type": "items", "planId": "plan-1", "entries": [ { "content": "Check for syntax errors", "priority": "high", "status": "pending" }, { "content": "Identify potential type issues", "priority": "medium", "status": "pending" }, { "content": "Review error handling patterns", "priority": "medium", "status": "pending" }, { "content": "Suggest improvements", "priority": "low", "status": "pending" } ] } } } } ``` > [card] > > Learn more about Agent Plans > > [Open](/protocol/v2/agent-plan) The Agent can report the model's text response as an `agent_message` update with the full `content` array: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "agent_message", "messageId": "msg_agent_c42b9", "content": [ { "type": "text", "text": "I'll analyze your code for potential issues. Let me examine it..." } ] } } } ``` #### Message IDs The Agent **MUST** include an opaque `messageId` on message updates and message chunks. User, agent, and thought messages can each be reported either as a message update with a full `content` array or as streamed chunks. `user_message`, `agent_message`, and `agent_thought` updates are upserts keyed by `messageId`: omitted `content` leaves the existing message content unchanged (or empty for a new `messageId`), `content: null` clears it, and concrete `content` arrays replace the previous content. Chunk updates with the same `messageId` append content. A chunk for a `messageId` the Client hasn't seen creates the message with empty content, then appends to it. Clients apply message updates and chunks in the order they are received for each `messageId`: * A message update without `content` leaves the current content unchanged, so Agents can update other optional fields without resending content. * A message update with `content` replaces all content currently stored for that message, including content accumulated from earlier chunks. * A message update with `content: []` or `content: null` clears the message content. * A chunk appends its `content` to whatever content is current for that message, whether that content came from an earlier message update or earlier chunks. * A message update's top-level `_meta` patches the message's stored metadata by top-level key, even when the same update replaces `content`, as described in [Metadata Patches](/protocol/v2/extensibility#metadata-patches). A chunk's `_meta`, when present, is chunk-scoped. For example, if an Agent sends `agent_message` with `content: [A]`, then sends `agent_message_chunk` with `B`, the rendered message content is `[A, B]`. If it later sends another `agent_message` with `content: [C]`, the rendered content becomes `[C]`. The earlier full content and chunks are replaced. Subsequent chunks append to `[C]`. For streaming agent text, the Agent can use `agent_message_chunk` updates: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "agent_message_chunk", "messageId": "msg_agent_c42b9", "content": { "type": "text", "text": " Let me examine it..." } } } } ``` The Agent can report internal reasoning with the same message-update or chunk patterns. `agent_thought` updates patch fields for the same thought `messageId`. `agent_thought_chunk` updates append new content. ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "agent_thought", "messageId": "msg_thought_a12", "content": [ { "type": "text", "text": "Need to inspect the loop body before suggesting a fix." } ] } } } ``` If the model requested tool calls, these are also reported immediately: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "tool_call_update", "toolCallId": "call_001", "title": "Analyzing Python code", "kind": "other", "status": "pending" } } } ``` #### Session notices No Client capability is required in v2. Clients that do not implement `notice` may preserve it through the [unknown-update fallback](/protocol/v2/extensibility#enum-and-tagged-union-variants) and ignore it or present it generically. This does not give it replay semantics. This is [capability-free informational delivery](/protocol/v2/extensibility#experimental-features-and-negotiation), not an advertisement that the Client will display the notice. At any point while a session exists, including outside prompt processing, the Agent **MAY** send a live user-facing notice: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "notice", "severity": "warning", "title": "MCP server unavailable", "description": "Continuing without it." } } } ``` `severity` is required and non-null and initially supports `info`, `warning`, and `error`. It is an open string enum: values beginning with `_` are reserved for implementation-specific extensions, while other unknown values are reserved for future ACP severities. Clients preserve unknown values and use a generic notice presentation without inferring additional behavior from them. `title` is required, non-null, non-empty plain text suitable for a compact presentation. `description` is optional, nullable plain text with supporting detail. Omission and `null` both mean no description. `_meta` is an optional, nullable object scoped to this event. Omission and `null` both mean no event metadata. Unlike compaction patch fields, these fields do not update or clear an earlier notice. Clients **MAY** ignore them, and Agents **MUST** behave as though a notice may not have been received, displayed, or seen. A notice **MUST NOT** carry information required for protocol correctness, authorization, user action, task completion, or fatal-error reporting. Clients own presentation and dismissal. They may use a toast, banner, inline status region, notification center, or another accessible surface, and may coalesce repeated notices. Severity is only a presentation hint. Even `error` does not fail a request, stop foreground work, change session state, or imply a prompt stop reason. Dismissal is local and produces no acknowledgement or removal event. Notices have no ID or Agent-managed lifecycle. Each occurrence is an independent live event, not conversation history, and **SHOULD NOT** be included in session replay. If a condition remains relevant after reconnecting, the Agent may emit a new notice. #### Session compaction No Client capability is required in v2. Clients without compaction-specific handling may preserve, ignore, or generically display these informational updates under the [v2 negotiation rules](/protocol/v2/extensibility#experimental-features-and-negotiation). The Agent **MAY** report context compaction as one persistent, ID-addressed timeline entity. A single `compaction_update` with `status: "completed"` is sufficient. Reporting progress is optional. Summary content is also optional. It may be sent all at once in the `summary` field or streamed using `compaction_summary_chunk` for the same `compactionId`. For example, an Agent can report that compaction has started: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "compaction_update", "compactionId": "cmp_001", "status": "in_progress" } } } ``` `compactionId` and `status` are required and non-null on every `compaction_update`. The ID is an opaque, Agent-owned string, unique within the session, and **MUST NOT** be reused for another compaction. Clients initialize a first-seen compaction ID with status `in_progress` and unset optional fields, then apply the notification. As for every [entity](#entity-ids), the first notification fixes the compaction's timeline position. Later updates and chunks for other entities patch them in place. They do not move or split them around the compaction. | `status` | Meaning | | - | - | | `in_progress` | Compaction has started and has not finished. | | `completed` | Compaction finished successfully. | | `failed` | Compaction finished unsuccessfully. | | `cancelled` | Compaction was cancelled before it finished. | The Agent **MUST** report a terminal status when a reported compaction ends. `status` is an open string enum. Values beginning with `_` are reserved for implementation-specific extensions. Other unknown values are reserved for future ACP statuses. Clients preserve unknown strings and present a generic state without inferring lifecycle or control behavior. If the retained summary is available incrementally, the Agent may append one [content block](/protocol/v2/content) at a time: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "compaction_summary_chunk", "compactionId": "cmp_001", "content": { "type": "text", "text": "## Retained context\n\n" } } } } ``` `compactionId` and `content` are required and non-null on each chunk. Chunk `_meta` is optional and nullable, is scoped to that chunk, and has no patch semantics: omission and `null` both mean no chunk metadata. An update may omit `summary` to retain the streamed content. A non-streaming Agent can instead supply the complete summary, and a streaming Agent can use the same field as an authoritative replacement of content received so far: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "compaction_update", "compactionId": "cmp_001", "status": "completed", "summary": [ { "type": "text", "text": "## Retained context\n\nThe user is updating the ACP schema." } ] } } } ``` The following `compaction_update` fields are optional, nullable patches: | Field | Type | Meaning | | - | - | - | | `summary` | `ContentBlock[]` | The unencrypted, user-displayable summary content produced or retained by compaction. | | `error` | `string` | A human-readable error description. | | `_meta` | `object` | Extensible metadata for the compaction entity. | For each patch field, omission leaves the stored value unchanged, `null` clears it, and a concrete value replaces it. On a first-seen ID, omission and `null` both start with no value. `summary: []` also clears the summary. A `_meta` object patches the stored metadata by top-level key instead of replacing it. See [Metadata Patches](/protocol/v2/extensibility#metadata-patches). Clients apply updates and chunks in receive order for each ID. Chunks append to the current summary. A concrete `summary` replaces all previously accumulated content, and any subsequent chunks append to that replacement. `summary: null` or `summary: []` clears accumulated content, including partial output before failure or cancellation. The summary is not the Agent's complete replacement history or generic status text such as "Compaction completed". It **SHOULD** faithfully represent the retained, user-displayable summary without internal prompt framing or hidden instructions. Text blocks may contain Markdown. Agents **SHOULD** omit it when no unencrypted summary is available or when disclosure would reveal context that was not otherwise user-visible. Compactions are replayed like other session entities. See [Replay Contents](/protocol/v2/session-setup#replay-contents). Compaction does not instruct the Client to discard earlier conversation history. Collapsing it is a local presentation choice. It also does not replace [`usage_update`](#session-usage-updates), which reports current context-window usage and cost rather than a compaction boundary. #### Session usage updates The Agent **MAY** also report current session context and cumulative cost state with a `usage_update`: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "usage_update", "used": 53000, "size": 200000, "cost": { "amount": 0.045, "currency": "USD" } } } } ``` `used` and `size` are required and non-null token counts for the current session context. `cost` is a patch field: omitting it leaves the last reported cost unchanged, `null` clears it, and a value replaces it, including when the currency differs. A value requires `amount` and `currency`. `currency` is the unit of `amount`: an ISO 4217 currency code such as `"USD"` for money, or another unit such as `"credits"`. ### 4. Report completion When foreground work ends, the Agent **MUST** report `idle` with a `state_update` notification and **SHOULD** include the corresponding [`StopReason`](#stop-reasons): ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "state_update", "state": "idle", "stopReason": "end_turn" } } } ``` The Agent **MUST** send any pending updates for the foreground work that ended before sending its idle update. Background activity may continue to emit updates afterward. Agents **MAY** stop foreground work at any point by sending an idle `state_update` session update. They **SHOULD** include the corresponding [`StopReason`](#stop-reasons). ### 5. Tool invocation and status reporting Before proceeding with execution, the Agent **MAY** request permission from the Client via the `session/request_permission` method. While foreground work is blocked on a permission response or other user action, the Agent **SHOULD** report `requires_action`. After reporting it, the Agent **MUST** report `running` when foreground progress resumes, or `idle` if the work ends without resuming. These are aggregate state changes, not updates for each request. See [Waiting for User Action](#waiting-for-user-action). A permission request for independent background activity does not by itself change the foreground state. See [Foreground and Background Work](#foreground-and-background-work). Once permission is granted (if required), the Agent **SHOULD** invoke the tool and report a status update marking the tool as `in_progress`: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "tool_call_update", "toolCallId": "call_001", "status": "in_progress" } } } ``` As the tool runs, the Agent **MAY** send additional updates, providing real-time feedback about tool execution progress. The Agent streams incremental content items with `tool_call_content_chunk`: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "tool_call_content_chunk", "toolCallId": "call_001", "content": { "type": "content", "content": { "type": "text", "text": "Checked syntax..." } } } } } ``` Clients append each `tool_call_content_chunk` to the current content for that `toolCallId`. A later `tool_call_update` with `content` replaces the accumulated content. Display-only terminal bytes use `terminal_output_chunk`, not `tool_call_content_chunk`. See [Display-only Terminals](/protocol/v2/tool-calls#display-only-terminals) for their per-terminal byte ordering and snapshot semantics. Tools execute on the Agent. Clients may expose tools through MCP servers supplied during session setup. v2 does not define Client file-system or terminal-execution capabilities. Client interactions such as elicitation remain subject to their own negotiated capabilities. When the tool completes, the Agent sends another update with the final status and any content: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "tool_call_update", "toolCallId": "call_001", "status": "completed", "content": [ { "type": "content", "content": { "type": "text", "text": "Analysis complete:\n- No syntax errors found\n- Consider adding type hints for better clarity\n- The function could benefit from error handling for empty lists" } } ] } } } ``` > [card] > > Learn more about Tool Calls > > [Open](/protocol/v2/tool-calls) ### 6. Continue conversation The Agent sends the tool results back to the language model as another request. The cycle returns to [step 3](#3-agent-reports-output), continuing until the language model completes its response without requesting additional tool calls or foreground work is stopped by the Agent or cancelled by the Client. ## Stop reasons When an Agent stops foreground work, it **SHOULD** specify the corresponding `StopReason` on an idle `state_update` session update. If the Agent knows it is idle but cannot determine why the work stopped, it may omit the stop reason. Clients **MUST** recognize `idle` as the end of foreground work even when the stop reason is omitted, `null`, malformed, or unknown. Without a recognized stop reason, Clients cannot infer how the work ended. **end\_turn** The Agent has finished foreground work, including a locally handled command that required no model call. **max\_tokens** The maximum token limit is reached **max\_turn\_requests** The maximum number of model requests for the foreground work is exceeded **refusal** The Agent refuses to continue **cancelled** The user or Client chose to stop the work: with `session/cancel`, by closing the session, or through an interaction the Agent offers, such as a permission option that tells the Agent to stop **error** Foreground work ended because something failed. See [Failures](#failures). When the Agent stops foreground work for its own reasons, it uses the matching reason: `max_tokens` or `max_turn_requests` for limits, `refusal` for a refusal, and `error` for anything else, such as an internal timeout. `cancelled` means the user or Client chose to stop the work, not that the Agent hit a limit or failed. Custom or future stop reasons can be used when Clients can display a generic stopped state. Custom stop reasons **MUST** begin with `_`. Unknown non-underscore stop reasons are reserved for future ACP variants. ## Failures When foreground work ends because something failed, the Agent **MUST** report `idle` and **SHOULD** include the `error` stop reason. This includes pre-insertion work and failures before any model output. The prompt's response still follows the [insertion boundary](#2-prompt-accepted). This stop reason carries the failure in an `error` field beside `stopReason`, which the Agent **SHOULD** include: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "state_update", "state": "idle", "stopReason": "error", "error": { "code": -32000, "message": "Authentication required" } } } } ``` **error** `Error` The failure that ended foreground work, as a JSON-RPC error object with required `code` and `message` and optional `data`. Optional and nullable: omission and `null` both mean the Agent supplied no failure details. `error` belongs to the `error` stop reason. Beside any other stop reason it is an unknown field. Clients may show `message` to the user and can handle `code` as they would for an error response: for example, `-32000` (authentication required) can prompt the user to authenticate before sending another prompt. Before reporting the failure, the Agent **SHOULD** give each tool call that the failed work left unfinished a terminal status, using `failed` for calls that did not complete. Listed [background work](#background-work), and tool calls that reference a listed terminal, are not part of the failed work and keep running. A failure does not undo the insertion or any side effects the work already had, such as tools that ran. Sending the prompt again submits a new message. The `error` stop reason is only for failures that end foreground work: * A failure before the user message is inserted requires a JSON-RPC error response to `session/prompt`, whether or not it also ends foreground work. * A failure the Agent recovers from while work continues, such as a retried model request or a failed tool call, is reported with a [notice](#session-notices) or a tool call whose status is `failed`, and does not change the state. * Errors raised while aborting cancelled work are reported with the `cancelled` stop reason, as described in [Cancellation](#cancellation). * A failure in background activity while the Agent is `idle` is not a stop reason, since no foreground work ended. Clients detect a lost connection or an exited Agent process themselves. No update can report them. ## Session states `state_update` is a snapshot of the session's aggregate foreground activity, whether or not a prompt started it. It is not an event for an individual prompt, model call, permission request, or elicitation. **running** Foreground work is in progress. **idle** No foreground work is active. Background activity may continue. **requires\_action** Foreground work is blocked on user action. Background activity **MAY** continue and emit other `session/update` notifications while the Agent reports `idle`. These notifications do not change the state. Each state may carry a [`background`](#background-work) list of that work. Unless the Client has advertised support for a custom or future state, Agents **MUST** still report `running`, `requires_action`, and `idle` where the [state transitions](#state-transitions) require them. A Client that receives a state it doesn't recognize **MUST NOT** treat it as `idle` or present the previous state as confirmed, and shows a generic busy state until a known state arrives. ### Initial state and synchronization New sessions default to `idle` until a state update reports otherwise. State updates may arrive before or after the `session/new` response. Clients **MUST NOT** overwrite an already-reported state when the response arrives. A separate initial idle notification is optional and does not represent completion. `session/resume` does not imply `idle`. The Agent **MUST** send a snapshot of foreground state after resuming, following any requested history replay and before the successful resume response, even when no replay was requested. Clients **MUST** use that snapshot rather than infer activity from the response or replayed content. See [Current-State Synchronization](/protocol/v2/session-setup#current-state-synchronization) for ordering and pending interactions. ### State transitions The table describes live state reporting between the three standard states. Initial or resume snapshots report the current state without implying a transition. | Current state | Condition | Next report | | - | - | - | | `idle` | Foreground work starts | **MUST** report `running`, or `requires_action` if the work starts blocked | | `running` | Foreground work cannot progress without user action | **SHOULD** report `requires_action` | | `requires_action` | Foreground progress resumes | **MUST** report `running` | | `running` or `requires_action` | All foreground activity ends | **MUST** report `idle` | | Any | Only independent background activity or an unrelated request changes | Unchanged | | Any | The current state is reported again | Unchanged (idempotent snapshot) | `requires_action` is only for blocked foreground work. An outstanding request alone does not justify it, but foreground work that starts blocked may report it directly without an artificial `running` first. Agents **MAY** repeat current-state snapshots. Clients **MUST** apply them idempotently: repeats do not start new work, end additional work, or add usage again. Repeated or resume idle snapshots may carry the last stop reason for context, without creating a new completion or cancellation. A repeated state may carry updated information. Applying that information does not constitute another state transition. When an idle transition ends work, the Agent **SHOULD** include its stop reason, and **MUST** use `cancelled` when confirming foreground cancellation. ### Waiting for user action `requires_action` means the foreground workflow as a whole is blocked on user action. The session remains `running` if other foreground work can still progress, even if some permission requests or elicitations are pending. Clients present those requests independently of the aggregate state. With several outstanding requests, opening or resolving a request does not itself cause a transition. Once `requires_action` is reported, the Agent **MUST** report `running` when progress resumes, even if other requests remain outstanding, or `idle` if the work ends without resuming. While still blocked, answering one request does not imply `running`. Declining or cancelling a request may lead to resumed work, a fallback, or completion. Agents **SHOULD** ignore responses for work that has already ended rather than use them to resume that work. ### Work boundaries and local commands When no foreground activity remains, the Agent **MUST** report `idle`. If another foreground interval then begins, it reports an active state again, even when the next interval starts immediately. Consecutive completed turns therefore have an idle boundary, not a continuous `running` state. Completing an individual prompt, command, or tool call while other foreground activity continues does not require an idle boundary. For prompts sent while work is active, see [Prompts During Active Work](#prompts-during-active-work). Handling an accepted prompt, including a local slash command that performs no model work, **MUST** use the foreground lifecycle. A local command handled from idle with no user-action wait uses `running` → `idle` and **SHOULD** use `end_turn` for successful completion. Neither the prompt response nor output notifications substitute for state updates. Foreground work may precede insertion. See [Insertion and ordering](#insertion-and-ordering). ### Lifecycle examples These examples illustrate the lifecycle. Blocked-state examples assume the Agent follows the recommendation to report `requires_action`. Start, resume-from-blocked, and completion updates are required. Normal completion stop reasons are recommended, and the cancellation stop reason is required. The same rules apply to permissions and both elicitation modes. In URL mode, an `accept` response leaves `requires_action` unchanged while the user still needs to finish the external interaction. Late answers may arrive after work ends, including during a later foreground workflow. An idle snapshot on resume may carry a previous stop reason without creating another completion. | Scenario | Expected trace or invariant | | - | - | | New session | Default `idle` unless a state update reports otherwise. The response does not overwrite an already-reported state | | Resume with running foreground work | Replay, if requested → current `running` snapshot → resume response. The snapshot reports activity after resuming | | Resume during blocked work | Current `requires_action` snapshot → resume response | | Foreground work starts blocked | `requires_action` → `running` when progress resumes → `idle` when work ends. No preliminary `running` required | | Two completed turns | `running` → `idle(end_turn)` → `running` → `idle(end_turn)` | | Local command from idle | Prompt insertion → `running` → local handling → `idle(end_turn)`, even without a model call | | Background permission or elicitation while idle | Request and response. State remains `idle` unless foreground work actually starts | | Two requests block all foreground work | `running` → `requires_action`. Answering one leaves `requires_action` if still blocked. Report `running` only when progress resumes | | A pending request while other foreground work progresses | Remain `running` and display the request independently | | A local command finishes while other foreground work continues | Remain active with no idle boundary for the individual command | | Cancellation while blocked | `requires_action` → cancellation cleanup → `idle(cancelled)`. After completion, late answers should not resume that work | | Repeated snapshot | `running, running` or `idle, idle` has one logical state, not two work intervals or completions | | Same state with updated information | Apply the updated information without another state transition or completion | | Resume idle with an old `cancelled` stop reason | Synchronize idle without cancelling a newer URL interaction or creating another cancellation event | | Cancellation while idle | No additional completion update is required | ## Cancellation Clients **MAY** cancel the session's foreground work at any time by sending a `session/cancel` notification: ```json theme={null} { "jsonrpc": "2.0", "method": "session/cancel", "params": { "sessionId": "sess_abc123def456" } } ``` `session/cancel` covers foreground work and prompts received before it that the Agent has not yet inserted. The Agent **MUST** answer the covered prompts with `-32800`, as described in [request cancellation](/protocol/v2/cancellation). A `session/prompt` received after `session/cancel` is not cancelled by it. Once a message is inserted, its prompt request still succeeds with its `messageId`. Cancellation does not undo that insertion. Work in the latest [`background`](#background-work) list is not covered and keeps running. The Agent **MAY** stop background activity it does not list. The Client **SHOULD** preemptively mark all non-finished tool calls pertaining to the current active work as `cancelled` as soon as it sends the `session/cancel` notification. It **SHOULD** skip tool calls in the latest `background` list and tool calls that reference a listed terminal. This mark is a local display hint: the Agent gives those tool calls their [final status](/protocol/v2/tool-calls#status), and its updates replace the mark. When the Agent stops the cancelled foreground work, it **MUST** stop waiting for that work's pending `session/request_permission` requests and treat them as not approved. It **SHOULD** cancel each of them with [`$/cancel_request`](/protocol/v2/cancellation) so the Client can dismiss the prompt. The Client **MAY** answer a request it knows belongs to the cancelled work with the `cancelled` outcome without waiting for `$/cancel_request`. Permission requests for work in the latest `background` list are not affected. For elicitation requests, see [Elicitation Cancellation](/protocol/v2/elicitation#session-cancellation). When the Agent receives this notification, it **SHOULD** stop all language model requests and all tool call invocations of the cancelled foreground work as soon as possible. A response can race with `session/cancel` before cancellation completes. After cancellation completes, the Agent **SHOULD** ignore late responses or external URL completions rather than use them to resume the cancelled work. After all ongoing operations have been successfully aborted and pending updates have been sent, the Agent **MUST** send an idle `state_update` session update with the `cancelled` [stop reason](#stop-reasons) if foreground work was active when cancellation took effect. Cancellation can finish without receiving answers to abandoned user-action requests. If no foreground work was active when cancellation took effect, no additional completion update is required. > [!WARNING] > > API client libraries and tools often throw an exception when their operation is aborted, which may otherwise be surfaced as a generic failure. > > Clients often display unrecognized errors from the Agent to the user, which would be undesirable for cancellations as they aren't considered errors. > > Agents **MUST** catch these errors and report the semantically meaningful `cancelled` stop reason, not `error`, on a `state_update` notification, so that Clients can reliably confirm the cancellation. The Agent **MAY** send `session/update` notifications with content or tool call updates after receiving the `session/cancel` notification, but it **MUST** ensure that it does so before sending the idle `state_update` session update that reports cancellation. The Client **SHOULD** still accept tool call updates received after sending `session/cancel`. # Schema Source: https://agentclientprotocol.com/protocol/v2/schema Schema definitions for the Agent Client Protocol > [!NOTE] > > This schema file is generated in this repository at > [`schema/v2/schema.json`](https://github.com/agentclientprotocol/agent-client-protocol/blob/main/schema/v2/schema.json). > GitHub releases for this schema are not published yet. ## Agent Defines the interface that all ACP-compliant agents must implement. Agents are programs that use generative AI to autonomously modify code. They handle requests from clients and execute tasks using language models and tools. ### auth/login Authenticates the client using the specified authentication method. Agents MUST support this method when their `initialize` response included a non-empty `authMethods` list. Clients MUST call this method only with a method whose type defines a protocol-driven login flow, and MUST NOT call it when `authMethods` was omitted or empty. Called when the agent requires authentication before allowing session creation. The client provides the authentication method ID that was advertised during initialization. After successful authentication, the client can proceed to create sessions with `session/new` without receiving an `auth_required` (`-32000`) error. See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/v2/initialization) #### LoginAuthRequest Request parameters for the `auth/login` method. Specifies which authentication method to use. Agents MUST support this method when their `initialize` response included a non-empty `authMethods` list. Clients MUST NOT call this method when `authMethods` was omitted or empty. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **methodId** `[AuthMethodId](#authmethodid)` *required* The ID of the authentication method to use. Must be one of the methods advertised in the initialize response. #### LoginAuthResponse Response to the `auth/login` method. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ### auth/logout Logs out of the current authenticated state. Agents MUST support this method when their `initialize` response included a non-empty `authMethods` list. Clients MUST NOT call this method when `authMethods` was omitted or empty. After a successful logout, authentication-gated requests require the client to complete an advertised authentication flow again. There is no guarantee about the behavior of already running sessions. #### LogoutAuthRequest Request parameters for the `auth/logout` method. Terminates the current authenticated session. Agents MUST support this method when their `initialize` response included a non-empty `authMethods` list. Clients MUST NOT call this method when `authMethods` was omitted or empty. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) #### LogoutAuthResponse Response to the `auth/logout` method. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ### initialize Establishes the connection with a client and negotiates protocol capabilities. This method is called at the beginning of the connection, before any other request, to: * Negotiate the protocol version to use * Exchange capability information between client and agent * Determine available authentication methods The Client may repeat it before its first other request. The latest successful `initialize` is authoritative. The agent should respond with its supported protocol version and capabilities. See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/v2/initialization) #### InitializeRequest Request parameters for the initialize method. Sent by the client to establish connection and negotiate capabilities. See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/v2/initialization) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **capabilities** `[ClientCapabilities](#clientcapabilities)` Capabilities supported by the client. * Default: `{}` **info** `[Implementation](#implementation)` *required* Information about the implementation sending this initialize request. **protocolVersion** `[ProtocolVersion](#protocolversion)` *required* The latest protocol version supported by the client. #### InitializeResponse Response to the `initialize` method. Contains the negotiated protocol version and agent capabilities. See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/v2/initialization) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **authMethods** `[AuthMethod\[\]](#authmethod)` Authentication methods supported by the agent. Optional. Omitted or empty means the agent does not advertise the `auth/login` and `auth/logout` methods. Supplying one or more methods means the agent MUST support both `auth/login` and `auth/logout`. **capabilities** `[AgentCapabilities](#agentcapabilities)` Capabilities supported by the agent. * Default: `{}` **info** `[Implementation](#implementation)` *required* Information about the implementation sending this initialize response. **protocolVersion** `[ProtocolVersion](#protocolversion)` *required* The highest protocol version supported by the agent that is at or below the version requested by the client. If no such version exists, initialization fails with error code -32022. The client must check that it supports this version and should disconnect if it does not. ### session/cancel Cancels a session's foreground work and its prompts not yet inserted. Work in the latest `background` list is not covered and keeps running. The Agent MAY stop background activity it does not list. Upon receiving this notification, the Agent SHOULD stop all language model requests and all tool call invocations of the cancelled foreground work as soon as possible. The Agent MUST stop waiting for pending `session/request_permission` requests of the cancelled work and treat them as not approved. It SHOULD cancel each of them with `$/cancel_request`. After all ongoing operations have been successfully aborted and pending updates have been sent, the Agent MUST send an idle `state_update` session update with the `cancelled` stop reason if cancellation ended active foreground work. No additional completion update is required if no foreground work was active. After cancellation completes, the Agent SHOULD ignore late answers rather than use them to resume the cancelled work. Agents MUST catch errors caused by aborting cancelled work and report the `cancelled` stop reason, not `error`. The Agent MAY send content or tool call updates after receiving `session/cancel`, but MUST send them before the idle `state_update` that reports cancellation. See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#cancellation) #### CancelSessionNotification Notification to cancel a session's foreground work and its prompts not yet inserted. See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#cancellation) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **sessionId** `[SessionId](#sessionid)` *required* The ID of the session whose foreground work to cancel. ### session/close Closes an active session and frees up any resources associated with it. The Agent MUST cancel any ongoing work as if `session/cancel` was called, stop the session's background work, and then free the resources associated with the session. #### CloseSessionRequest Request parameters for closing an active session. The Agent MUST cancel any ongoing work related to the session as if `session/cancel` was called, then free the resources associated with the session. Unlike `session/cancel`, closing also stops the session's background work. After the close response, the Agent sends no other messages for the session on that connection. Closing a session that does not exist or is not active SHOULD succeed, and Clients SHOULD treat a `-32002` response as a successful close. When closing cancels active foreground work, the Agent MUST send the final updates for that work and the idle `state_update` with `stopReason: "cancelled"` before responding successfully to `session/close`. Closing an idle session does not itself require another idle update. Closing also cancels pending `session/prompt` requests whose messages have not been inserted, including held prompts. If closing prevents a prompt's user message from being inserted, the Agent MUST answer that request with `-32800` (Request Cancelled). If the message has already been inserted, the Agent MUST respond successfully with its `messageId`. Prompt responses need not precede the close response. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **sessionId** `[SessionId](#sessionid)` *required* The ID of the session to close. #### CloseSessionResponse Response from closing a session. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ### session/delete Deletes an existing session from `session/list`. This method is only available if the agent advertises the `session.delete` capability. #### DeleteSessionRequest Request parameters for deleting an existing session from `session/list`. Only available if the Agent supports the `session.delete` capability. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **sessionId** `[SessionId](#sessionid)` *required* The ID of the session to delete. #### DeleteSessionResponse Response from deleting a session. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ### session/list Lists existing sessions known to the agent. The agent should return metadata about sessions with optional filtering and pagination support. #### ListSessionsRequest Request parameters for listing existing sessions. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **cursor** `[SessionListCursor](#sessionlistcursor) | null` Opaque cursor token from a previous response's nextCursor field for cursor-based pagination Omitted and `null` are equivalent and mean the first page is requested. **cwd** `[AbsolutePath](#absolutepath) | null` Filter sessions by working directory. Must be an absolute path. Only sessions whose `cwd` is this same directory match. Subdirectories and `additionalDirectories` don't. Agents MAY normalize paths when comparing. Omitted and `null` are equivalent and mean sessions are not filtered by working directory. #### ListSessionsResponse Response from listing sessions. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **nextCursor** `[SessionListCursor](#sessionlistcursor) | null` Opaque cursor token. If present, pass this in the next request's cursor parameter to fetch the next page. Omitted and `null` are equivalent and mean there are no more results. An empty string is a valid cursor, not the end of results. **sessions** `[SessionInfo\[\]](#sessioninfo)` *required* Array of session information objects. ### session/new Creates a new conversation session with the agent. Sessions represent independent conversation contexts with their own history and state. The agent should: * Create a new session context * Connect to any specified MCP servers * Return a unique session ID for future requests May return an `auth_required` (`-32000`) error if the agent requires authentication. See protocol docs: [Session Setup](https://agentclientprotocol.com/protocol/v2/session-setup) #### NewSessionRequest Request parameters for creating a new session. See protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/v2/session-setup#creating-a-session) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **additionalDirectories** `[AbsolutePath\[\]](#absolutepath)` Additional workspace roots for this session. Each path must be absolute. These expand the session's workspace scope without changing `cwd`, which remains the base for relative paths. When omitted or empty, no additional roots are activated for the new session. **cwd** `[AbsolutePath](#absolutepath)` *required* The working directory for this session. Must be an absolute path. **mcpServers** `[McpServer\[\]](#mcpserver)` List of MCP (Model Context Protocol) servers the agent should connect to. **systemPrompt** `[SystemPrompt](#systemprompt) | null` System-level instructions for the new session. Optional. Omitted and `null` are equivalent and mean the Agent uses its own default instructions. Clients MUST only send this when the Agent advertises `session.systemPrompt`. #### NewSessionResponse Response from creating a new session. New sessions default to `idle` until a state update reports otherwise. Updates may arrive before or after this response. Clients MUST NOT overwrite an already-reported state when the response arrives. See protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/v2/session-setup#creating-a-session) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **availableCommands** `[AvailableCommand\[\]](#availablecommand)` Initial commands the agent can execute in this session. Optional. Omitted or empty means no initial commands are advertised. Senders MUST use an array, not `null`. Receivers treat `null` like omission. Later `available_commands_update` notifications replace this list. **configOptions** `[SessionConfigOption\[\]](#sessionconfigoption)` Initial session configuration options. Optional. Omitted or empty means no config options are advertised. Senders MUST use an array, not `null`. Receivers treat `null` like omission. Later `config_option_update` notifications replace this list. **sessionId** `[SessionId](#sessionid)` *required* Unique identifier for the created session. Used in all subsequent requests for this conversation. ### session/prompt Processes a user prompt within a session. Acceptance means adding a logical user message with an ID and a position relative to other messages in the ACP conversation, not receipt or queueing. The Agent MUST return the inserted message's ID without waiting for processing to finish. The Agent reports the user message with the same ID through `session/update`. This notification may arrive before or after the response, but neither may precede insertion. Processing state, output, tool calls, and completion are also reported through session updates. An error response means the user message was not inserted. Once it is inserted, the Agent MUST NOT answer with an error, even if the work fails before the response is sent. It ends that work with the `error` stop reason. A rejected submission produces no user-message updates. Foreground state follows its normal lifecycle independently of the request outcome: `running` may precede insertion, and rejection alone does not imply `idle`. See protocol docs: [Prompt Lifecycle](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle) #### PromptRequest Request parameters for sending a user prompt to the agent. Contains the user's message and any additional context. See protocol docs: [User Message](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#1-user-message) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **prompt** `[ContentBlock\[\]](#contentblock)` *required* The blocks of content that compose the user's message. As a baseline, the Agent MUST support `text` and `resource_link` content blocks, while other variants are optionally enabled via `PromptCapabilities`. The Client MUST adapt its interface according to `PromptCapabilities`. The client MAY include referenced pieces of context as either `resource` or `resource_link` content blocks. When available, `resource` is preferred as it avoids extra round-trips and allows the message to include pieces of context from sources the agent may not have access to. Clients MUST NOT send an empty array. Agents MAY reject one with `-32602` without inserting it. **sessionId** `[SessionId](#sessionid)` *required* The ID of the session to send this user message to #### PromptResponse Response acknowledging that a user prompt was inserted into the ACP conversation. This response does not indicate that the prompt was merely received or held, nor that the agent has finished processing it. Processing and completion are reported through `state_update` session updates. Insertion is the logical addition of a user message with a message ID and a position relative to other messages in the ACP conversation. See protocol docs: [Prompt Accepted](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#2-prompt-accepted) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **messageId** `[MessageId](#messageid)` *required* Identifies the user message inserted into the ACP conversation. Required and non-null. Omission and explicit `null` are both invalid. The corresponding user-message session update carries this same identifier and may arrive before or after this response. Agents must echo the message during the live session, but are not required to retain it. If retained and replayed, the message keeps this identifier. ### session/resume Resumes an existing session. The agent should resume the session context, allowing the conversation to continue. If `replayFrom` is set, the agent should replay retained conversation history before responding. #### ResumeSessionRequest Request parameters for resuming an existing session. Resumes an existing session and optionally replays retained conversation history according to `replayFrom`. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **additionalDirectories** `[AbsolutePath\[\]](#absolutepath)` Additional workspace roots to activate for this session. Each path must be absolute. When omitted or empty, no additional roots are activated. When non-empty, this is the complete resulting additional-root list for the resumed session. It may differ from any previously used or reported list as long as the request `cwd` matches the session's `cwd`. **cwd** `[AbsolutePath](#absolutepath)` *required* The working directory for this session. Must be an absolute path. Clients MUST send the session's working directory. Agents MAY reject a different directory with `-32602`, and MAY normalize paths when comparing. **mcpServers** `[McpServer\[\]](#mcpserver)` List of MCP servers to connect to for this session. The complete set of Client-provided servers. Omitted and `[]` mean none. Agents SHOULD NOT restore servers from earlier requests. **replayFrom** `[ReplayFrom](#replayfrom) | null` Inclusive cursor describing where conversation replay should begin. Optional. Omitted and `null` are equivalent and mean the Agent should resume without replaying previous conversation history. Replay cursors are inclusive: replay includes the position identified by the cursor. Supplying `\{ "type": "start" \}` means the Agent should replay all retained conversation history before responding. Agents MUST reject unsupported cursor types or malformed cursor values with `-32602` (Invalid params), rather than substituting another cursor or resuming without replay. **sessionId** `[SessionId](#sessionid)` *required* The ID of the session to resume. **systemPrompt** `[SystemPrompt](#systemprompt) | null` System-level instructions for the resumed session. Optional. Omitted and `null` are equivalent. The Agent may then keep a system prompt it stored with the session or use its default instructions. Clients MUST only send this when the Agent advertises `session.systemPrompt`, and SHOULD send the same value they used when the session was created. #### ResumeSessionResponse Response from resuming an existing session. The agent MUST send a current `state_update` after any requested history replay and before this response, even without replay. The update reports foreground state after resuming. The response alone does not imply `idle`. See protocol docs: [Current-State Synchronization](https://agentclientprotocol.com/protocol/v2/session-setup#current-state-synchronization) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **availableCommands** `[AvailableCommand\[\]](#availablecommand)` Initial commands the agent can execute in this session. Optional. Omitted or empty means no initial commands are advertised. Senders MUST use an array, not `null`. Receivers treat `null` like omission. Later `available_commands_update` notifications replace this list. **configOptions** `[SessionConfigOption\[\]](#sessionconfigoption)` Initial session configuration options. Optional. Omitted or empty means no config options are advertised. Senders MUST use an array, not `null`. Receivers treat `null` like omission. Later `config_option_update` notifications replace this list. ### session/set\_config\_option Sets the current value for a session configuration option. #### SetSessionConfigOptionRequest Request parameters for setting a session configuration option. Agents MUST support this method for any session where they advertise config options. Agents MUST reject an unknown `configId` or invalid value with `-32602` and leave the configuration unchanged. See protocol docs: [Session Config Options](https://agentclientprotocol.com/protocol/v2/session-config-options#setting-a-config-option) **Type:** Union **Shared properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **configId** `[SessionConfigId](#sessionconfigid)` *required* The ID of the configuration option to set. **sessionId** `[SessionId](#sessionid)` *required* The ID of the session to set the configuration option for. **Variants:** **id** `object` A `SessionConfigValueId` string value (`type: "id"`). **Properties** **type** `string` *required* The discriminator value. Must be `"id"`. **value** `[SessionConfigValueId](#sessionconfigvalueid)` *required* The value ID. **boolean** `object` A boolean value (`type: "boolean"`). **Properties** **type** `string` *required* The discriminator value. Must be `"boolean"`. **value** `boolean` *required* The boolean value. **other** `object` Custom or future session configuration option value payload. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Agents MUST reject a `session/set_config_option` request with a value type they do not support with `-32602`. **Properties** **type** `string` *required* Custom or future session configuration option value type. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. **value** `any` *required* Raw value payload for the custom or future value type. #### SetSessionConfigOptionResponse Response to `session/set_config_option` method. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **configOptions** `[SessionConfigOption\[\]](#sessionconfigoption)` *required* The full set of configuration options and their current values. ### terminal/cancel Stops one terminal's process without cancelling the rest of the session's work. This method is only available while the terminal advertises `capabilities.cancel`. The response means the Agent accepted the cancellation. A `terminal_update` with `exitStatus` confirms it. #### CancelTerminalRequest Request parameters for cancelling one terminal. Clients MUST NOT send it unless the terminal currently advertises `capabilities.cancel`. The Agent responds once it has accepted the cancellation. The response does not mean the work has stopped. The Agent confirms it with a `terminal_update` that sets `exitStatus`. Cancelling stops the process but does not release the terminal, and does not change the status of a tool call that references it. The Agent responds with `-32602` if the terminal is unknown, has already exited, or is not cancellable. Cancelling a terminal does not change the foreground state by itself. See protocol docs: [Cancelling Terminals](https://agentclientprotocol.com/protocol/v2/tool-calls#cancelling-terminals) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **sessionId** `[SessionId](#sessionid)` *required* The ID of the session that owns the terminal. **terminalId** `[TerminalId](#terminalid)` *required* The ID of the terminal to cancel. #### CancelTerminalResponse Response from cancelling a terminal. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ### tool\_call/cancel Cancels one tool call without cancelling the rest of the session's work. This method is only available while the tool call advertises `capabilities.cancel`. The response means the Agent accepted the cancellation. A final `tool_call_update` confirms it. #### CancelToolCallRequest Request parameters for cancelling one tool call. Clients MUST NOT send it unless the tool call currently advertises `capabilities.cancel`. The Agent responds once it has accepted the cancellation. The response does not mean the work has stopped. The Agent confirms it with a `tool_call_update` to a final status: normally `cancelled`, or `completed` or `failed` if the work finished first. The Agent responds with `-32602` if the tool call is unknown, already final, or not cancellable. Cancelling a tool call does not change the foreground state by itself. See protocol docs: [Cancelling Tool Calls](https://agentclientprotocol.com/protocol/v2/tool-calls#cancelling-tool-calls) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **sessionId** `[SessionId](#sessionid)` *required* The ID of the session that owns the tool call. **toolCallId** `[ToolCallId](#toolcallid)` *required* The ID of the tool call to cancel. #### CancelToolCallResponse Response from cancelling a tool call. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ## Client Defines the interface that ACP-compliant clients must implement. Clients are typically code editors (IDEs, text editors) that provide the interface between users and AI agents. They manage the environment, handle user interactions, and control access to resources. ### elicitation/complete Notification that a URL-based elicitation has completed. See protocol docs: [Elicitation](https://agentclientprotocol.com/protocol/v2/elicitation#url-completion) #### CompleteElicitationNotification Notification sent by the agent when a URL-based elicitation is complete. This notification is not a foreground state update. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **elicitationId** `[ElicitationId](#elicitationid)` *required* The ID of the elicitation that completed. ### elicitation/create Requests structured user input via a form or URL. See protocol docs: [Elicitation](https://agentclientprotocol.com/protocol/v2/elicitation) #### CreateElicitationRequest Request from the agent to elicit structured user input. The agent sends this to the client to request information from the user, either via a form or by directing them to a URL. Elicitations are tied to a session (optionally a tool call) or a request. A session-scoped request follows the aggregate foreground-state contract: agents SHOULD report `requires_action` when the whole foreground workflow is blocked on user action. Once reported, they MUST report `running` when progress resumes, or `idle` if work ends without resuming. Independent background requests and request-scoped elicitations do not themselves change session state. Accepting a URL does not mean the external interaction completed. Agents SHOULD cancel pending elicitations no longer needed by cancelled work. The request's scope alone does not establish that dependency. See protocol docs: [Elicitation](https://agentclientprotocol.com/protocol/v2/elicitation) **Type:** Union **Shared properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **message** `string` *required* A human-readable message describing what input is needed. **Variants:** **form** `object` Form-based elicitation where the client renders a form from the provided schema. **Properties** **mode** `string` *required* The discriminator value. Must be `"form"`. **requestedSchema** `[ElicitationSchema](#elicitationschema)` *required* A JSON Schema describing the form fields to present to the user. **Alternatives (`oneOf`):** **Session** Tied to a session, optionally to a specific tool call within that session. **Properties** **sessionId** `[SessionId](#sessionid)` *required* The session this elicitation is tied to. **toolCallId** `[ToolCallId](#toolcallid) | null` Optional tool call within the session. Optional. Omitted and `null` are equivalent and mean the elicitation is scoped to the session without a specific tool call. **Request** Tied to a specific JSON-RPC request outside of a session (e.g., during auth/configuration phases before any session is started). **Properties** **requestId** `[RequestId](#requestid)` *required* The pending Client-to-Agent request this elicitation is tied to. **url** `object` URL-based elicitation where the client directs the user to a URL. **Properties** **elicitationId** `[ElicitationId](#elicitationid)` *required* The unique identifier for this elicitation. **mode** `string` *required* The discriminator value. Must be `"url"`. **url** `string` *required* The URL to direct the user to. * Format: `uri` **Alternatives (`oneOf`):** **Session** Tied to a session, optionally to a specific tool call within that session. **Properties** **sessionId** `[SessionId](#sessionid)` *required* The session this elicitation is tied to. **toolCallId** `[ToolCallId](#toolcallid) | null` Optional tool call within the session. Optional. Omitted and `null` are equivalent and mean the elicitation is scoped to the session without a specific tool call. **Request** Tied to a specific JSON-RPC request outside of a session (e.g., during auth/configuration phases before any session is started). **Properties** **requestId** `[RequestId](#requestid)` *required* The pending Client-to-Agent request this elicitation is tied to. **other** `object` Custom or future elicitation mode. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Clients that do not understand this mode should preserve the raw payload when storing, replaying, proxying, or forwarding elicitation requests. They MUST NOT render it as a known elicitation mode. **Properties** **mode** `string` *required* Custom or future elicitation mode. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. **Alternatives (`oneOf`):** **Session** Tied to a session, optionally to a specific tool call within that session. **Properties** **sessionId** `[SessionId](#sessionid)` *required* The session this elicitation is tied to. **toolCallId** `[ToolCallId](#toolcallid) | null` Optional tool call within the session. Optional. Omitted and `null` are equivalent and mean the elicitation is scoped to the session without a specific tool call. **Request** Tied to a specific JSON-RPC request outside of a session (e.g., during auth/configuration phases before any session is started). **Properties** **requestId** `[RequestId](#requestid)` *required* The pending Client-to-Agent request this elicitation is tied to. #### CreateElicitationResponse Response from the client to an elicitation request. **Type:** Union **Shared properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **Variants:** **accept** `object` The user accepted and provided content. **Properties** **action** `string` *required* The discriminator value. Must be `"accept"`. **content** `object | null` The user-provided content, if any, as an object matching the requested schema. Omitted and `null` are equivalent and mean no content is provided. **decline** `object` The user declined the elicitation. **Properties** **action** `string` *required* The discriminator value. Must be `"decline"`. **cancel** `object` The elicitation was cancelled. **Properties** **action** `string` *required* The discriminator value. Must be `"cancel"`. **other** `object` Custom or future elicitation action. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Agents that do not understand this action should preserve the raw payload when storing, replaying, proxying, or forwarding elicitation responses, and otherwise MUST handle it as `cancel`. **Properties** **action** `string` *required* Custom or future elicitation action. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ### session/request\_permission Requests permission from the user for an operation. Called by the agent when it needs user authorization before executing a potentially sensitive operation. The client should present the options to the user and return their decision. After `session/cancel`, the agent stops waiting for requests of the cancelled foreground work and SHOULD cancel them with `$/cancel_request`. The client answers a cancelled request with the `cancelled` outcome. See protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/v2/tool-calls#requesting-permission) #### RequestPermissionRequest Request for user permission to proceed with an operation. Sent when the agent needs authorization before performing a sensitive operation. See protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/v2/tool-calls#requesting-permission) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **description** `string | null` Optional human-readable explanation of why permission is needed. This text is specific to the permission prompt and does not update any subject's displayed content. Omitted and `null` are equivalent and mean no separate permission description was provided. **options** `[PermissionOption\[\]](#permissionoption)` *required* Available permission options for the user to choose from. Must contain at least one option. **sessionId** `[SessionId](#sessionid)` *required* The session ID for this request. **subject** `[RequestPermissionSubject](#requestpermissionsubject) | null` Optional structured context about the operation requiring permission. Omitted and `null` are equivalent and mean no structured subject was provided. **title** `string` *required* Human-readable title for the permission prompt. This title is specific to the permission prompt and does not update any subject's displayed title. #### RequestPermissionResponse Response to a permission request. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **outcome** `[RequestPermissionOutcome](#requestpermissionoutcome)` *required* The user's decision on the permission request. ### session/update Handles session update notifications from the agent. This is a notification endpoint (no response expected) that receives updates about session activity, including message updates, message chunks, tool calls, and execution plans. Note: Clients SHOULD continue accepting tool call updates even after sending a `session/cancel` notification, as the agent may send final updates before reporting an idle `state_update` with the cancelled stop reason. See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#3-agent-reports-output) #### UpdateSessionNotification Notification containing a session update from the agent. Agents can send session updates at any point while the session exists. See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#3-agent-reports-output) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **sessionId** `[SessionId](#sessionid)` *required* The ID of the session this update pertains to. **update** `[SessionUpdate](#sessionupdate)` *required* The actual update content. ## Protocol Level Defines the interface that ACP-compliant agents and clients must both implement. Notifications whose methods start with '$/' are messages which are protocol implementation dependent and might not be implementable in all clients or agents. For example if the implementation uses a single threaded synchronous programming language then there is little it can do to react to a `$/cancel\_request\` notification. If an agent or client receives notifications starting with '\$/' it is free to ignore the notification. ### \$/cancel\_request Cancels an ongoing request. This is a notification sent by the side that sent a request to cancel that request. Upon receiving this notification, the receiver: 1. MAY cancel the corresponding request activity and all nested activities 2. MAY send any pending notifications. 3. MUST still send a response for the original request. If the request already finished or is not cancelled, that is its normal response. If it is cancelled, it is either the method's defined cancellation result (for example an inserted `session/prompt`, or a `cancelled` permission outcome) or an error with code `-32800` (Request Cancelled). Receivers MUST ignore this notification for an unknown or already-answered request ID, and MUST NOT send a second response for it. See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/cancellation) #### CancelRequestNotification Notification to cancel an ongoing request. See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/cancellation) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **requestId** `[RequestId](#requestid)` *required* The ID of the request to cancel: a request that the sender of this notification issued. Receivers match it only against requests they received from that sender. ## AbsolutePath An absolute filesystem path used by the protocol. Uses the native syntax of the machine the Agent runs on, such as `/home/user/project`, `C:\Users\user\project`, or `\\server\share\project`. It is not a URI. **Type:** `string` ## AgentAuthCapabilities Authentication-related extension capabilities supported by the agent. This object does not advertise support for `auth/login` or `auth/logout`. Those methods are advertised by a non-empty `authMethods` list in the `initialize` response. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ## AgentCapabilities Capabilities supported by the agent. Advertised during initialization to inform the client about available features and content types. See protocol docs: [Agent Capabilities](https://agentclientprotocol.com/protocol/v2/initialization#agent-capabilities) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **auth** `[AgentAuthCapabilities](#agentauthcapabilities) | null` Authentication-related extension capabilities supported by the agent. Optional. Omitted and `null` are equivalent and mean the agent does not advertise any authentication-related extensions. This field does not advertise support for `auth/login` or `auth/logout`. Those methods are advertised by a non-empty `authMethods` list in the `initialize` response. **session** `[SessionCapabilities](#sessioncapabilities) | null` Session capabilities supported by the agent. Optional. Omitted and `null` are equivalent and mean the agent does not support the `session/*` methods. Supplying `\{\}` means the agent supports the baseline session methods: `session/new`, `session/list`, `session/resume`, `session/close`, `session/prompt`, `session/cancel`, and `session/update`. ## AgentMessage An agent message upsert. Only `messageId` is required. `content` has patch semantics: an omitted field leaves existing message content unchanged, `null` clears the value, and a concrete array replaces the previous value. For a new `messageId`, omitted `content` starts empty. `content` is replaced as a whole array. Send `[]` or `null` to clear it. Message updates and chunks are applied in the order they are received. When an `agent_message` update includes `content`, that array replaces any content previously accumulated for the message, including content from earlier chunks. Later chunks with the same `messageId` append to the current content. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted leaves the stored metadata unchanged. `null` clears it. An object patches the stored metadata by top-level key: keys it omits are unchanged, a key set to `null` is removed, and any other value replaces that key's stored value without merging nested objects. Beyond this patch rule, implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches) **content** `[ContentBlock\[\]](#contentblock) | null` Complete replacement content for this message. **messageId** `[MessageId](#messageid)` *required* A unique identifier for the message. ## AgentThought An agent thought or reasoning message upsert. Only `messageId` is required. `content` has patch semantics: an omitted field leaves existing thought content unchanged, `null` clears the value, and a concrete array replaces the previous value. For a new `messageId`, omitted `content` starts empty. `content` is replaced as a whole array. Send `[]` or `null` to clear it. Message updates and chunks are applied in the order they are received. When an `agent_thought` update includes `content`, that array replaces any content previously accumulated for the thought, including content from earlier chunks. Later chunks with the same `messageId` append to the current content. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted leaves the stored metadata unchanged. `null` clears it. An object patches the stored metadata by top-level key: keys it omits are unchanged, a key set to `null` is removed, and any other value replaces that key's stored value without merging nested objects. Beyond this patch rule, implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches) **content** `[ContentBlock\[\]](#contentblock) | null` Complete replacement content for this thought message. **messageId** `[MessageId](#messageid)` *required* A unique identifier for the thought message. ## Annotations Optional annotations for the client. The client can use annotations to inform how objects are used or displayed **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **audience** `[Role\[\]](#role) | null` Intended recipients for this content, such as the user or assistant. Omitted and `null` are equivalent and mean no audience is specified. **lastModified** `string | null` Timestamp indicating when the underlying resource was last modified. Should be an ISO 8601 formatted string (e.g., "2025-01-12T15:00:58Z"), as in MCP. Omitted and `null` are equivalent and mean the modification time is not reported. **priority** `number | null` Relative importance of this content when clients choose what to surface, from 0 (least important) to 1 (most important). Omitted and `null` are equivalent and mean no priority is specified. | Constraint | Value | | - | - | | Minimum | `0` | | Maximum | `1` | ## AudioContent Audio provided to or from an LLM. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **annotations** `[Annotations](#annotations) | null` Optional annotations that help clients decide how to display or route this content. Omitted and `null` are equivalent and mean no annotations are provided. **data** `string` *required* Base64-encoded media payload. * Content encoding: `base64` **mimeType** `[MediaType](#mediatype)` *required* MIME type describing the encoded media payload. ## AuthMethod Describes an available authentication method. The `type` field acts as the discriminator in the serialized JSON form. **Type:** Union **terminal** `object` Client runs the configured agent program as a separate interactive process, without passing this method to `auth/login`. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **args** `"string"[]` Additional arguments to append to the configured agent invocation for terminal auth. **description** `string | null` Optional human-readable description of this authentication method. Omitted and `null` are equivalent and mean no description is provided. **env** `[EnvVariable\[\]](#envvariable)` Additional environment variables to set on the configured agent invocation for terminal auth. Names MUST be unique. These values override same-named variables in the base launch configuration. **methodId** `[AuthMethodId](#authmethodid)` *required* Unique identifier for this authentication method. **name** `string` *required* Human-readable name of the authentication method. **type** `string` *required* The discriminator value. Must be `"terminal"`. **agent** `object` Agent handles authentication itself through `auth/login`. The `type` discriminator value is `agent`. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **description** `string | null` Optional human-readable description of this authentication method. Omitted and `null` are equivalent and mean no description is provided. **methodId** `[AuthMethodId](#authmethodid)` *required* Unique identifier for this authentication method. **name** `string` *required* Human-readable name of the authentication method. **type** `string` *required* The discriminator value. Must be `"agent"`. **other** `object` Custom or future authentication method. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Clients that do not understand this method type should preserve the raw payload when storing, replaying, proxying, or forwarding initialization data, and otherwise ignore the method or display it generically. **Properties** **methodId** `[AuthMethodId](#authmethodid)` *required* Unique identifier for this authentication method. **name** `string` *required* Human-readable name of the authentication method. **type** `string` *required* Custom or future authentication method type. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## AuthMethodAgent Agent handles authentication itself through `auth/login`. The `type` discriminator value is `agent`. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **description** `string | null` Optional human-readable description of this authentication method. Omitted and `null` are equivalent and mean no description is provided. **methodId** `[AuthMethodId](#authmethodid)` *required* Unique identifier for this authentication method. **name** `string` *required* Human-readable name of the authentication method. ## AuthMethodId Typed identifier used for auth method values on the wire. **Type:** `string` ## AuthMethodTerminal Terminal-based authentication method. The client runs the configured agent program as a separate interactive process for the user to authenticate via a TUI. Agents MUST advertise this method only when the client enabled its terminal authentication capability. A zero exit status signals success. Any other termination signals failure. The client MUST NOT pass this method to `auth/login`. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **args** `"string"[]` Additional arguments to append to the configured agent invocation for terminal auth. **description** `string | null` Optional human-readable description of this authentication method. Omitted and `null` are equivalent and mean no description is provided. **env** `[EnvVariable\[\]](#envvariable)` Additional environment variables to set on the configured agent invocation for terminal auth. Names MUST be unique. These values override same-named variables in the base launch configuration. **methodId** `[AuthMethodId](#authmethodid)` *required* Unique identifier for this authentication method. **name** `string` *required* Human-readable name of the authentication method. ## AvailableCommand A command the agent advertises to the client. The `type` field acts as the discriminator in the serialized JSON form. **Type:** Union **command** `object` A slash command the user can invoke by including it in a prompt. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **description** `string` *required* Human-readable description of what the command does. **input** `[AvailableCommandInput](#availablecommandinput) | null` Input for the command if required Omitted and `null` are equivalent and mean the command takes no input. **name** `string` *required* Command name without the leading `/` (e.g., `create_plan`, `research_codebase`). MUST NOT contain whitespace and MUST be unique within the command list. **type** `string` *required* The discriminator value. Must be `"command"`. **other** `object` Custom or future command kind. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Clients that do not understand this command type should preserve the raw payload when storing, replaying, proxying, or forwarding command metadata, and otherwise ignore the command or display it as a plain command using its `name` and `description`. **Properties** **description** `string` *required* Human-readable description of what the command does. **name** `string` *required* Command name without the leading `/`. MUST NOT contain whitespace and MUST be unique within the command list. **type** `string` *required* Custom or future command type. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## AvailableCommandInput The input specification for a command. **Type:** Union **text** `object` All text after the command name and the whitespace following it is provided as input. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **hint** `string` *required* A hint to display when the input hasn't been provided yet **type** `string` *required* The discriminator value. Must be `"text"`. **other** `object` Custom or future command input specification. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Clients that do not understand this input type should preserve the raw payload when storing, replaying, proxying, or forwarding command metadata, and otherwise ignore the input specification or display the command without structured input. **Properties** **type** `string` *required* Custom or future command input type. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## AvailableCommandsUpdate Available commands are ready or have changed **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **availableCommands** `[AvailableCommand\[\]](#availablecommand)` *required* Commands the agent can execute. ## BackgroundTerminal A listed terminal running in the background. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **terminalId** `[TerminalId](#terminalid)` *required* The ID of the listed terminal. ## BackgroundToolCall A listed tool call whose work continues in the background. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **toolCallId** `[ToolCallId](#toolcallid)` *required* The ID of the listed tool call. ## BackgroundWork One piece of work running independently of the session's foreground work. Items reference entities the Client already tracks. The Agent MUST announce each item before the first snapshot that lists it, and MUST report a terminal's `exitStatus` or a tool call's final status before the snapshot that removes it. Each piece of work is listed once: process-backed work is listed as its terminal, not also as its tool call. See protocol docs: [Background Work](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#background-work) **Type:** Union **terminal** `object` A process that keeps running after its tool call returned control to the model. Live until its `terminal_update` reports `exitStatus`. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **terminalId** `[TerminalId](#terminalid)` *required* The ID of the listed terminal. **type** `string` *required* The discriminator value. Must be `"terminal"`. **tool\_call** `object` Work started by a tool call that continues without a process of its own, such as a watcher, a workflow, or a scheduled wakeup. `pending` and `paused` tool calls stay listed. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **toolCallId** `[ToolCallId](#toolcallid)` *required* The ID of the listed tool call. **type** `string` *required* The discriminator value. Must be `"tool_call"`. **other** `object` Custom or future background work. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. An unknown item still means background work is running, even when the Client cannot show what it is. **Properties** **type** `string` *required* Custom or future background work type. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## BlobResourceContents Binary resource contents. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **blob** `string` *required* Base64-encoded bytes for a binary resource payload. * Content encoding: `base64` **mimeType** `[MediaType](#mediatype) | null` MIME type describing the encoded media payload. Omitted and `null` are equivalent and mean the MIME type is not specified. **uri** `string` *required* URI associated with this resource or media payload. * Format: `uri` ## BooleanPropertySchema Schema for boolean properties in an elicitation form. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **default** `boolean | null` Default value. Optional. Omitted and `null` are equivalent and mean no default value is provided. **description** `string | null` Human-readable description. Optional. Omitted and `null` are equivalent and mean no description is provided. **title** `string | null` Optional title for the property. Optional. Omitted and `null` are equivalent and mean no title is provided. ## CancelledPermissionOutcome The request was not approved and no option was selected. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ## ClientAuthCapabilities Authentication capabilities supported by the client. Advertised during initialization to inform the agent which authentication method types the client can handle. This governs opt-in types that require additional client-side support. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **terminal** `[TerminalAuthCapabilities](#terminalauthcapabilities) | null` Whether the client supports `terminal` authentication methods. Optional. Omitted and `null` are equivalent and mean the client does not advertise support. The client should supply `\{\}` only when it can reproduce the configured agent invocation in an interactive terminal. Supplying `\{\}` means the agent may include `terminal` entries in its authentication methods. ## ClientCapabilities Capabilities supported by the client. Advertised during initialization to inform the agent about available features and methods. See protocol docs: [Client Capabilities](https://agentclientprotocol.com/protocol/v2/initialization#client-capabilities) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **auth** `[ClientAuthCapabilities](#clientauthcapabilities) | null` Authentication capabilities supported by the client. Determines which authentication method types the agent may include in its `InitializeResponse`. Optional. Omitted and `null` are equivalent and mean the client does not advertise any authentication-method extensions. **elicitation** `[ElicitationCapabilities](#elicitationcapabilities) | null` Elicitation capabilities supported by the client. Determines which elicitation modes the agent may use. Optional. Omitted and `null` are equivalent and mean the client does not advertise elicitation support. ## Command A slash command the user can invoke by including it in a prompt. The `type` discriminator value is `command`. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **description** `string` *required* Human-readable description of what the command does. **input** `[AvailableCommandInput](#availablecommandinput) | null` Input for the command if required Omitted and `null` are equivalent and mean the command takes no input. **name** `string` *required* Command name without the leading `/` (e.g., `create_plan`, `research_codebase`). MUST NOT contain whitespace and MUST be unique within the command list. ## CommandPermissionSubject Permission request details for a command. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **command** `string` *required* The command that would be run if permission is granted. **cwd** `[AbsolutePath](#absolutepath)` *required* The absolute working directory for the command. **terminalId** `[TerminalId](#terminalid) | null` The associated terminal, when already known. Omitted and `null` are equivalent. **toolCallId** `[ToolCallId](#toolcallid) | null` The associated tool call, when known. Omitted and `null` are equivalent. ## CompactionId Unique identifier for a context compaction within a session. **Type:** `string` ## CompactionStatus Lifecycle state of a context compaction. **Type:** Union **in\_progress** `string` Compaction has started and has not finished. **completed** `string` Compaction finished successfully. **failed** `string` Compaction finished unsuccessfully. **cancelled** `string` Compaction was cancelled before it finished. **other** `string` Custom or future compaction status. Values beginning with `_` are reserved for implementation-specific extensions. Other unknown values are reserved for future ACP statuses. ## CompactionSummaryChunk A content block appended to a compaction's summary. A first-seen ID creates an in-progress compaction. Chunks append in receive order. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. This metadata is scoped to the chunk and does not patch stored metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **compactionId** `[CompactionId](#compactionid)` *required* ID of the compaction whose summary receives this content. **content** `[ContentBlock](#contentblock)` *required* One content block to append. ## CompactionUpdate A context compaction upsert. The first notification fixes the compaction's timeline position. Later updates with the same ID patch that entity in place. `summary`, `error`, and `_meta` have patch semantics: omission leaves the stored value unchanged, `null` clears it, and a concrete value replaces it. `summary: []` also clears the summary. A concrete `_meta` object patches the stored metadata by top-level key instead of replacing it. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted leaves the stored metadata unchanged. `null` clears it. An object patches the stored metadata by top-level key: keys it omits are unchanged, a key set to `null` is removed, and any other value replaces that key's stored value without merging nested objects. Beyond this patch rule, implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches) **compactionId** `[CompactionId](#compactionid)` *required* The Agent-owned ID of this compaction, unique within the session. **error** `string | null` Human-readable error details for the compaction. **status** `[CompactionStatus](#compactionstatus)` *required* Current lifecycle status. **summary** `[ContentBlock\[\]](#contentblock) | null` Complete replacement user-displayable summary content for the compaction. ## ConfigOptionUpdate Session configuration options have been updated. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **configOptions** `[SessionConfigOption\[\]](#sessionconfigoption)` *required* The full set of configuration options and their current values. ## Content Standard content block (text, images, resources). **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **content** `[ContentBlock](#contentblock)` *required* The actual content block. ## ContentBlock Content blocks represent displayable information in the Agent Client Protocol. Content blocks appear in: * User prompts sent via `session/prompt` * Language model output reported through `session/update` notifications as message updates or streamed chunks * Progress updates and results from tool calls This structure is compatible with the Model Context Protocol (MCP), so agents can forward content from MCP tool outputs without transformation. See protocol docs: [Content](https://agentclientprotocol.com/protocol/v2/content) **Type:** Union **text** `object` Text content. May be plain text or formatted with Markdown. All agents MUST support text content blocks in prompts. Clients SHOULD render this text as CommonMark and MAY support GitHub Flavored Markdown extensions. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **annotations** `[Annotations](#annotations) | null` Optional annotations that help clients decide how to display or route this content. Omitted and `null` are equivalent and mean no annotations are provided. **text** `string` *required* Text payload carried by this content block. **type** `string` *required* The discriminator value. Must be `"text"`. **image** `object` Images for visual context or analysis. Requires the `image` prompt capability when included in prompts. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **annotations** `[Annotations](#annotations) | null` Optional annotations that help clients decide how to display or route this content. Omitted and `null` are equivalent and mean no annotations are provided. **data** `string` *required* Base64-encoded media payload. * Content encoding: `base64` **mimeType** `[MediaType](#mediatype)` *required* MIME type describing the encoded media payload. **type** `string` *required* The discriminator value. Must be `"image"`. **uri** `string | null` URI associated with this resource or media payload. Omitted and `null` are equivalent and mean no URI is associated with the image. * Format: `uri` **audio** `object` Audio data for transcription or analysis. Requires the `audio` prompt capability when included in prompts. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **annotations** `[Annotations](#annotations) | null` Optional annotations that help clients decide how to display or route this content. Omitted and `null` are equivalent and mean no annotations are provided. **data** `string` *required* Base64-encoded media payload. * Content encoding: `base64` **mimeType** `[MediaType](#mediatype)` *required* MIME type describing the encoded media payload. **type** `string` *required* The discriminator value. Must be `"audio"`. **resource\_link** `object` References to resources that the receiver may be able to read. All agents MUST support resource links in prompts. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **annotations** `[Annotations](#annotations) | null` Optional annotations that help clients decide how to display or route this content. Omitted and `null` are equivalent and mean no annotations are provided. **description** `string | null` Optional human-readable details shown with this protocol object. Omitted and `null` are equivalent and mean no description is provided. **icons** `[Icon\[\]](#icon) | null` Optional set of sized icons that the client can display in a user interface. Omitted and `null` are equivalent and mean no icons are provided. **mimeType** `[MediaType](#mediatype) | null` MIME type describing the encoded media payload. Omitted and `null` are equivalent and mean the MIME type is not specified. **name** `string` *required* Human-readable name shown for this protocol object. **size** `integer | null` Optional size of the linked resource in bytes, if known. Omitted and `null` are equivalent and mean the size is not known. * Minimum: `0` **title** `string | null` Optional display title for end-user UI. Omitted and `null` are equivalent and mean no title is provided. **type** `string` *required* The discriminator value. Must be `"resource_link"`. **uri** `string` *required* URI associated with this resource or media payload. * Format: `uri` **resource** `object` Complete resource contents embedded directly in the message. Preferred for including context as it avoids extra round-trips. Requires the `embeddedContext` prompt capability when included in prompts. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **annotations** `[Annotations](#annotations) | null` Optional annotations that help clients decide how to display or route this content. Omitted and `null` are equivalent and mean no annotations are provided. **resource** `[EmbeddedResourceResource](#embeddedresourceresource)` *required* Embedded resource payload, either text or binary data. **type** `string` *required* The discriminator value. Must be `"resource"`. **other** `object` Custom or future content block. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Receivers that do not understand this content block type should preserve the raw payload when storing, replaying, proxying, or forwarding content, and otherwise ignore it or display it generically. Agents MUST reject a `session/prompt` request with a content block type they do not support with `-32602`. **Properties** **type** `string` *required* Custom or future content block type. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## ContentChunk A streamed item of message content. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. This metadata is scoped to the chunk and does not patch stored metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **content** `[ContentBlock](#contentblock)` *required* A single item of content **messageId** `[MessageId](#messageid)` *required* A unique identifier for the message this chunk belongs to. All chunks belonging to the same message share the same `messageId`. Chunks for different messages can interleave. ## Cost Cost information for a session. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **amount** `number` *required* Total cumulative cost for session. **currency** `string` *required* Unit of `amount`: an ISO 4217 currency code (e.g., "USD", "EUR") for money, or another unit such as "credits". ## Diff File changes produced by a tool call. `changes` is authoritative for affected absolute paths and operations. `patch` optionally carries renderable text for some or all of those changes and MUST be consistent with `changes`. Agents SHOULD provide `patch` whenever feasible. Clients MUST handle diffs where `patch` is omitted or `null`. See protocol docs: [Content](https://agentclientprotocol.com/protocol/v2/tool-calls#content) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **changes** `[DiffChange\[\]](#diffchange)` *required* Structured file changes described by this diff. Clients can use this field without parsing patch text to determine affected paths. **patch** `[DiffPatch](#diffpatch) | null` Renderable patch text for some or all of the structured changes. Agents SHOULD provide patch text whenever feasible. Omitted and `null` are equivalent and mean no renderable patch text was provided. ## DiffChange One file-level change described by a `Diff`. Structured change metadata lets clients identify affected files and operations without parsing the text patch. **Type:** Union **Shared properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **fileType** `[DiffFileType](#difffiletype) | null` File content kind after the operation (for `delete`, of the deleted file). Omitted and `null` are equivalent and mean the content kind is unknown. **mimeType** `[MediaType](#mediatype) | null` MIME type of the file contents after the operation (for `delete`, of the deleted file). Omitted and `null` are equivalent and mean the MIME type is unknown. **Variants:** **add** `object` A file was added. **Properties** **operation** `string` *required* The discriminator value. Must be `"add"`. **path** `[AbsolutePath](#absolutepath)` *required* Absolute path for the operation. **delete** `object` A file was deleted. **Properties** **operation** `string` *required* The discriminator value. Must be `"delete"`. **path** `[AbsolutePath](#absolutepath)` *required* Absolute path for the operation. **modify** `object` A file was modified in place. **Properties** **operation** `string` *required* The discriminator value. Must be `"modify"`. **path** `[AbsolutePath](#absolutepath)` *required* Absolute path for the operation. **move** `object` A file was moved or renamed. **Properties** **oldPath** `[AbsolutePath](#absolutepath)` *required* Absolute path before the operation. **operation** `string` *required* The discriminator value. Must be `"move"`. **path** `[AbsolutePath](#absolutepath)` *required* Absolute path after the operation. **copy** `object` A file was copied. **Properties** **oldPath** `[AbsolutePath](#absolutepath)` *required* Absolute path before the operation. **operation** `string` *required* The discriminator value. Must be `"copy"`. **path** `[AbsolutePath](#absolutepath)` *required* Absolute path after the operation. **other** `object` Custom or future file operation. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. **Properties** **operation** `string` *required* Custom or future file operation. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## DiffFileType Kind of file content represented by a diff change. **Type:** Union **text** `string` Text content. **binary** `string` Binary or otherwise non-text content. **directory** `string` Directory entry. **symlink** `string` Symbolic link. **other** `string` Custom or future file type. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## DiffPatch Renderable patch text and its format. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **format** `[DiffPatchFormat](#diffpatchformat)` *required* Patch format. The only ACP-defined value is `git_patch`. **text** `string` *required* Patch text in the format named by `format`. ## DiffPatchFormat Text patch format used by `DiffPatch`. **Type:** Union **git\_patch** `string` One or more `diff --git` sections in Git's `--patch` (`-p`) text format. Unlike Git, which writes paths relative to the repository root, every path MUST be absolute, including in `rename from`, `rename to`, `copy from`, and `copy to` lines, and MUST NOT have a prefix such as Git's default `a/` and `b/`. Otherwise paths follow Git: `/dev/null` names the missing side of an added or deleted file in the `---` and `+++` lines, and paths with unusual characters are quoted as Git quotes them. Each path, once unquoted, is the same native absolute path string as the matching `changes` entry. Surrounding commit metadata and email envelopes MUST NOT be included. **other** `string` Custom or future patch format. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## DiffPathChange Operation metadata for add, delete, and modify changes. **Type:** Object **Properties:** **path** `[AbsolutePath](#absolutepath)` *required* Absolute path for the operation. ## DiffPathPairChange Operation metadata for move and copy changes. **Type:** Object **Properties:** **oldPath** `[AbsolutePath](#absolutepath)` *required* Absolute path before the operation. **path** `[AbsolutePath](#absolutepath)` *required* Absolute path after the operation. ## ElicitationAcceptAction The user accepted the elicitation and provided content. **Type:** Object **Properties:** **content** `object | null` The user-provided content, if any, as an object matching the requested schema. Omitted and `null` are equivalent and mean no content is provided. ## ElicitationCapabilities Elicitation capabilities supported by the client. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **form** `[ElicitationFormCapabilities](#elicitationformcapabilities) | null` Whether the client supports form-based elicitation. Optional. Omitted and `null` are equivalent and mean form support is not advertised. Supplying `\{\}` explicitly advertises form support. **url** `[ElicitationUrlCapabilities](#elicitationurlcapabilities) | null` Whether the client supports URL-based elicitation. Optional. Omitted and `null` are equivalent and mean the client does not advertise support. Supplying `\{\}` means the client supports URL-based elicitation. ## ElicitationContentValue Allowed wire representations for `ElicitationContentValue`. **Type:** Union **String** `string` String value accepted in elicitation response content. **Integer** `int64` Integer value accepted in elicitation response content. **Number** `double` Number value accepted in elicitation response content. **Boolean** `boolean` Boolean value accepted in elicitation response content. **StringArray** `array` String array value accepted in elicitation response content. **Other** Any other JSON value, such as the value of a custom or future property type. Preserved as sent. Agents validate it against the requested schema like any other value. ## ElicitationFormCapabilities Form-based elicitation capabilities. Supplying `\{\}` means the client supports form-based elicitation. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ## ElicitationFormMode Form-based elicitation mode where the client renders a form from the provided schema. **Type:** Union **Shared properties:** **requestedSchema** `[ElicitationSchema](#elicitationschema)` *required* A JSON Schema describing the form fields to present to the user. **Variants:** **Session** Tied to a session, optionally to a specific tool call within that session. **Properties** **sessionId** `[SessionId](#sessionid)` *required* The session this elicitation is tied to. **toolCallId** `[ToolCallId](#toolcallid) | null` Optional tool call within the session. Optional. Omitted and `null` are equivalent and mean the elicitation is scoped to the session without a specific tool call. **Request** Tied to a specific JSON-RPC request outside of a session (e.g., during auth/configuration phases before any session is started). **Properties** **requestId** `[RequestId](#requestid)` *required* The pending Client-to-Agent request this elicitation is tied to. ## ElicitationId Unique identifier for an elicitation. **Type:** `string` ## ElicitationPropertySchema Property schema for elicitation form fields. Each variant corresponds to a JSON Schema `"type"` value. Single-select enums use `type: "string"` with `enum` or `oneOf` set. Multi-select enums use `type: "array"`. **Type:** Union **string** `object` String property (or single-select enum when `enum`/`oneOf` is set). **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **default** `string | null` Default value. Optional. Omitted and `null` are equivalent and mean no default value is provided. **description** `string | null` Human-readable description. Optional. Omitted and `null` are equivalent and mean no description is provided. **enum** `"string"[] | null` Enum values for untitled single-select enums. Must contain at least one value when present. Optional. Omitted and `null` are equivalent and mean no untitled single-select choices are declared by `enum`. **format** `[StringFormat](#stringformat) | null` String format. Optional. Omitted and `null` are equivalent and mean there is no format constraint. **maxLength** `integer | null` Maximum string length. Optional. Omitted and `null` are equivalent and mean there is no maximum length constraint. * Minimum: `0` **minLength** `integer | null` Minimum string length. Optional. Omitted and `null` are equivalent and mean there is no minimum length constraint. * Minimum: `0` **oneOf** `[EnumOption\[\]](#enumoption) | null` Titled enum options for titled single-select enums. Must contain at least one option when present. Optional. Omitted and `null` are equivalent and mean no titled single-select choices are declared by `oneOf`. **pattern** `string | null` Pattern the string must match, in ECMA-262 regular expression syntax. Optional. Omitted and `null` are equivalent and mean there is no pattern constraint. * Format: `regex` **title** `string | null` Optional title for the property. Optional. Omitted and `null` are equivalent and mean no title is provided. **type** `string` *required* The discriminator value. Must be `"string"`. **number** `object` Number (floating-point) property. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **default** `number | null` Default value. Optional. Omitted and `null` are equivalent and mean no default value is provided. **description** `string | null` Human-readable description. Optional. Omitted and `null` are equivalent and mean no description is provided. **maximum** `number | null` Maximum value (inclusive). Optional. Omitted and `null` are equivalent and mean there is no inclusive upper bound. **minimum** `number | null` Minimum value (inclusive). Optional. Omitted and `null` are equivalent and mean there is no inclusive lower bound. **title** `string | null` Optional title for the property. Optional. Omitted and `null` are equivalent and mean no title is provided. **type** `string` *required* The discriminator value. Must be `"number"`. **integer** `object` Integer property. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **default** `integer | null` Default value. Optional. Omitted and `null` are equivalent and mean no default value is provided. **description** `string | null` Human-readable description. Optional. Omitted and `null` are equivalent and mean no description is provided. **maximum** `integer | null` Maximum value (inclusive). Optional. Omitted and `null` are equivalent and mean there is no inclusive upper bound. **minimum** `integer | null` Minimum value (inclusive). Optional. Omitted and `null` are equivalent and mean there is no inclusive lower bound. **title** `string | null` Optional title for the property. Optional. Omitted and `null` are equivalent and mean no title is provided. **type** `string` *required* The discriminator value. Must be `"integer"`. **boolean** `object` Boolean property. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **default** `boolean | null` Default value. Optional. Omitted and `null` are equivalent and mean no default value is provided. **description** `string | null` Human-readable description. Optional. Omitted and `null` are equivalent and mean no description is provided. **title** `string | null` Optional title for the property. Optional. Omitted and `null` are equivalent and mean no title is provided. **type** `string` *required* The discriminator value. Must be `"boolean"`. **array** `object` Multi-select array property. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **default** `"string"[] | null` Default selected values. Optional. Omitted and `null` are equivalent and mean no default selections are provided. **description** `string | null` Human-readable description. Optional. Omitted and `null` are equivalent and mean no description is provided. **items** `[MultiSelectItems](#multiselectitems)` *required* The items definition describing allowed values. **maxItems** `integer | null` Maximum number of items to select. Optional. Omitted and `null` are equivalent and mean there is no maximum selection count. * Minimum: `0` **minItems** `integer | null` Minimum number of items to select. Optional. Omitted and `null` are equivalent and mean there is no minimum selection count. * Minimum: `0` **title** `string | null` Optional title for the property. Optional. Omitted and `null` are equivalent and mean no title is provided. **type** `string` *required* The discriminator value. Must be `"array"`. **other** `object` Custom or future elicitation property schema. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Clients that do not understand this property schema type should preserve the raw schema when storing, replaying, proxying, or forwarding elicitation requests. They MUST NOT render it as a known input control. **Properties** **type** `string` *required* Custom or future elicitation property schema type. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## ElicitationRequestScope Request-scoped elicitation, tied to a specific JSON-RPC request outside of a session (e.g., during auth/configuration phases before any session is started). **Type:** Object **Properties:** **requestId** `[RequestId](#requestid)` *required* The pending Client-to-Agent request this elicitation is tied to. ## ElicitationSchema Type-safe elicitation schema for requesting structured user input. This represents a JSON Schema object with primitive-typed properties, as required by the elicitation specification. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **description** `string | null` Optional description of what this schema represents. Optional. Omitted and `null` are equivalent and mean no schema description is provided. **properties** `object` *required* Property definitions (must be primitive types). **required** `"string"[] | null` List of required property names. Optional. Omitted and `null` are equivalent and mean no property names are required. **title** `string | null` Optional title for the schema. Optional. Omitted and `null` are equivalent and mean no title is provided. **type** `[ElicitationSchemaType](#elicitationschematype)` *required* Type discriminator. Always `"object"`. Any other value is rejected. ## ElicitationSchemaType Type discriminator for elicitation schemas. **Type:** Union **object** `string` Object schema type. ## ElicitationSessionScope Session-scoped elicitation, optionally tied to a specific tool call. When `toolCallId` is set, the elicitation is tied to a specific tool call. This is useful when an agent receives an elicitation from an MCP server during a tool call and needs to redirect it to the user. **Type:** Object **Properties:** **sessionId** `[SessionId](#sessionid)` *required* The session this elicitation is tied to. **toolCallId** `[ToolCallId](#toolcallid) | null` Optional tool call within the session. Optional. Omitted and `null` are equivalent and mean the elicitation is scoped to the session without a specific tool call. ## ElicitationUrlCapabilities URL-based elicitation capabilities. Supplying `\{\}` means the client supports URL-based elicitation. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ## ElicitationUrlMode URL-based elicitation mode where the client directs the user to a URL. **Type:** Union **Shared properties:** **elicitationId** `[ElicitationId](#elicitationid)` *required* The unique identifier for this elicitation. **url** `string` *required* The URL to direct the user to. * Format: `uri` **Variants:** **Session** Tied to a session, optionally to a specific tool call within that session. **Properties** **sessionId** `[SessionId](#sessionid)` *required* The session this elicitation is tied to. **toolCallId** `[ToolCallId](#toolcallid) | null` Optional tool call within the session. Optional. Omitted and `null` are equivalent and mean the elicitation is scoped to the session without a specific tool call. **Request** Tied to a specific JSON-RPC request outside of a session (e.g., during auth/configuration phases before any session is started). **Properties** **requestId** `[RequestId](#requestid)` *required* The pending Client-to-Agent request this elicitation is tied to. ## EmbeddedResource The contents of a resource, embedded into a prompt or tool call result. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **annotations** `[Annotations](#annotations) | null` Optional annotations that help clients decide how to display or route this content. Omitted and `null` are equivalent and mean no annotations are provided. **resource** `[EmbeddedResourceResource](#embeddedresourceresource)` *required* Embedded resource payload, either text or binary data. ## EmbeddedResourceResource Resource content that can be embedded in a message. **Type:** Union **TextResourceContents** Text resource contents embedded directly in the message. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **mimeType** `[MediaType](#mediatype) | null` MIME type describing the encoded media payload. Omitted and `null` are equivalent and mean the MIME type is not specified. **text** `string` *required* Text payload carried by this content block. **uri** `string` *required* URI associated with this resource or media payload. * Format: `uri` **BlobResourceContents** Binary resource contents embedded directly in the message. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **blob** `string` *required* Base64-encoded bytes for a binary resource payload. * Content encoding: `base64` **mimeType** `[MediaType](#mediatype) | null` MIME type describing the encoded media payload. Omitted and `null` are equivalent and mean the MIME type is not specified. **uri** `string` *required* URI associated with this resource or media payload. * Format: `uri` ## EnumOption A titled enum option with a const value, human-readable title, and optional description. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **const** `string` *required* The constant value for this option. **description** `string | null` Human-readable description. Optional. Omitted and `null` are equivalent and mean no description is provided. **title** `string` *required* Human-readable title for this option. ## EnvVariable An environment variable to set when launching a process. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **name** `string` *required* The name of the environment variable. **value** `string` *required* The value to set for the environment variable. ## Error JSON-RPC error object. Represents an error that occurred during method execution, following the JSON-RPC 2.0 error object specification with optional additional data. See protocol docs: [JSON-RPC Error Object](https://www.jsonrpc.org/specification#error_object) **Type:** Object **Properties:** **code** `[ErrorCode](#errorcode)` *required* A number indicating the error type that occurred. This must be an integer as defined in the JSON-RPC specification. **data** `[ErrorData](#errordata) | null` Optional primitive or structured value that contains additional information about the error. This may include debugging information or context-specific details. Omitted and `null` are equivalent and mean no additional data is provided. Some codes define a shape: `UnsupportedProtocolVersionErrorData` for `-32022`, and `SessionNotFoundErrorData` for `-32002` when a session is not found. **message** `string` *required* A string providing a short description of the error. The message should be limited to a concise single sentence. ## ErrorCode Predefined error codes for common JSON-RPC and ACP-specific errors. Standard errors use the JSON-RPC 2.0 codes. ACP-specific errors use the JSON-RPC server-error range (-32000 to -32099), and request cancellation uses -32800 from the range LSP reserves (-32899 to -32800). **Type:** Union **-32700** `int32` **Parse error**: Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text. **-32600** `int32` **Invalid request**: The JSON sent is not a valid Request object. **-32601** `int32` **Method not found**: The method does not exist or is not available. **-32602** `int32` **Invalid params**: Invalid method parameter(s). **-32603** `int32` **Internal error**: Internal JSON-RPC error. **-32800** `int32` **Request cancelled**: Execution of the method was aborted either due to a cancellation request from the caller or because of resource constraints or shutdown. **-32000** `int32` **Authentication required**: Authentication is required before this operation can be performed. **-32002** `int32` **Resource not found**: A given resource, such as a session, was not found. **-32022** `int32` **Unsupported protocol version**: No protocol version supported by the Agent is at or below the requested version. The error data is an `UnsupportedProtocolVersionErrorData`. **Other** `int32` Other undefined error code. ## ErrorData Schema for `Error::data`: the shapes ACP defines, or any other value. **Type:** Union **UnsupportedProtocolVersion** **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **requested** `[ProtocolVersion](#protocolversion)` *required* The protocol version the Client requested. **supported** `[ProtocolVersion\[\]](#protocolversion)` *required* The protocol versions the Agent supports. **SessionNotFound** **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **sessionId** `[SessionId](#sessionid)` *required* The session ID from the request. **Other** ## ErrorStopReason Details of a failure that ended active work. **Type:** Object **Properties:** **error** `[Error](#error) | null` The failure, as a JSON-RPC error object. Optional. Omitted and `null` are equivalent and mean the agent is not reporting failure details. Agents SHOULD include it. ## ExtNotification Allows either side to send an arbitrary notification that is not part of the ACP spec. Extension notifications provide a way to send one-way messages for custom functionality while maintaining protocol compatibility. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ## ExtRequest Allows for sending an arbitrary request that is not part of the ACP spec. Extension methods provide a way to add custom functionality while maintaining protocol compatibility. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ## ExtResponse Allows for sending an arbitrary response to an extension request that is not part of the ACP spec. Extension methods provide a way to add custom functionality while maintaining protocol compatibility. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ## HttpHeader An HTTP header to set when making requests to the MCP server. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **name** `string` *required* The name of the HTTP header. **value** `string` *required* The value to set for the HTTP header. ## Icon An optionally-sized icon that can be displayed in a user interface. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **mimeType** `[MediaType](#mediatype) | null` Optional MIME type override if the source MIME type is missing or generic. Omitted and `null` are equivalent and mean the source MIME type is used. **sizes** `"string"[] | null` Optional array of strings that specify sizes at which the icon can be used. Each string should be in `WxH` format (e.g., `"48x48"`, `"96x96"`) or `"any"` for scalable formats like SVG. If not provided, the client should assume that the icon can be used at any size. Omitted and `null` are equivalent and mean no sizes are specified. **src** `string` *required* A standard URI pointing to an icon resource. MUST be an `https:` or `data:` URI. Clients reject other schemes, fetch without credentials, and do not follow scheme- or origin-changing redirects. * Format: `uri` **theme** `[IconTheme](#icontheme) | null` Optional theme this icon is designed for. Omitted and `null` are equivalent and mean the icon is not theme-specific. ## IconTheme Theme an icon is designed for. **Type:** Union **light** `string` Icon designed for light backgrounds. **dark** `string` Icon designed for dark backgrounds. **other** `string` Custom or future icon theme. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## IdleStateUpdate No foreground work is active. Background activity may continue. Agents SHOULD include a `stopReason` when the idle transition ends foreground work. An idle update that does not end foreground work need not include one. Receivers treat an omitted, `null`, or malformed `stopReason` as the agent not reporting one. Repeated or resume snapshots may carry the last stop reason for context. They MUST NOT be counted as new completions, cancellations, or additional usage. **Type:** Union **Shared properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **background** `[BackgroundWork\[\]](#backgroundwork) | null` Work running independently of foreground work, as a complete snapshot. Optional. Omitted and `null` are equivalent and mean the Agent is not reporting background work, not that nothing is running. `[]` means no background work is running. An Agent that reports background work MUST include it on every state update for the session. A malformed list is treated as not reported. See protocol docs: [Background Work](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#background-work) **stopReason** `string | null` Why foreground work stopped. The value selects one of this type's variants, which may add fields of their own. Optional. Omitted and `null` are equivalent and mean the agent is not reporting a stop reason; a malformed value is treated the same way. See protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#stop-reasons) **Variants:** **end\_turn** `object` The active work ended successfully. Includes locally handled commands that required no model call. **Properties** **stopReason** `string` *required* The discriminator value. Must be `"end_turn"`. **max\_tokens** `object` The active work ended because the agent reached the maximum number of tokens. **Properties** **stopReason** `string` *required* The discriminator value. Must be `"max_tokens"`. **max\_turn\_requests** `object` The active work ended because the agent reached the maximum number of model requests for the foreground work. **Properties** **stopReason** `string` *required* The discriminator value. Must be `"max_turn_requests"`. **refusal** `object` The active work ended because the agent refused to continue. **Properties** **stopReason** `string` *required* The discriminator value. Must be `"refusal"`. **cancelled** `object` The user or client chose to stop the work: via `session/cancel`, by closing the session, or through an interaction the agent offers, such as a permission option that tells the agent to stop. Work the agent stops for its own reasons uses another reason, such as `error` for an internal timeout. Agents MUST report this stop reason on an idle `state_update` when cancellation ends active foreground work, even if aborting causes exceptions. Agents MUST catch these errors and report `cancelled`, not `error`. **Properties** **stopReason** `string` *required* The discriminator value. Must be `"cancelled"`. **error** `object` The active work ended because something failed. This includes pre-insertion foreground work. A prompt failure before insertion also requires an error response to `session/prompt`. After insertion, the prompt's response remains successful. **Properties** **error** `[Error](#error) | null` The failure, as a JSON-RPC error object. Optional. Omitted and `null` are equivalent and mean the agent is not reporting failure details. Agents SHOULD include it. **stopReason** `string` *required* The discriminator value. Must be `"error"`. **other** `object` Custom or future stop reason. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. **Properties** **stopReason** `string` *required* Custom or future stop reason. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. **none** `object` No stop reason: `stopReason` is omitted or `null`. **Properties** **stopReason** `null` ## ImageContent An image provided to or from an LLM. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **annotations** `[Annotations](#annotations) | null` Optional annotations that help clients decide how to display or route this content. Omitted and `null` are equivalent and mean no annotations are provided. **data** `string` *required* Base64-encoded media payload. * Content encoding: `base64` **mimeType** `[MediaType](#mediatype)` *required* MIME type describing the encoded media payload. **uri** `string | null` URI associated with this resource or media payload. Omitted and `null` are equivalent and mean no URI is associated with the image. * Format: `uri` ## Implementation Metadata about the implementation of the client or agent. Describes the name and version of an ACP implementation, with an optional title for UI representation. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **name** `string` *required* Intended for programmatic or logical use, but can be used as a display name fallback if title isn't present. **title** `string | null` Intended for UI and end-user contexts and optimized to be human-readable and easily understood. If not provided, the name should be used for display. Omitted and `null` are equivalent and mean the `name` is used for display. **version** `string` *required* Version of the implementation. Can be displayed to the user or used for debugging or metrics purposes. (e.g. "1.0.0"). ## IntegerPropertySchema Schema for integer properties in an elicitation form. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **default** `integer | null` Default value. Optional. Omitted and `null` are equivalent and mean no default value is provided. **description** `string | null` Human-readable description. Optional. Omitted and `null` are equivalent and mean no description is provided. **maximum** `integer | null` Maximum value (inclusive). Optional. Omitted and `null` are equivalent and mean there is no inclusive upper bound. **minimum** `integer | null` Minimum value (inclusive). Optional. Omitted and `null` are equivalent and mean there is no inclusive lower bound. **title** `string | null` Optional title for the property. Optional. Omitted and `null` are equivalent and mean no title is provided. ## McpCapabilities MCP capabilities supported by the agent for session lifecycle requests. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **http** `[McpHttpCapabilities](#mcphttpcapabilities) | null` Agent supports `http` MCP servers. Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports HTTP MCP server transports. **stdio** `[McpStdioCapabilities](#mcpstdiocapabilities) | null` Agent supports `stdio` MCP servers. Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports stdio MCP server transports. ## McpHttpCapabilities Capabilities for HTTP MCP server transports. Supplying `\{\}` means the agent supports HTTP MCP server transports. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ## McpServer Configuration for connecting to an MCP (Model Context Protocol) server. MCP servers provide tools and context that the agent can use when processing prompts. See protocol docs: [MCP Servers](https://agentclientprotocol.com/protocol/v2/session-setup#mcp-servers) **Type:** Union **http** `object` HTTP transport configuration Only available when the Agent capabilities include `session.mcp.http`. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **headers** `[HttpHeader\[\]](#httpheader)` HTTP headers to set when making requests to the MCP server. Headers the MCP transport defines are owned by the transport, and Agents use the transport's values for them. **name** `string` *required* Human-readable name identifying this MCP server. **type** `string` *required* The discriminator value. Must be `"http"`. **url** `string` *required* URL to the MCP server. * Format: `uri` **stdio** `object` Stdio transport configuration Only available when the Agent capabilities include `session.mcp.stdio`. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **args** `"string"[]` Command-line arguments to pass to the MCP server. **command** `[AbsolutePath](#absolutepath)` *required* Absolute path to the MCP server executable. **env** `[EnvVariable\[\]](#envvariable)` Environment variables to set when launching the MCP server. Names SHOULD be unique. Agents MAY reject duplicates with `-32602`, and otherwise the last entry wins. **name** `string` *required* Human-readable name identifying this MCP server. **type** `string` *required* The discriminator value. Must be `"stdio"`. **other** `object` Custom or future MCP server transport configuration. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Receivers that do not understand this transport should preserve the raw payload when storing, replaying, proxying, or forwarding session setup data. Agents MUST reject a request with a transport they do not support with `-32602`. **Properties** **type** `string` *required* Custom or future MCP server transport type. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## McpServerHttp HTTP transport configuration for MCP. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **headers** `[HttpHeader\[\]](#httpheader)` HTTP headers to set when making requests to the MCP server. Headers the MCP transport defines are owned by the transport, and Agents use the transport's values for them. **name** `string` *required* Human-readable name identifying this MCP server. **url** `string` *required* URL to the MCP server. * Format: `uri` ## McpServerStdio Stdio transport configuration for MCP. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **args** `"string"[]` Command-line arguments to pass to the MCP server. **command** `[AbsolutePath](#absolutepath)` *required* Absolute path to the MCP server executable. **env** `[EnvVariable\[\]](#envvariable)` Environment variables to set when launching the MCP server. Names SHOULD be unique. Agents MAY reject duplicates with `-32602`, and otherwise the last entry wins. **name** `string` *required* Human-readable name identifying this MCP server. ## McpStdioCapabilities Capabilities for stdio MCP server transports. Supplying `\{\}` means the agent supports stdio MCP server transports. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ## MediaType An Internet media type identifying the format of protocol content. **Type:** `string` ## MessageId Identifier for a message, unique among messages of the same type within a session. Each message type, such as user messages, agent messages, and agent thoughts, has its own ID space: messages of different types may share an ID and remain distinct messages. **Type:** `string` ## MultiSelectItems Items for a multi-select (array) property schema. **Type:** Union **string** `object` Multi-select string items with plain string values. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **enum** `"string"[]` *required* Allowed enum values. Must contain at least one value. **type** `string` *required* The discriminator value. Must be `"string"`. **other** `object` Custom or future typed multi-select items. **Properties** **type** `string` *required* Custom or future multi-select item type. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. **titled** Titled multi-select items with human-readable labels. As in MCP, titled items omit `type` and are identified by `anyOf`. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **anyOf** `[EnumOption\[\]](#enumoption)` *required* Titled enum options. Must contain at least one option. ## MultiSelectPropertySchema Schema for multi-select (array) properties in an elicitation form. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **default** `"string"[] | null` Default selected values. Optional. Omitted and `null` are equivalent and mean no default selections are provided. **description** `string | null` Human-readable description. Optional. Omitted and `null` are equivalent and mean no description is provided. **items** `[MultiSelectItems](#multiselectitems)` *required* The items definition describing allowed values. **maxItems** `integer | null` Maximum number of items to select. Optional. Omitted and `null` are equivalent and mean there is no maximum selection count. * Minimum: `0` **minItems** `integer | null` Minimum number of items to select. Optional. Omitted and `null` are equivalent and mean there is no minimum selection count. * Minimum: `0` **title** `string | null` Optional title for the property. Optional. Omitted and `null` are equivalent and mean no title is provided. ## Notice Fire-and-forget information for the user. Notices are live events rather than session history. Agents must not rely on a notice being received, displayed, or seen by the user. No Client capability is required, and unsupported Clients may ignore notices. See protocol docs: [Session Notices](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#session-notices) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **description** `string | null` Optional plain-text detail or guidance. Omitted and `null` are equivalent and mean no description was supplied. **severity** `[NoticeSeverity](#noticeseverity)` *required* Presentation severity hint. **title** `string` *required* Required non-empty plain-text title that can stand alone. * Min length: `1` ## NoticeSeverity Severity hint for a session notice. **Type:** Union **info** `string` Informational notice. **warning** `string` Warning notice. **error** `string` Error notice. **other** `string` Custom or future notice severity. Values beginning with `_` are reserved for implementation-specific extensions. Other unknown values are reserved for future ACP severities. ## NumberPropertySchema Schema for number (floating-point) properties in an elicitation form. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **default** `number | null` Default value. Optional. Omitted and `null` are equivalent and mean no default value is provided. **description** `string | null` Human-readable description. Optional. Omitted and `null` are equivalent and mean no description is provided. **maximum** `number | null` Maximum value (inclusive). Optional. Omitted and `null` are equivalent and mean there is no inclusive upper bound. **minimum** `number | null` Minimum value (inclusive). Optional. Omitted and `null` are equivalent and mean there is no inclusive lower bound. **title** `string | null` Optional title for the property. Optional. Omitted and `null` are equivalent and mean no title is provided. ## PermissionOption An option presented to the user when requesting permission. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **kind** `[PermissionOptionKind](#permissionoptionkind)` *required* Hint about the nature of this permission option. **name** `string` *required* Human-readable label to display to the user. **optionId** `[PermissionOptionId](#permissionoptionid)` *required* Identifier for this permission option. MUST be unique within the request. ## PermissionOptionId Unique identifier for a permission option. **Type:** `string` ## PermissionOptionKind The type of permission option being presented to the user. Helps clients choose appropriate icons and UI treatment. **Type:** Union **allow\_once** `string` Allow this operation only this time. **allow\_always** `string` Allow this operation and remember the choice. **reject\_once** `string` Reject this operation only this time. **reject\_always** `string` Reject this operation and remember the choice. **other** `string` Custom or future permission option kind. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## PlanEntry A single entry in the execution plan. Represents a task or goal that the assistant intends to accomplish as part of fulfilling the user's request. See protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/v2/agent-plan#plan-entries) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **content** `string` *required* Human-readable description of what this task aims to accomplish. **priority** `[PlanEntryPriority](#planentrypriority)` *required* The relative importance of this task. Used to indicate which tasks are most critical to the overall goal. **status** `[PlanEntryStatus](#planentrystatus)` *required* Current execution status of this task. ## PlanEntryPriority Priority levels for plan entries. Used to indicate the relative importance or urgency of different tasks in the execution plan. See protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/v2/agent-plan#plan-entries) **Type:** Union **high** `string` High priority task - critical to the overall goal. **medium** `string` Medium priority task - important but not critical. **low** `string` Low priority task - nice to have but not essential. **other** `string` Custom or future plan entry priority. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## PlanEntryStatus Status of a plan entry in the execution flow. Tracks the lifecycle of each task from planning through completion. See protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/v2/agent-plan#plan-entries) **Type:** Union **pending** `string` The task has not started yet. **in\_progress** `string` The task is currently being worked on. **completed** `string` The task has been successfully completed. **cancelled** `string` The task was cancelled before it completed. **other** `string` Custom or future plan entry status. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## PlanId Unique identifier for a plan within a session. **Type:** `string` ## PlanItems A plan represented as structured entries. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **entries** `[PlanEntry\[\]](#planentry)` *required* The list of tasks to be accomplished. When updating an item-based plan, the agent must send a complete list of all entries with their current status. The client replaces that plan with each update. **planId** `[PlanId](#planid)` *required* The plan ID to update. ## PlanUpdate A content update for a plan identified by ID. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **plan** `[PlanUpdateContent](#planupdatecontent)` *required* The updated plan content. ## PlanUpdateContent Updated content for a plan. **Type:** Union **items** `object` Structured plan entries. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **entries** `[PlanEntry\[\]](#planentry)` *required* The list of tasks to be accomplished. When updating an item-based plan, the agent must send a complete list of all entries with their current status. The client replaces that plan with each update. **planId** `[PlanId](#planid)` *required* The plan ID to update. **type** `string` *required* The discriminator value. Must be `"items"`. **other** `object` Custom or future plan update content. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Receivers that do not understand this content type should preserve the raw payload when storing, replaying, proxying, or forwarding plans, and otherwise ignore it or display it generically. It still replaces any earlier content for the same `planId`. **Properties** **planId** `[PlanId](#planid)` *required* The plan ID to update. **type** `string` *required* Custom or future plan update content type. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## PromptAudioCapabilities Capabilities for audio content in prompt requests. Supplying `\{\}` means the agent supports audio content in prompts. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ## PromptCapabilities Prompt capabilities supported by the agent in `session/prompt` requests. Baseline agent functionality requires support for `text` and `resource_link` content blocks in prompt requests. Other variants must be explicitly opted in to. Capabilities for different types of content in prompt requests. Indicates which content types beyond the baseline (text and resource links) the agent can process. See protocol docs: [Session Prompt Capabilities](https://agentclientprotocol.com/protocol/v2/initialization#session-prompt-capabilities) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **audio** `[PromptAudioCapabilities](#promptaudiocapabilities) | null` Agent supports `audio` content blocks. Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports audio content in prompts. **embeddedContext** `[PromptEmbeddedContextCapabilities](#promptembeddedcontextcapabilities) | null` Agent supports embedded context in `session/prompt` requests. When enabled, the Client is allowed to include `resource` content blocks in prompt requests for pieces of context that are referenced in the message. Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports embedded context in prompts. **image** `[PromptImageCapabilities](#promptimagecapabilities) | null` Agent supports `image` content blocks. Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports image content in prompts. ## PromptEmbeddedContextCapabilities Capabilities for embedded context in prompt requests. Supplying `\{\}` means the agent supports embedded context in prompts. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ## PromptImageCapabilities Capabilities for image content in prompt requests. Supplying `\{\}` means the agent supports image content in prompts. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ## ProtocolVersion Protocol version identifier. This version is only bumped for breaking changes. Non-breaking changes should be introduced via capabilities. **Type:** `integer (uint16)` | Constraint | Value | | - | - | | Minimum | `0` | | Maximum | `65535` | ## ReplayFrom Inclusive cursor describing where replayed session history should begin. Replay includes the position identified by the cursor. **Type:** Union **start** `object` Replay all retained conversation history from its first replayable entry. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **type** `string` *required* The discriminator value. Must be `"start"`. **other** `object` Custom or future replay cursor. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Intermediaries SHOULD preserve the raw payload when storing, replaying, proxying, or forwarding requests. Agents that do not support this cursor MUST reject the request with `-32602` (Invalid params), rather than substituting another cursor or resuming without replay. **Properties** **type** `string` *required* Custom or future replay cursor type. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## ReplayFromStart Inclusive replay cursor requesting replay from the start of retained conversation history. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ## RequestId A JSON-RPC request ID: a string or an integer. Unlike base JSON-RPC, it MUST NOT be `null`. The receiver MUST reply with the same value in the response. Each side chooses IDs for its own requests, so the same ID can be in use in both directions. A sender MUST NOT reuse an ID while a request with it is still awaiting a response. **Type:** Union **Number** `int64` A numeric request ID. **Str** `string` A string request ID. ## RequestPermissionOutcome The outcome of a permission request. **Type:** Union **cancelled** `object` The request was not approved and no option was selected: the session's work was cancelled, the user dismissed the prompt, or the client declined it by policy. Agents MUST NOT proceed with the operation. The client answers a request the agent cancels with `$/cancel_request` with this outcome. After sending `session/cancel`, the client MAY also send it without waiting for `$/cancel_request`, for a request it knows belongs to the cancelled foreground work. See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#cancellation) **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **outcome** `string` *required* The discriminator value. Must be `"cancelled"`. **selected** `object` The user selected one of the provided options. If `optionId` doesn't match an offered option, the agent MUST treat the request as not approved. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **optionId** `[PermissionOptionId](#permissionoptionid)` *required* The ID of the option the user selected. **outcome** `string` *required* The discriminator value. Must be `"selected"`. **other** `object` Custom or future permission outcome. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Agents that do not understand this outcome MUST NOT treat it as approval. They should preserve the raw payload when storing, replaying, proxying, or forwarding permission responses, and otherwise fail or decline the permission request according to policy. **Properties** **outcome** `string` *required* Custom or future permission outcome. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## RequestPermissionSubject The operation requiring permission. **Type:** Union **tool\_call** `object` Permission is requested before executing a tool call. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **toolCall** `[ToolCallUpdate](#toolcallupdate)` *required* Details about the tool call requiring permission. Clients apply this to their stored tool call exactly like a `tool_call_update` notification, in the order it was received, before showing the prompt. A first-seen `toolCallId` creates the tool call. **type** `string` *required* The discriminator value. Must be `"tool_call"`. **command** `object` Permission is requested before running a command. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **command** `string` *required* The command that would be run if permission is granted. **cwd** `[AbsolutePath](#absolutepath)` *required* The absolute working directory for the command. **terminalId** `[TerminalId](#terminalid) | null` The associated terminal, when already known. Omitted and `null` are equivalent. **toolCallId** `[ToolCallId](#toolcallid) | null` The associated tool call, when known. Omitted and `null` are equivalent. **type** `string` *required* The discriminator value. Must be `"command"`. **other** `object` Custom or future permission subject. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Clients that do not understand this subject type should preserve the raw payload when storing, replaying, proxying, or forwarding permission requests, and otherwise display a generic permission prompt or decline it according to policy. **Properties** **type** `string` *required* Custom or future permission subject type. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## RequiresActionStateUpdate The foreground workflow as a whole is blocked on user action. Agents SHOULD report this state when foreground work cannot progress without user action. Pending permissions or elicitations alone do not imply this state if other foreground work can progress, or if the requests belong only to independent background activity. Once reported, agents MUST report `running` when progress resumes, or `idle` if the work ends without resuming. Responding to one request does not itself imply `running`. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **background** `[BackgroundWork\[\]](#backgroundwork) | null` Work running independently of foreground work, as a complete snapshot. Optional. Omitted and `null` are equivalent and mean the Agent is not reporting background work, not that nothing is running. `[]` means no background work is running. An Agent that reports background work MUST include it on every state update for the session. A malformed list is treated as not reported. See protocol docs: [Background Work](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#background-work) ## ResourceLink A link to a resource that the receiver may be able to read, included in a prompt or tool call result. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **annotations** `[Annotations](#annotations) | null` Optional annotations that help clients decide how to display or route this content. Omitted and `null` are equivalent and mean no annotations are provided. **description** `string | null` Optional human-readable details shown with this protocol object. Omitted and `null` are equivalent and mean no description is provided. **icons** `[Icon\[\]](#icon) | null` Optional set of sized icons that the client can display in a user interface. Omitted and `null` are equivalent and mean no icons are provided. **mimeType** `[MediaType](#mediatype) | null` MIME type describing the encoded media payload. Omitted and `null` are equivalent and mean the MIME type is not specified. **name** `string` *required* Human-readable name shown for this protocol object. **size** `integer | null` Optional size of the linked resource in bytes, if known. Omitted and `null` are equivalent and mean the size is not known. * Minimum: `0` **title** `string | null` Optional display title for end-user UI. Omitted and `null` are equivalent and mean no title is provided. **uri** `string` *required* URI associated with this resource or media payload. * Format: `uri` ## Role The sender or recipient of messages and data in a conversation. **Type:** Union **assistant** `string` The assistant side of a conversation. **user** `string` The user side of a conversation. **other** `string` Custom or future role. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## RunningStateUpdate Foreground work is in progress. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **background** `[BackgroundWork\[\]](#backgroundwork) | null` Work running independently of foreground work, as a complete snapshot. Optional. Omitted and `null` are equivalent and mean the Agent is not reporting background work, not that nothing is running. `[]` means no background work is running. An Agent that reports background work MUST include it on every state update for the session. A malformed list is treated as not reported. See protocol docs: [Background Work](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#background-work) ## SelectedPermissionOutcome The user selected one of the provided options. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **optionId** `[PermissionOptionId](#permissionoptionid)` *required* The ID of the option the user selected. ## SessionAdditionalDirectoriesCapabilities Capabilities for additional session directories support. Supplying `\{\}` means the agent supports the `additionalDirectories` field on supported session lifecycle requests. Agents may return `SessionInfo.additionalDirectories` in `session/list` to report the complete ordered additional-root list associated with a listed session. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ## SessionCapabilities Session capabilities supported by the agent. Supplying `\{\}` means the agent supports the baseline session methods: `session/new`, `session/list`, `session/resume`, `session/close`, `session/prompt`, `session/cancel`, and `session/update`. Agents that support sessions **MAY** support additional session methods, prompt content types, and MCP transports by specifying additional capabilities. See protocol docs: [Session Capabilities](https://agentclientprotocol.com/protocol/v2/initialization#session-capabilities) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **additionalDirectories** `[SessionAdditionalDirectoriesCapabilities](#sessionadditionaldirectoriescapabilities) | null` Whether the agent supports `additionalDirectories` on supported session lifecycle requests. Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports `additionalDirectories` on supported session lifecycle requests. Agents may return `SessionInfo.additionalDirectories` to report the complete ordered additional-root list associated with a listed session. **delete** `[SessionDeleteCapabilities](#sessiondeletecapabilities) | null` Whether the agent supports `session/delete`. Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports deleting sessions from `session/list`. **mcp** `[McpCapabilities](#mcpcapabilities) | null` MCP capabilities supported by the agent for session lifecycle requests. Optional. Omitted and `null` are equivalent and mean the agent does not advertise MCP server transport support for sessions. **prompt** `[PromptCapabilities](#promptcapabilities) | null` Prompt capabilities supported by the agent in `session/prompt` requests. Optional. Omitted and `null` are equivalent and mean the agent does not advertise any prompt extensions beyond the baseline text and resource-link content required by `session/prompt`. **systemPrompt** `[SessionSystemPromptCapabilities](#sessionsystempromptcapabilities) | null` Whether the agent supports `systemPrompt` on session lifecycle requests. Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports `systemPrompt` in `append` mode. ## SessionConfigBoolean A boolean on/off toggle session configuration option payload. **Type:** Object **Properties:** **currentValue** `boolean` *required* The current value of the boolean option. ## SessionConfigGroupId Unique identifier for a session configuration option value group. **Type:** `string` ## SessionConfigId Unique identifier for a session configuration option. **Type:** `string` ## SessionConfigOption A session configuration option selector and its current state. **Type:** Union **Shared properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **category** `[SessionConfigOptionCategory](#sessionconfigoptioncategory) | null` Optional semantic category for this option (UX only). Omitted and `null` are equivalent and mean no category is provided. **configId** `[SessionConfigId](#sessionconfigid)` *required* Unique identifier for the configuration option. **description** `string | null` Optional description for the Client to display to the user. Omitted and `null` are equivalent and mean no description is provided. **name** `string` *required* Human-readable label for the option. **Variants:** **select** `object` Single-value selector (dropdown). **Properties** **currentValue** `[SessionConfigValueId](#sessionconfigvalueid)` *required* The currently selected value. MUST be one of the `value`s in `options`. **options** `[SessionConfigSelectOptions](#sessionconfigselectoptions)` *required* The set of selectable options. MUST contain at least one value, and each `value` MUST be unique within the option, including across groups. **type** `string` *required* The discriminator value. Must be `"select"`. **boolean** `object` Boolean on/off toggle. **Properties** **currentValue** `boolean` *required* The current value of the boolean option. **type** `string` *required* The discriminator value. Must be `"boolean"`. **other** `object` Custom or future session configuration option payload. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Clients that do not understand this option type should preserve the raw payload when storing, replaying, proxying, or forwarding configuration data, and otherwise ignore the option. The Agent keeps using its `currentValue`. **Properties** **type** `string` *required* Custom or future session configuration option type. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## SessionConfigOptionCategory Semantic category for a session configuration option. This is intended to help Clients distinguish broadly common selectors (e.g. model selector vs session mode selector vs thought/reasoning level) for UX purposes (keyboard shortcuts, icons, placement). It MUST NOT be required for correctness. Clients MUST handle missing or unknown categories gracefully. Category names beginning with `_` are free for custom use, like other ACP extension methods. Category names that do not begin with `_` are reserved for the ACP spec. **Type:** Union **mode** `string` Session mode selector. **model** `string` Model selector. **model\_config** `string` Model-related configuration parameter. **thought\_level** `string` Thought/reasoning level selector. **other** `string` Custom or future category. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## SessionConfigSelect A single-value selector (dropdown) session configuration option payload. **Type:** Object **Properties:** **currentValue** `[SessionConfigValueId](#sessionconfigvalueid)` *required* The currently selected value. MUST be one of the `value`s in `options`. **options** `[SessionConfigSelectOptions](#sessionconfigselectoptions)` *required* The set of selectable options. MUST contain at least one value, and each `value` MUST be unique within the option, including across groups. ## SessionConfigSelectGroup A group of possible values for a session configuration option. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **groupId** `[SessionConfigGroupId](#sessionconfiggroupid)` *required* Unique identifier for this group. **name** `string` *required* Human-readable label for this group. **options** `[SessionConfigSelectOption\[\]](#sessionconfigselectoption)` *required* The set of option values in this group. MUST contain at least one value. ## SessionConfigSelectOption A possible value for a session configuration option. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **description** `string | null` Optional description for this option value. Omitted and `null` are equivalent and mean no description is provided. **name** `string` *required* Human-readable label for this option value. **value** `[SessionConfigValueId](#sessionconfigvalueid)` *required* Unique identifier for this option value. ## SessionConfigSelectOptions Possible values for a session configuration option. **Type:** Union **Ungrouped** `array` A flat list of options with no grouping. **Grouped** `array` A list of options grouped under headers. ## SessionConfigValueId Unique identifier for a session configuration option value. **Type:** `string` ## SessionDeleteCapabilities Capabilities for the `session/delete` method. Supplying `\{\}` means the agent supports deleting sessions from `session/list`. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ## SessionId A unique identifier for a conversation session between a client and agent. Each session has its own context, conversation history, and state, so one agent can run several independent sessions. See protocol docs: [Session ID](https://agentclientprotocol.com/protocol/v2/session-setup#session-id) **Type:** `string` ## SessionInfo Information about a session returned by session/list **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **additionalDirectories** `[AbsolutePath\[\]](#absolutepath)` Additional workspace roots reported for this session. Each path must be absolute. When present, this is the complete ordered additional-root list reported by the Agent. Omitted and empty values are equivalent: the response reports no additional roots. **cwd** `[AbsolutePath](#absolutepath)` *required* The working directory for this session. Must be an absolute path. **sessionId** `[SessionId](#sessionid)` *required* Unique identifier for the session **title** `string | null` Human-readable title for the session Omitted and `null` are equivalent and mean no title is provided. **updatedAt** `string | null` RFC 3339 timestamp of last activity. Omitted and `null` are equivalent and mean the last activity time is not reported. * Format: `date-time` ## SessionInfoUpdate Update to session metadata. All fields are optional to support partial updates. Agents send this notification to update session information like title or custom metadata. Clients can use it to keep session titles and state current. Omitted fields leave the existing session info unchanged. `null` clears the corresponding value. A concrete `_meta` object patches the stored metadata by top-level key. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted leaves the stored metadata unchanged. `null` clears it. An object patches the stored metadata by top-level key: keys it omits are unchanged, a key set to `null` is removed, and any other value replaces that key's stored value without merging nested objects. Beyond this patch rule, implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches) **title** `string | null` Human-readable title for the session. Set to null to clear. **updatedAt** `string | null` RFC 3339 timestamp of last activity. Set to null to clear. * Format: `date-time` ## SessionListCursor An opaque cursor used to paginate `session/list` results. **Type:** `string` ## SessionNotFoundErrorData Data for the `-32002` (Resource not found) error when a session-scoped request names a session that does not exist or is not active. See protocol docs: [Unknown Sessions](https://agentclientprotocol.com/protocol/v2/error#unknown-sessions) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **sessionId** `[SessionId](#sessionid)` *required* The session ID from the request. ## SessionSystemPromptCapabilities Capabilities for client-provided system prompts. Supplying `\{\}` means the agent supports `systemPrompt` on session lifecycle requests in `append` mode. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **mode** `[SessionSystemPromptModeCapabilities](#sessionsystempromptmodecapabilities) | null` Delivery modes the agent supports in addition to `append`. Optional. Omitted and `null` are equivalent and mean the agent supports only `append`. ## SessionSystemPromptModeCapabilities System prompt delivery modes the agent supports in addition to `append`. `append` has no entry because every agent advertising `session.systemPrompt` supports it. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **override** `[SessionSystemPromptOverrideCapabilities](#sessionsystempromptoverridecapabilities) | null` Whether the agent supports `override` mode. Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports replacing its built-in default instructions with the client-provided system prompt. ## SessionSystemPromptOverrideCapabilities Capabilities for the `override` system prompt mode. Supplying `\{\}` means the agent supports replacing its built-in default instructions with the client-provided system prompt. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ## SessionUpdate Different types of updates that can be sent while a session exists. These updates report messages, progress, and other session activity. See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#3-agent-reports-output) **Type:** Union **user\_message\_chunk** `object` A chunk of the user's message being streamed. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. This metadata is scoped to the chunk and does not patch stored metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **content** `[ContentBlock](#contentblock)` *required* A single item of content **messageId** `[MessageId](#messageid)` *required* A unique identifier for the message this chunk belongs to. All chunks belonging to the same message share the same `messageId`. Chunks for different messages can interleave. **sessionUpdate** `string` *required* The discriminator value. Must be `"user_message_chunk"`. **user\_message** `object` A user message has been created or updated. Agents can send this when they accept or replay a user message. When a client receives another `user_message` update with the same `messageId`, fields in the new update patch the previous fields for that message. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted leaves the stored metadata unchanged. `null` clears it. An object patches the stored metadata by top-level key: keys it omits are unchanged, a key set to `null` is removed, and any other value replaces that key's stored value without merging nested objects. Beyond this patch rule, implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches) **content** `[ContentBlock\[\]](#contentblock) | null` Complete replacement content for this message. **messageId** `[MessageId](#messageid)` *required* A unique identifier for the message. **sessionUpdate** `string` *required* The discriminator value. Must be `"user_message"`. **agent\_message\_chunk** `object` A chunk of the agent's response being streamed. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. This metadata is scoped to the chunk and does not patch stored metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **content** `[ContentBlock](#contentblock)` *required* A single item of content **messageId** `[MessageId](#messageid)` *required* A unique identifier for the message this chunk belongs to. All chunks belonging to the same message share the same `messageId`. Chunks for different messages can interleave. **sessionUpdate** `string` *required* The discriminator value. Must be `"agent_message_chunk"`. **agent\_message** `object` An agent message has been created or updated. Agents can send this in addition to streamed chunks. When a client receives another `agent_message` update with the same `messageId`, fields in the new update patch the previous fields for that message. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted leaves the stored metadata unchanged. `null` clears it. An object patches the stored metadata by top-level key: keys it omits are unchanged, a key set to `null` is removed, and any other value replaces that key's stored value without merging nested objects. Beyond this patch rule, implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches) **content** `[ContentBlock\[\]](#contentblock) | null` Complete replacement content for this message. **messageId** `[MessageId](#messageid)` *required* A unique identifier for the message. **sessionUpdate** `string` *required* The discriminator value. Must be `"agent_message"`. **agent\_thought\_chunk** `object` A chunk of the agent's internal reasoning being streamed. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. This metadata is scoped to the chunk and does not patch stored metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **content** `[ContentBlock](#contentblock)` *required* A single item of content **messageId** `[MessageId](#messageid)` *required* A unique identifier for the message this chunk belongs to. All chunks belonging to the same message share the same `messageId`. Chunks for different messages can interleave. **sessionUpdate** `string` *required* The discriminator value. Must be `"agent_thought_chunk"`. **agent\_thought** `object` An agent thought or reasoning message has been created or updated. Agents can send this in addition to streamed chunks. When a client receives another `agent_thought` update with the same `messageId`, fields in the new update patch the previous fields for that message. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted leaves the stored metadata unchanged. `null` clears it. An object patches the stored metadata by top-level key: keys it omits are unchanged, a key set to `null` is removed, and any other value replaces that key's stored value without merging nested objects. Beyond this patch rule, implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches) **content** `[ContentBlock\[\]](#contentblock) | null` Complete replacement content for this thought message. **messageId** `[MessageId](#messageid)` *required* A unique identifier for the thought message. **sessionUpdate** `string` *required* The discriminator value. Must be `"agent_thought"`. **state\_update** `object` A snapshot of the session's aggregate foreground activity. **Properties** **sessionUpdate** `string` *required* The discriminator value. Must be `"state_update"`. **Alternatives (`anyOf`):** **running** `object` Foreground work is in progress. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **background** `[BackgroundWork\[\]](#backgroundwork) | null` Work running independently of foreground work, as a complete snapshot. Optional. Omitted and `null` are equivalent and mean the Agent is not reporting background work, not that nothing is running. `[]` means no background work is running. An Agent that reports background work MUST include it on every state update for the session. A malformed list is treated as not reported. See protocol docs: [Background Work](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#background-work) **state** `string` *required* The discriminator value. Must be `"running"`. **idle** `object` No foreground work is active. Background activity may continue. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **background** `[BackgroundWork\[\]](#backgroundwork) | null` Work running independently of foreground work, as a complete snapshot. Optional. Omitted and `null` are equivalent and mean the Agent is not reporting background work, not that nothing is running. `[]` means no background work is running. An Agent that reports background work MUST include it on every state update for the session. A malformed list is treated as not reported. See protocol docs: [Background Work](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#background-work) **state** `string` *required* The discriminator value. Must be `"idle"`. **stopReason** `string | null` Why foreground work stopped. The value selects one of this type's variants, which may add fields of their own. Optional. Omitted and `null` are equivalent and mean the agent is not reporting a stop reason; a malformed value is treated the same way. See protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#stop-reasons) **Alternatives (`anyOf`):** **end\_turn** `object` The active work ended successfully. Includes locally handled commands that required no model call. **Properties** **stopReason** `string` *required* The discriminator value. Must be `"end_turn"`. **max\_tokens** `object` The active work ended because the agent reached the maximum number of tokens. **Properties** **stopReason** `string` *required* The discriminator value. Must be `"max_tokens"`. **max\_turn\_requests** `object` The active work ended because the agent reached the maximum number of model requests for the foreground work. **Properties** **stopReason** `string` *required* The discriminator value. Must be `"max_turn_requests"`. **refusal** `object` The active work ended because the agent refused to continue. **Properties** **stopReason** `string` *required* The discriminator value. Must be `"refusal"`. **cancelled** `object` The user or client chose to stop the work: via `session/cancel`, by closing the session, or through an interaction the agent offers, such as a permission option that tells the agent to stop. Work the agent stops for its own reasons uses another reason, such as `error` for an internal timeout. Agents MUST report this stop reason on an idle `state_update` when cancellation ends active foreground work, even if aborting causes exceptions. Agents MUST catch these errors and report `cancelled`, not `error`. **Properties** **stopReason** `string` *required* The discriminator value. Must be `"cancelled"`. **error** `object` The active work ended because something failed. This includes pre-insertion foreground work. A prompt failure before insertion also requires an error response to `session/prompt`. After insertion, the prompt's response remains successful. **Properties** **error** `[Error](#error) | null` The failure, as a JSON-RPC error object. Optional. Omitted and `null` are equivalent and mean the agent is not reporting failure details. Agents SHOULD include it. **stopReason** `string` *required* The discriminator value. Must be `"error"`. **other** `object` Custom or future stop reason. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. **Properties** **stopReason** `string` *required* Custom or future stop reason. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. **none** `object` No stop reason: `stopReason` is omitted or `null`. **Properties** **stopReason** `null` **requires\_action** `object` Foreground work is blocked on user action. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **background** `[BackgroundWork\[\]](#backgroundwork) | null` Work running independently of foreground work, as a complete snapshot. Optional. Omitted and `null` are equivalent and mean the Agent is not reporting background work, not that nothing is running. `[]` means no background work is running. An Agent that reports background work MUST include it on every state update for the session. A malformed list is treated as not reported. See protocol docs: [Background Work](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#background-work) **state** `string` *required* The discriminator value. Must be `"requires_action"`. **other** `object` Custom or future session state. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Unless the Client advertised support for this state, Agents MUST still report the standard states. Clients MUST NOT treat an unrecognized state as `idle` or present the previous state as confirmed, and show a generic busy state until a known state arrives. **Properties** **state** `string` *required* Custom or future session state. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. **tool\_call\_content\_chunk** `object` A chunk of tool-call content being streamed. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. This metadata is scoped to the chunk and does not patch stored metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **content** `[ToolCallContent](#toolcallcontent)` *required* A single item of content produced by the tool call. **sessionUpdate** `string` *required* The discriminator value. Must be `"tool_call_content_chunk"`. **toolCallId** `[ToolCallId](#toolcallid)` *required* The ID of the tool call this content belongs to. **tool\_call\_update** `object` A tool call has been created or updated. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted leaves the stored metadata unchanged. `null` clears it. An object patches the stored metadata by top-level key: keys it omits are unchanged, a key set to `null` is removed, and any other value replaces that key's stored value without merging nested objects. Beyond this patch rule, implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches) **capabilities** `[ToolCallCapabilities](#toolcallcapabilities) | null` Client-initiated controls this tool call currently supports, such as cancellation. Omission leaves the capabilities unchanged, `null` clears them, and an object replaces the whole previous value. A new tool call starts with none. **content** `[ToolCallContent\[\]](#toolcallcontent) | null` Content produced by the tool call. **kind** `[ToolKind](#toolkind) | null` The category of tool being invoked. Helps clients choose appropriate icons and UI treatment. Omission leaves the kind unchanged, `null` resets it to `other`, and a value replaces it. A new tool call starts as `other`. **locations** `[ToolCallLocation\[\]](#toolcalllocation) | null` File locations affected by this tool call. Enables "follow-along" features in clients. **name** `string | null` Programmatic name of the tool being invoked. This field is optional and has patch semantics. Omission means no change, `null` clears the name, and a string replaces it. For a tool call ID the client has not seen before, omission or `null` means that no tool name is available. **rawInput** `object` Raw input parameters sent to the tool. **rawOutput** `object` Raw output returned by the tool. **sessionUpdate** `string` *required* The discriminator value. Must be `"tool_call_update"`. **status** `[ToolCallStatus](#toolcallstatus) | null` Current execution status of the tool call. Omission leaves the status unchanged, `null` resets it to `pending`, and a value replaces it. A new tool call starts as `pending`. **title** `string | null` Human-readable title describing what the tool is doing. Omission leaves the title unchanged, `null` unsets it, and a string replaces it. A new tool call starts without a title. **toolCallId** `[ToolCallId](#toolcallid)` *required* Unique identifier for this tool call within the session. **terminal\_update** `object` An agent-owned terminal has been created or updated. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted leaves the stored metadata unchanged. `null` clears it. An object patches the stored metadata by top-level key: keys it omits are unchanged, a key set to `null` is removed, and any other value replaces that key's stored value without merging nested objects. Beyond this patch rule, implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches) **capabilities** `[TerminalCapabilities](#terminalcapabilities) | null` Client-initiated controls this terminal currently supports, such as cancellation. Omission leaves the capabilities unchanged, `null` clears them, and an object replaces the whole previous value. A new terminal starts with none. **command** `string | null` The command being run. **cwd** `[AbsolutePath](#absolutepath) | null` The absolute working directory of the command. **exitStatus** `[TerminalExitStatus](#terminalexitstatus) | null` Exit information. A concrete object marks the terminal as exited. **output** `[TerminalOutput](#terminaloutput) | null` An authoritative replacement snapshot of terminal output bytes. **sessionUpdate** `string` *required* The discriminator value. Must be `"terminal_update"`. **size** `[TerminalSize](#terminalsize) | null` The terminal size the command runs with, when known. Clients can render output at this size so that column layouts, progress bars, and cursor-positioned output display as the program wrote them. **terminalId** `[TerminalId](#terminalid)` *required* Unique identifier for this terminal within the session. **terminal\_output\_chunk** `object` A chunk of bytes appended to an agent-owned terminal's output. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. This metadata is scoped to the chunk and does not patch stored metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **data** `string` *required* Independently base64-encoded terminal output bytes. * Content encoding: `base64` **sessionUpdate** `string` *required* The discriminator value. Must be `"terminal_output_chunk"`. **terminalId** `[TerminalId](#terminalid)` *required* The terminal receiving these bytes. **plan\_update** `object` A content update for a plan identified by ID. See protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/v2/agent-plan) **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **plan** `[PlanUpdateContent](#planupdatecontent)` *required* The updated plan content. **sessionUpdate** `string` *required* The discriminator value. Must be `"plan_update"`. **available\_commands\_update** `object` Available commands are ready or have changed **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **availableCommands** `[AvailableCommand\[\]](#availablecommand)` *required* Commands the agent can execute. **sessionUpdate** `string` *required* The discriminator value. Must be `"available_commands_update"`. **config\_option\_update** `object` Session configuration options have been updated. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **configOptions** `[SessionConfigOption\[\]](#sessionconfigoption)` *required* The full set of configuration options and their current values. **sessionUpdate** `string` *required* The discriminator value. Must be `"config_option_update"`. **session\_info\_update** `object` Session metadata has been updated (title, timestamps, custom metadata) **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted leaves the stored metadata unchanged. `null` clears it. An object patches the stored metadata by top-level key: keys it omits are unchanged, a key set to `null` is removed, and any other value replaces that key's stored value without merging nested objects. Beyond this patch rule, implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches) **sessionUpdate** `string` *required* The discriminator value. Must be `"session_info_update"`. **title** `string | null` Human-readable title for the session. Set to null to clear. **updatedAt** `string | null` RFC 3339 timestamp of last activity. Set to null to clear. * Format: `date-time` **usage\_update** `object` Context window and cost update for the session. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **cost** `[Cost](#cost) | null` Cumulative session cost. Omitted leaves the last reported cost unchanged. `null` clears it. A value replaces it. **sessionUpdate** `string` *required* The discriminator value. Must be `"usage_update"`. **size** `uint64` *required* Total context window size in tokens. * Minimum: `0` **used** `uint64` *required* Tokens currently in context. * Minimum: `0` **notice** `object` Information for the user that is not part of session history. No Client capability is required. Clients that do not understand or present notices may ignore them. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **description** `string | null` Optional plain-text detail or guidance. Omitted and `null` are equivalent and mean no description was supplied. **sessionUpdate** `string` *required* The discriminator value. Must be `"notice"`. **severity** `[NoticeSeverity](#noticeseverity)` *required* Presentation severity hint. **title** `string` *required* Required non-empty plain-text title that can stand alone. * Min length: `1` **compaction\_update** `object` A context compaction has been created or updated. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted leaves the stored metadata unchanged. `null` clears it. An object patches the stored metadata by top-level key: keys it omits are unchanged, a key set to `null` is removed, and any other value replaces that key's stored value without merging nested objects. Beyond this patch rule, implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches) **compactionId** `[CompactionId](#compactionid)` *required* The Agent-owned ID of this compaction, unique within the session. **error** `string | null` Human-readable error details for the compaction. **sessionUpdate** `string` *required* The discriminator value. Must be `"compaction_update"`. **status** `[CompactionStatus](#compactionstatus)` *required* Current lifecycle status. **summary** `[ContentBlock\[\]](#contentblock) | null` Complete replacement user-displayable summary content for the compaction. **compaction\_summary\_chunk** `object` A content block appended to a context compaction's retained summary. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. This metadata is scoped to the chunk and does not patch stored metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **compactionId** `[CompactionId](#compactionid)` *required* ID of the compaction whose summary receives this content. **content** `[ContentBlock](#contentblock)` *required* One content block to append. **sessionUpdate** `string` *required* The discriminator value. Must be `"compaction_summary_chunk"`. **other** `object` Custom or future session update. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Receivers that do not understand this update type should preserve the raw payload when storing, replaying, proxying, or forwarding session history, and otherwise ignore it or display it generically. **Properties** **sessionUpdate** `string` *required* Custom or future session update type. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## StateUpdate A snapshot of the session's aggregate foreground activity. Foreground work is the agent's active response or workflow in the session, including model processing, tool execution, and waiting for user action needed to continue that work. It can start with a prompt or be agent-initiated, for example to pursue an ongoing goal or follow up on a completed background task. Either way, the agent MUST report `running` when foreground work starts, or `requires_action` if it starts blocked on user action, and `idle` when it ends. The agent SHOULD include a stop reason on that idle update. Agent-initiated work does not require a prompt request or a synthetic user message. `running` may precede user-message insertion, for example during a foreground hook. It is not acknowledgment of insertion, and rejecting a prompt does not itself end foreground work. Background activity can continue and emit other `session/update` notifications while `idle`. Those notifications, including a detached task's progress or completion, do not by themselves change this state. A permission request only warrants `requires_action` when foreground work is blocked on user action. The agent SHOULD report `requires_action` when the foreground workflow as a whole cannot progress without user action, including permissions or elicitations. Once reported, it MUST report `running` when progress resumes, or `idle` when work ends without resuming. If other foreground work can progress, the state remains `running`. Resolving one of several requests does not itself change the state. Agents SHOULD ignore responses for work that has already ended rather than use them to resume it. A new session defaults to idle until a state update reports otherwise. Resume MUST send a current-state snapshot after any replay and before its response. The snapshot reports foreground state after resuming. The response alone does not imply idle. Repeated snapshots are idempotent, not additional work, completions, or usage. A repeated state may carry updated information without another state transition. The agent MUST report `idle` when no foreground activity remains. Completing an individual activity while other foreground work continues does not require an idle boundary. Local commands use the same lifecycle even without model work. See protocol docs: [Session States](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#session-states) **Type:** Union **running** `object` Foreground work is in progress. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **background** `[BackgroundWork\[\]](#backgroundwork) | null` Work running independently of foreground work, as a complete snapshot. Optional. Omitted and `null` are equivalent and mean the Agent is not reporting background work, not that nothing is running. `[]` means no background work is running. An Agent that reports background work MUST include it on every state update for the session. A malformed list is treated as not reported. See protocol docs: [Background Work](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#background-work) **state** `string` *required* The discriminator value. Must be `"running"`. **idle** `object` No foreground work is active. Background activity may continue. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **background** `[BackgroundWork\[\]](#backgroundwork) | null` Work running independently of foreground work, as a complete snapshot. Optional. Omitted and `null` are equivalent and mean the Agent is not reporting background work, not that nothing is running. `[]` means no background work is running. An Agent that reports background work MUST include it on every state update for the session. A malformed list is treated as not reported. See protocol docs: [Background Work](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#background-work) **state** `string` *required* The discriminator value. Must be `"idle"`. **stopReason** `string | null` Why foreground work stopped. The value selects one of this type's variants, which may add fields of their own. Optional. Omitted and `null` are equivalent and mean the agent is not reporting a stop reason; a malformed value is treated the same way. See protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#stop-reasons) **Alternatives (`anyOf`):** **end\_turn** `object` The active work ended successfully. Includes locally handled commands that required no model call. **Properties** **stopReason** `string` *required* The discriminator value. Must be `"end_turn"`. **max\_tokens** `object` The active work ended because the agent reached the maximum number of tokens. **Properties** **stopReason** `string` *required* The discriminator value. Must be `"max_tokens"`. **max\_turn\_requests** `object` The active work ended because the agent reached the maximum number of model requests for the foreground work. **Properties** **stopReason** `string` *required* The discriminator value. Must be `"max_turn_requests"`. **refusal** `object` The active work ended because the agent refused to continue. **Properties** **stopReason** `string` *required* The discriminator value. Must be `"refusal"`. **cancelled** `object` The user or client chose to stop the work: via `session/cancel`, by closing the session, or through an interaction the agent offers, such as a permission option that tells the agent to stop. Work the agent stops for its own reasons uses another reason, such as `error` for an internal timeout. Agents MUST report this stop reason on an idle `state_update` when cancellation ends active foreground work, even if aborting causes exceptions. Agents MUST catch these errors and report `cancelled`, not `error`. **Properties** **stopReason** `string` *required* The discriminator value. Must be `"cancelled"`. **error** `object` The active work ended because something failed. This includes pre-insertion foreground work. A prompt failure before insertion also requires an error response to `session/prompt`. After insertion, the prompt's response remains successful. **Properties** **error** `[Error](#error) | null` The failure, as a JSON-RPC error object. Optional. Omitted and `null` are equivalent and mean the agent is not reporting failure details. Agents SHOULD include it. **stopReason** `string` *required* The discriminator value. Must be `"error"`. **other** `object` Custom or future stop reason. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. **Properties** **stopReason** `string` *required* Custom or future stop reason. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. **none** `object` No stop reason: `stopReason` is omitted or `null`. **Properties** **stopReason** `null` **requires\_action** `object` Foreground work is blocked on user action. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **background** `[BackgroundWork\[\]](#backgroundwork) | null` Work running independently of foreground work, as a complete snapshot. Optional. Omitted and `null` are equivalent and mean the Agent is not reporting background work, not that nothing is running. `[]` means no background work is running. An Agent that reports background work MUST include it on every state update for the session. A malformed list is treated as not reported. See protocol docs: [Background Work](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#background-work) **state** `string` *required* The discriminator value. Must be `"requires_action"`. **other** `object` Custom or future session state. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Unless the Client advertised support for this state, Agents MUST still report the standard states. Clients MUST NOT treat an unrecognized state as `idle` or present the previous state as confirmed, and show a generic busy state until a known state arrives. **Properties** **state** `string` *required* Custom or future session state. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## StringFormat String format types for string properties in elicitation schemas. **Type:** Union **email** `string` Email address format. **uri** `string` URI format. **date** `string` Date format (YYYY-MM-DD). **date-time** `string` Date-time format (RFC 3339). **other** `string` Custom or future string format. Unknown formats are preserved. Implementations that do not understand a format should treat it as an annotation rather than rejecting the schema. ## StringMultiSelectItems String item schema for multi-select enum properties. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **enum** `"string"[]` *required* Allowed enum values. Must contain at least one value. ## StringPropertySchema Schema for string properties in an elicitation form. When `enum` or `oneOf` is set, this represents a single-select enum with `"type": "string"`. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **default** `string | null` Default value. Optional. Omitted and `null` are equivalent and mean no default value is provided. **description** `string | null` Human-readable description. Optional. Omitted and `null` are equivalent and mean no description is provided. **enum** `"string"[] | null` Enum values for untitled single-select enums. Must contain at least one value when present. Optional. Omitted and `null` are equivalent and mean no untitled single-select choices are declared by `enum`. **format** `[StringFormat](#stringformat) | null` String format. Optional. Omitted and `null` are equivalent and mean there is no format constraint. **maxLength** `integer | null` Maximum string length. Optional. Omitted and `null` are equivalent and mean there is no maximum length constraint. * Minimum: `0` **minLength** `integer | null` Minimum string length. Optional. Omitted and `null` are equivalent and mean there is no minimum length constraint. * Minimum: `0` **oneOf** `[EnumOption\[\]](#enumoption) | null` Titled enum options for titled single-select enums. Must contain at least one option when present. Optional. Omitted and `null` are equivalent and mean no titled single-select choices are declared by `oneOf`. **pattern** `string | null` Pattern the string must match, in ECMA-262 regular expression syntax. Optional. Omitted and `null` are equivalent and mean there is no pattern constraint. * Format: `regex` **title** `string | null` Optional title for the property. Optional. Omitted and `null` are equivalent and mean no title is provided. ## SystemPrompt Client-provided system-level instructions for a session. Clients MUST only send this when the Agent advertises `session.systemPrompt`. Agents that cannot apply it, for example because of an unadvertised mode or an unsupported content block type, MUST return an error instead of creating or resuming the session. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **content** `[ContentBlock\[\]](#contentblock)` *required* The system prompt content. Agents advertising the capability MUST accept `text` content blocks. Clients MUST NOT send other content block types until a future capability allows them, and Agents MUST return an error for content blocks they do not support, including unknown types. Clients MUST NOT send an empty array. Agents MAY reject one with `-32602` without creating or resuming the session. **mode** `[SystemPromptMode](#systempromptmode)` *required* How the Agent combines `content` with its own instructions. Required. Agents MUST return an error for a mode they do not support rather than treating it as `append` or `override`. ## SystemPromptMode How the Agent combines a client-provided system prompt with its own instructions. Unknown modes are preserved so they can be stored, proxied, or forwarded. An Agent MUST return an error for a mode it does not support rather than treating it as `append` or `override`. **Type:** Union **append** `string` Add the content to the Agent's own instructions rather than replacing them. Every Agent that advertises `session.systemPrompt` supports this mode. Agents SHOULD give the content system-level precedence, for example in the model's system prompt or developer instructions rather than in user-turn content. Where it is placed and how it is formatted is implementation-defined. **override** `string` Replace the Agent's built-in default instructions with the content. This does not change tool availability, MCP servers, permissions, or session configuration. Context the Agent supplies from the workspace or environment MAY still be included. Clients that use this mode take responsibility for any tool guidance or safety instructions the Agent's default instructions provided, and MUST only use it when the Agent advertises `session.systemPrompt.mode.override`. **other** `string` Custom or future system prompt mode. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## Terminal A display-only reference to an agent-owned terminal. Terminal state and output are delivered separately through `terminal_update` and `terminal_output_chunk` session updates. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **terminalId** `[TerminalId](#terminalid)` *required* The ID of the terminal to display. ## TerminalAuthCapabilities Capabilities for terminal authentication methods. Supplying `\{\}` means the client can reproduce the configured agent invocation in an interactive terminal and supports terminal authentication methods. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ## TerminalCancelCapabilities Capability to cancel a terminal with `terminal/cancel`. Supplying `\{\}` advertises support. An omitted or `null` `cancel` does not. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ## TerminalCapabilities Client-initiated controls a terminal currently supports. A malformed value falls back to no controls, so the Client never sends a request the Agent did not advertise. See protocol docs: [Cancelling Terminals](https://agentclientprotocol.com/protocol/v2/tool-calls#cancelling-terminals) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **cancel** `[TerminalCancelCapabilities](#terminalcancelcapabilities) | null` Permits the Client to cancel this terminal with `terminal/cancel`. Omitted and `null` are equivalent and mean unsupported. An object (including `\{\}`) means supported. Agents SHOULD stop advertising it once the terminal reports `exitStatus`. ## TerminalExitStatus Exit information for an agent-owned terminal. The presence of this object marks the terminal as exited, even when neither an exit code nor a signal is known. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **exitCode** `integer | null` Process exit code as the platform reports it, when known. Negative values are allowed, for example signed Windows exit codes. Omitted and `null` are equivalent. **signal** `string | null` Signal that terminated the process, when known. Agents should use the conventional platform signal name. POSIX examples include `SIGTERM`, `SIGKILL`, and `SIGINT`. Other platforms may use a platform-specific name. Omitted and `null` are equivalent. ## TerminalId Unique identifier for an agent-owned terminal within a session. **Type:** `string` ## TerminalOutput An authoritative replacement snapshot of terminal output bytes. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **data** `string` *required* Base64-encoded replacement terminal output bytes. * Content encoding: `base64` ## TerminalOutputChunk A chunk of bytes appended to an agent-owned terminal's output. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. This metadata is scoped to the chunk and does not patch stored metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **data** `string` *required* Independently base64-encoded terminal output bytes. * Content encoding: `base64` **terminalId** `[TerminalId](#terminalid)` *required* The terminal receiving these bytes. ## TerminalSize The size of an agent-owned terminal in character cells. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **cols** `uint16` *required* Number of columns. | Constraint | Value | | - | - | | Minimum | `1` | | Maximum | `65535` | **rows** `uint16` *required* Number of rows. | Constraint | Value | | - | - | | Minimum | `1` | | Maximum | `65535` | ## TerminalUpdate An upsert for the stored state of an agent-owned terminal. Only `terminalId` is required. Other fields have patch semantics: omitted fields leave the stored value unchanged, `null` clears it, and concrete values replace it. A concrete `_meta` object instead patches the stored metadata by top-level key. When the terminal ID is new, omitted fields start unknown. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted leaves the stored metadata unchanged. `null` clears it. An object patches the stored metadata by top-level key: keys it omits are unchanged, a key set to `null` is removed, and any other value replaces that key's stored value without merging nested objects. Beyond this patch rule, implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches) **capabilities** `[TerminalCapabilities](#terminalcapabilities) | null` Client-initiated controls this terminal currently supports, such as cancellation. Omission leaves the capabilities unchanged, `null` clears them, and an object replaces the whole previous value. A new terminal starts with none. **command** `string | null` The command being run. **cwd** `[AbsolutePath](#absolutepath) | null` The absolute working directory of the command. **exitStatus** `[TerminalExitStatus](#terminalexitstatus) | null` Exit information. A concrete object marks the terminal as exited. **output** `[TerminalOutput](#terminaloutput) | null` An authoritative replacement snapshot of terminal output bytes. **size** `[TerminalSize](#terminalsize) | null` The terminal size the command runs with, when known. Clients can render output at this size so that column layouts, progress bars, and cursor-positioned output display as the program wrote them. **terminalId** `[TerminalId](#terminalid)` *required* Unique identifier for this terminal within the session. ## TextCommandInput All text that was typed after the command name is provided as input. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **hint** `string` *required* A hint to display when the input hasn't been provided yet ## TextContent Text provided to or from an LLM. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **annotations** `[Annotations](#annotations) | null` Optional annotations that help clients decide how to display or route this content. Omitted and `null` are equivalent and mean no annotations are provided. **text** `string` *required* Text payload carried by this content block. ## TextResourceContents Text-based resource contents. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **mimeType** `[MediaType](#mediatype) | null` MIME type describing the encoded media payload. Omitted and `null` are equivalent and mean the MIME type is not specified. **text** `string` *required* Text payload carried by this content block. **uri** `string` *required* URI associated with this resource or media payload. * Format: `uri` ## TitledMultiSelectItems Items definition for titled multi-select enum properties. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **anyOf** `[EnumOption\[\]](#enumoption)` *required* Titled enum options. Must contain at least one option. ## ToolCallCancelCapabilities Capability to cancel a tool call with `tool_call/cancel`. Supplying `\{\}` advertises support. An omitted or `null` `cancel` does not. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) ## ToolCallCapabilities Client-initiated controls a tool call currently supports. A malformed value falls back to no controls, so the Client never sends a request the Agent did not advertise. See protocol docs: [Cancelling Tool Calls](https://agentclientprotocol.com/protocol/v2/tool-calls#cancelling-tool-calls) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **cancel** `[ToolCallCancelCapabilities](#toolcallcancelcapabilities) | null` Permits the Client to cancel this tool call with `tool_call/cancel`. Omitted and `null` are equivalent and mean unsupported. An object (including `\{\}`) means supported. Agents SHOULD stop advertising it once the tool call reaches a final status. ## ToolCallContent Content produced by a tool call. Tool calls can produce different types of content including standard content blocks (text, images), file diffs, or display-only terminals. See protocol docs: [Content](https://agentclientprotocol.com/protocol/v2/tool-calls#content) **Type:** Union **content** `object` Standard content block (text, images, resources). **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **content** `[ContentBlock](#contentblock)` *required* The actual content block. **type** `string` *required* The discriminator value. Must be `"content"`. **diff** `object` File modification shown as a diff. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **changes** `[DiffChange\[\]](#diffchange)` *required* Structured file changes described by this diff. Clients can use this field without parsing patch text to determine affected paths. **patch** `[DiffPatch](#diffpatch) | null` Renderable patch text for some or all of the structured changes. Agents SHOULD provide patch text whenever feasible. Omitted and `null` are equivalent and mean no renderable patch text was provided. **type** `string` *required* The discriminator value. Must be `"diff"`. **terminal** `object` A display-only reference to an agent-owned terminal. **Properties** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **terminalId** `[TerminalId](#terminalid)` *required* The ID of the terminal to display. **type** `string` *required* The discriminator value. Must be `"terminal"`. **other** `object` Custom or future tool call content. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Receivers that do not understand this content type should preserve the raw payload when storing, replaying, proxying, or forwarding tool call output, and otherwise ignore it or display it generically. **Properties** **type** `string` *required* Custom or future tool call content type. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. ## ToolCallContentChunk A streamed item of tool-call content. Tool-call content chunks append one `ToolCallContent` item to the current content for the matching `toolCallId`. Agents can send a `tool_call_update` with `content` when they need to replace the whole content collection instead. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. This metadata is scoped to the chunk and does not patch stored metadata. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **content** `[ToolCallContent](#toolcallcontent)` *required* A single item of content produced by the tool call. **toolCallId** `[ToolCallId](#toolcallid)` *required* The ID of the tool call this content belongs to. ## ToolCallId Unique identifier for a tool call within a session. **Type:** `string` ## ToolCallLocation A file location being accessed or modified by a tool. Enables clients to implement "follow-along" features that track which files the agent is working with in real-time. See protocol docs: [Following the Agent](https://agentclientprotocol.com/protocol/v2/tool-calls#following-the-agent) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **line** `integer | null` Optional 1-based line number within the file. Omitted and `null` are equivalent and mean no specific line. `0` is invalid. * Minimum: `1` **path** `[AbsolutePath](#absolutepath)` *required* The absolute file path being accessed or modified. ## ToolCallPermissionSubject Permission request details for a tool call. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **toolCall** `[ToolCallUpdate](#toolcallupdate)` *required* Details about the tool call requiring permission. Clients apply this to their stored tool call exactly like a `tool_call_update` notification, in the order it was received, before showing the prompt. A first-seen `toolCallId` creates the tool call. ## ToolCallStatus Execution status of a tool call. Tool calls progress through different statuses during their lifecycle. See protocol docs: [Status](https://agentclientprotocol.com/protocol/v2/tool-calls#status) **Type:** Union **pending** `string` The tool call hasn't started running yet, for example because its input is streaming, it is awaiting approval, or it is scheduled to run later. **in\_progress** `string` The tool call is currently running. **paused** `string` The tool call has started, is not running now, and will not continue until something resumes it. It may return to `in_progress` any number of times. **completed** `string` The tool call completed successfully. **failed** `string` The tool call failed with an error. **cancelled** `string` The tool call was cancelled before it completed. **other** `string` Custom or future tool call status. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Clients treat a tool call with an unrecognized status as still in progress. ## ToolCallUpdate Represents an upsert for a tool call that the language model has requested. Tool calls are actions that the agent executes on behalf of the language model, such as reading files, executing code, or fetching data from external sources. Only `toolCallId` is required. Other fields have patch semantics: omitted fields leave the existing tool call value unchanged, `null` clears or unsets the value, and concrete values replace the previous value. For collection fields, concrete arrays replace the previous collection, and both `null` and `[]` clear the collection. A concrete `_meta` object instead patches the stored metadata by top-level key. When a client receives a tool call ID it has not seen before, omitted fields start at their protocol defaults. See protocol docs: [Tool Calls](https://agentclientprotocol.com/protocol/v2/tool-calls) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted leaves the stored metadata unchanged. `null` clears it. An object patches the stored metadata by top-level key: keys it omits are unchanged, a key set to `null` is removed, and any other value replaces that key's stored value without merging nested objects. Beyond this patch rule, implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches) **capabilities** `[ToolCallCapabilities](#toolcallcapabilities) | null` Client-initiated controls this tool call currently supports, such as cancellation. Omission leaves the capabilities unchanged, `null` clears them, and an object replaces the whole previous value. A new tool call starts with none. **content** `[ToolCallContent\[\]](#toolcallcontent) | null` Content produced by the tool call. **kind** `[ToolKind](#toolkind) | null` The category of tool being invoked. Helps clients choose appropriate icons and UI treatment. Omission leaves the kind unchanged, `null` resets it to `other`, and a value replaces it. A new tool call starts as `other`. **locations** `[ToolCallLocation\[\]](#toolcalllocation) | null` File locations affected by this tool call. Enables "follow-along" features in clients. **name** `string | null` Programmatic name of the tool being invoked. This field is optional and has patch semantics. Omission means no change, `null` clears the name, and a string replaces it. For a tool call ID the client has not seen before, omission or `null` means that no tool name is available. **rawInput** `object` Raw input parameters sent to the tool. **rawOutput** `object` Raw output returned by the tool. **status** `[ToolCallStatus](#toolcallstatus) | null` Current execution status of the tool call. Omission leaves the status unchanged, `null` resets it to `pending`, and a value replaces it. A new tool call starts as `pending`. **title** `string | null` Human-readable title describing what the tool is doing. Omission leaves the title unchanged, `null` unsets it, and a string replaces it. A new tool call starts without a title. **toolCallId** `[ToolCallId](#toolcallid)` *required* Unique identifier for this tool call within the session. ## ToolKind Categories of tools that can be invoked. Tool kinds help clients choose appropriate icons and optimize how they display tool execution progress. See protocol docs: [Reporting](https://agentclientprotocol.com/protocol/v2/tool-calls#reporting) **Type:** Union **read** `string` Reading files or data. **edit** `string` Modifying files or content. **delete** `string` Removing files or data. **move** `string` Moving or renaming files. **search** `string` Searching for information. **execute** `string` Running commands or code. **think** `string` Internal reasoning or planning. **fetch** `string` Retrieving external data. **switch\_mode** `string` Changing the session's mode, a [config option](https://agentclientprotocol.com/protocol/v2/session-config-options) with the `mode` category. **other** `string` Other tool types (default). **unknown** `string` Custom or future tool kind. Values beginning with `_` are reserved for implementation-specific extensions. Unknown values that do not begin with `_` are reserved for future ACP variants. Clients display an unrecognized kind as `other`. ## UnsupportedProtocolVersionErrorData Data for the `-32022` (Unsupported protocol version) error. See protocol docs: [Version Negotiation](https://agentclientprotocol.com/protocol/v2/initialization#version-negotiation) **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **requested** `[ProtocolVersion](#protocolversion)` *required* The protocol version the Client requested. **supported** `[ProtocolVersion\[\]](#protocolversion)` *required* The protocol versions the Agent supports. ## UsageUpdate Context window and cost update for a session. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. Implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) **cost** `[Cost](#cost) | null` Cumulative session cost. Omitted leaves the last reported cost unchanged. `null` clears it. A value replaces it. **size** `uint64` *required* Total context window size in tokens. * Minimum: `0` **used** `uint64` *required* Tokens currently in context. * Minimum: `0` ## UserMessage A user message upsert. Only `messageId` is required. `content` has patch semantics: an omitted field leaves existing message content unchanged, `null` clears the value, and a concrete array replaces the previous value. For a new `messageId`, omitted `content` starts empty. `content` is replaced as a whole array. Send `[]` or `null` to clear it. Message updates and chunks are applied in the order they are received. When a `user_message` update includes `content`, that array replaces any content previously accumulated for the message, including content from earlier chunks. Later chunks with the same `messageId` append to the current content. **Type:** Object **Properties:** **\_meta** `object | null` The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted leaves the stored metadata unchanged. `null` clears it. An object patches the stored metadata by top-level key: keys it omits are unchanged, a key set to `null` is removed, and any other value replaces that key's stored value without merging nested objects. Beyond this patch rule, implementations MUST NOT assign meaning to keys they do not recognize. See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches) **content** `[ContentBlock\[\]](#contentblock) | null` Complete replacement content for this message. **messageId** `[MessageId](#messageid)` *required* A unique identifier for the message. # Security Considerations Source: https://agentclientprotocol.com/protocol/v2/security Trust model and security guidance for Agents and Clients This page describes ACP's trust model and security guidance that spans features. Guidance for a single feature is on that feature's page. See [Feature Guidance](#feature-guidance). ## Trust Model * The Agent runs with whatever permissions its process is given. ACP itself does not sandbox it. * Files, web pages, tool results, and MCP servers can influence Agent output. Treat every Agent-authored string, URI, and path as untrusted, including replayed content. * Permission requests are advisory: the Agent performs operations and is responsible for honoring the user's decision. A Client cannot prevent an operation the Agent performs without asking. * `info` in `initialize` is self-reported. Implementations **SHOULD NOT** use it for security decisions, and Clients **SHOULD** identify the Agent from their own launch configuration. Out of scope: a malicious Agent binary, detecting prompt injection, and operating-system sandboxing. ## Rendering Agent content This applies to all Agent-authored display text, including messages, thoughts, tool calls, plans, commands, config options, notices, session titles, authentication methods, permission requests, and elicitations. * Clients **SHOULD NOT** run scripts from Agent content, and **SHOULD** disable or sanitize raw HTML when rendering Markdown. * Clients **SHOULD NOT** automatically run active content, such as diagram renderers, that can fetch resources or execute code. * Clients **SHOULD NOT** open links from Agent content without user action, and **SHOULD** show the full target and get user confirmation before handing a link with a scheme other than `http` or `https` to the operating system or another handler. * Clients **SHOULD** show the full link target when it differs from the link text. * Clients **SHOULD** reveal or remove bidirectional, zero-width, and tag characters in commands, paths, URLs, diffs, and permission requests. * Clients that print Agent text to a terminal **SHOULD** neutralize terminal control sequences in it. * Clients **SHOULD** keep Agent [slash commands](/protocol/v2/slash-commands) distinguishable from their own commands. * Clients **MAY** bound or throttle permission requests, elicitations, and output. ## URIs and remote resources This applies to `uri` on images, resource links, and embedded resources, to icon `src`, and to URLs in Markdown. * Clients **SHOULD** render images from `data` and **SHOULD NOT** fetch Agent-supplied remote URIs without user action. A request can leak data through its URL. * Icon `src` is the only URI a Client may fetch without user action. For icons, as in MCP, Clients **MUST** accept only `https:` and `data:` URIs and reject other schemes, including `file:`. They **MUST** fetch without credentials, **MUST NOT** follow redirects that change the scheme or origin, and **MUST** apply these checks to every redirect hop. Clients that display icons **MUST** support PNG and JPEG. * Automatic fetches **SHOULD** use only `https:` or `data:` URIs, **SHOULD NOT** carry credentials, **SHOULD** refuse loopback and private-network targets, and **SHOULD** bound the response size. * Clients **SHOULD NOT** run scripts in SVG images from Agent content. * Apart from icons, which never use `file:`, Clients **SHOULD NOT** read a `file:` URI from Agent content outside the session's [root set](/protocol/v2/session-setup#workspace-root-security) without user action. * Agents **SHOULD** apply the root set and these fetch rules to URIs in prompts. ## Credentials * Implementations **SHOULD NOT** put credentials in `_meta`, including `traceparent`, `tracestate`, and `baggage`. [Preserving unknown values](/protocol/v2/extensibility#enum-and-tagged-union-variants) does not require storing or replaying credentials. * Session, message, tool-call, and terminal IDs are not credentials. ## Prompt injection * Agents **SHOULD** treat embedded resources, files, tool results, and MCP results as data, not as user instructions. * Agents **SHOULD** request permission before sending data off the machine after reading untrusted content. * Agents **SHOULD** request permission before writing files that control execution or approval, such as version-control hooks, editor or Agent settings, and MCP configuration. * Clients **SHOULD NOT** open links, run commands, change settings, or send data based only on Agent-authored text. * A [system prompt](/protocol/v2/session-setup#system-prompt) carries more weight than user turns. Clients **SHOULD** only send content they trust at that level, and Agents **MAY** reject it. ## Intermediaries * An intermediary between the Client and the Agent, such as a proxy, can read and change every message, and each side treats it as the other. Clients **SHOULD** only use intermediaries the user trusts. * Intermediaries **SHOULD NOT** answer permission requests or elicitations for the user except under user-configured policy, and **SHOULD** forward `subject` unchanged. * An Agent serving more than one user **SHOULD** scope `session/list`, every request that names a session (such as `session/resume` and `session/delete`), permission requests, and elicitations to the user that owns the session. It treats another user's session as one that does not exist, so it is not listed, resuming it fails with `-32002`, and deleting it does nothing. Such an Agent **SHOULD** also authorize `cwd`, `additionalDirectories`, and `mcpServers` against the requesting user, and **SHOULD NOT** launch stdio MCP servers that user isn't permitted to run. ## Transports [Custom transports](/protocol/v2/transports#custom-transports) **SHOULD** document their security considerations, including how peers authenticate. ## Feature guidance * [Workspace roots](/protocol/v2/session-setup#workspace-root-security) * [Terminal authentication](/protocol/v2/authentication#launch-safety) * [MCP servers](/protocol/v2/session-setup#security) * [Permission requests](/protocol/v2/tool-calls#security) * [Display-only terminals](/protocol/v2/tool-calls#display-only-terminals) and [diffs](/protocol/v2/tool-calls#diffs) * [Elicitation](/protocol/v2/elicitation#user-interaction-requirements) and [URL security](/protocol/v2/elicitation#url-security) ## Residual risk A user can approve a harmful operation, prompt injection can steer operations the user allowed, and an Agent can act without asking. # Session Config Options Source: https://agentclientprotocol.com/protocol/v2/session-config-options Flexible configuration selectors for agent sessions Agents can provide an arbitrary list of configuration options for a session, which Clients show to users as selectors. Options can cover modes, models, model parameters, reasoning levels, and more. ## Initial state During [Session Setup](/protocol/v2/session-setup) the Agent **MAY** return a list of configuration options and their current values: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "sessionId": "sess_abc123def456", "configOptions": [ { "configId": "mode", "name": "Session Mode", "description": "Controls how the agent requests permission", "category": "mode", "type": "select", "currentValue": "ask", "options": [ { "value": "ask", "name": "Ask", "description": "Request permission before making any changes" }, { "value": "code", "name": "Code", "description": "Write and modify code with full tool access" } ] }, { "configId": "model", "name": "Model", "category": "model", "type": "select", "currentValue": "model-1", "options": [ { "value": "model-1", "name": "Model 1", "description": "The fastest model" }, { "value": "model-2", "name": "Model 2", "description": "The most powerful model" } ] }, { "configId": "context_size", "name": "Context Size", "category": "model_config", "type": "select", "currentValue": "200k", "options": [ { "value": "200k", "name": "200K" }, { "value": "1m", "name": "1M" } ] }, { "configId": "brave_mode", "name": "Brave Mode", "description": "Skip confirmation prompts and act autonomously", "type": "boolean", "currentValue": false } ] } } ``` **configOptions** `SessionConfigOption[]` The list of configuration options available for this session. The order of this array represents the Agent's preferred priority. Clients **SHOULD** respect this ordering when displaying options. ### SessionConfigOption **configId** `string` *required* Unique identifier for this configuration option. Used when setting values. **name** `string` *required* Human-readable label for the option **description** `string` Optional description providing more details about what this option controls **category** `SessionConfigOptionCategory` Optional [semantic category](#option-categories) to help Clients provide consistent UX. **type** `string` *required* The type of input control. `select` and `boolean` are supported. **currentValue** `string | boolean` *required* The current value for this option. For `select` options this is a string value ID. For `boolean` options this is a boolean. **options** `SessionConfigSelectOption[] | SessionConfigSelectGroup[]` The available values for a `select` option. Required when `type` is `"select"` and omitted when `type` is `"boolean"`. This is either a flat array of values or an array of groups. Values and groups are not mixed in the same array. For a `select` option, Agents **MUST** offer at least one value, **MUST** keep each `value` unique within the option, including across groups, and `currentValue` **MUST** be one of them. Each group **MUST** contain at least one value. Clients **SHOULD** hide a group that ends up empty, for example after skipping values they couldn't parse. ### SessionConfigSelectOption **value** `string` *required* The value identifier used when setting this option **name** `string` *required* Human-readable name to display **description** `string` Optional description of what this value does ### Grouped select options Select options may be grouped under labeled headers. Each `SessionConfigSelectGroup` requires `groupId`, `name`, and an `options` array containing the same `SessionConfigSelectOption` objects used by flat selects. A group's `_meta` is optional. Value descriptions and `_meta` remain optional as described above. ```json theme={null} { "options": [ { "groupId": "recommended", "name": "Recommended", "options": [ { "value": "model-1", "name": "Model 1", "description": "Fast for everyday tasks" } ] } ] } ``` ### Boolean config options Boolean config options use `type: "boolean"` for simple on/off toggles: ```json theme={null} { "configId": "brave_mode", "name": "Brave Mode", "description": "Skip confirmation prompts and act autonomously", "type": "boolean", "currentValue": true } ``` ## Option categories Each config option **MAY** include a `category` field. Categories are semantic metadata intended to help Clients provide consistent UX, such as attaching keyboard shortcuts, choosing icons, or deciding placement. > [!WARNING] > > Categories are for UX purposes only and **MUST NOT** be required for > correctness. Clients **MUST** handle missing or unknown categories gracefully. Category names beginning with `_` are free for custom use (e.g., `_com.example/category`). Category names that do not begin with `_` are reserved for the ACP spec. | Category | Description | | - | - | | `mode` | Session mode selector | | `model` | Model selector | | `model_config` | Model-related parameter, such as context size or speed/quality trade-off | | `thought_level` | Thought/reasoning level selector | Clients **SHOULD** render `model_config` options near the `model` selector, such as in the same popover or panel. No capability negotiation is required for category values. When multiple options share the same category, Clients **SHOULD** use the array ordering to resolve ties, preferring earlier options in the list for prominent placement or keyboard shortcuts. ## Option ordering The order of the `configOptions` array is significant. Agents **SHOULD** place higher-priority options first in the list. Clients **SHOULD**: * Display options in the order provided by the Agent * Use ordering to resolve ties when multiple options share the same category * If displaying a limited number of options, prefer those at the beginning of the list ## Default values and graceful degradation Every configuration option's `currentValue` is the value the Agent is using. It changes only through a `session/set_config_option` response or a `config_option_update` notification. Agents **MUST** be able to operate with it, even if: * The Client doesn't support configuration options * The Client chooses not to display certain options * The Client receives an option type it doesn't recognize Option `type` values can be custom or future variants. Custom option types **MUST** begin with `_`. Unknown non-underscore option types are reserved for future ACP variants. If a Client receives an option with an unrecognized `type`, it **SHOULD** preserve the raw option when storing, replaying, proxying, or forwarding session state, and otherwise ignore that option. The Agent keeps using its `currentValue`. ## Setting a config option The current value of a config option can be changed at any point during a session. Agents that advertise config options for a session **MUST** support `session/set_config_option` for it. Clients **MUST NOT** call it otherwise and **MUST** only send an advertised `configId`. Agents **MUST** reject an unknown `configId` or invalid value, including an unsupported value `type` or a `type` that doesn't match the option, with `-32602` and leave the configuration unchanged. Whether a change made while foreground work is active applies to that work or only to later work is up to the Agent. The response's `configOptions` is the complete list as of the response, and Clients replace their list with it. It may report a `currentValue` different from the one requested, for example when the Agent adjusted the value or another change applied concurrently. Clients apply responses and `config_option_update` notifications in the order received, each replacing the whole list. ### From the Client Clients can change a config option value by calling the `session/set_config_option` method: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "session/set_config_option", "params": { "sessionId": "sess_abc123def456", "configId": "mode", "type": "id", "value": "code" } } ``` **sessionId** `SessionId` *required* The ID of the session **configId** `string` *required* The `configId` of the configuration option to change **type** `"id" | "boolean"` *required* The shape of the value. Use `id` for `select` and other id-based options. Use `boolean` for boolean options. **value** `string | boolean` *required* The new value to set. For `select` options, this **MUST** be one of the values listed in the option's `options` array. For `boolean` options, this **MUST** be a boolean. For boolean options, Clients send `type: "boolean"` with a boolean `value`: ```json theme={null} { "jsonrpc": "2.0", "id": 3, "method": "session/set_config_option", "params": { "sessionId": "sess_abc123def456", "configId": "brave_mode", "type": "boolean", "value": true } } ``` The Agent **MUST** respond with the complete list of all configuration options and their current values: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "result": { "configOptions": [ { "configId": "mode", "name": "Session Mode", "description": "Controls how the agent requests permission", "category": "mode", "type": "select", "currentValue": "code", "options": [ { "value": "ask", "name": "Ask", "description": "Request permission before making any changes" }, { "value": "code", "name": "Code", "description": "Write and modify code with full tool access" } ] }, { "configId": "model", "name": "Model", "category": "model", "type": "select", "currentValue": "model-1", "options": [ { "value": "model-1", "name": "Model 1", "description": "The fastest model" }, { "value": "model-2", "name": "Model 2", "description": "The most powerful model" } ] }, { "configId": "context_size", "name": "Context Size", "category": "model_config", "type": "select", "currentValue": "200k", "options": [ { "value": "200k", "name": "200K" }, { "value": "1m", "name": "1M" } ] }, { "configId": "brave_mode", "name": "Brave Mode", "description": "Skip confirmation prompts and act autonomously", "type": "boolean", "currentValue": false } ] } } ``` > [!NOTE] > > The response always contains the **complete** configuration state, so Agents > can report dependent changes. For example, changing the model may change the > available reasoning options. ### From the Agent Agents **SHOULD** send a `config_option_update` session notification on each connection where the session is [active](/protocol/v2/session-setup#session-lifecycle) whenever configuration state changes, including changes requested through `session/set_config_option`. The response remains the source of truth for the requesting Client, which may also receive a duplicate notification. Agents **SHOULD** send that duplicate before the response and notifications for subsequent changes after it. ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "config_option_update", "configOptions": [ { "configId": "mode", "name": "Session Mode", "description": "Controls how the agent requests permission", "category": "mode", "type": "select", "currentValue": "code", "options": [ { "value": "ask", "name": "Ask", "description": "Request permission before making any changes" }, { "value": "code", "name": "Code", "description": "Write and modify code with full tool access" } ] }, { "configId": "model", "name": "Model", "category": "model", "type": "select", "currentValue": "model-2", "options": [ { "value": "model-1", "name": "Model 1", "description": "The fastest model" }, { "value": "model-2", "name": "Model 2", "description": "The most powerful model" } ] }, { "configId": "context_size", "name": "Context Size", "category": "model_config", "type": "select", "currentValue": "200k", "options": [ { "value": "200k", "name": "200K" }, { "value": "1m", "name": "1M" } ] }, { "configId": "brave_mode", "name": "Brave Mode", "description": "Skip confirmation prompts and act autonomously", "type": "boolean", "currentValue": false } ] } } } ``` This notification also contains the complete configuration state. Common reasons an Agent might update configuration options include: * Switching modes after the user approves a completed plan, or as the user's policy allows * Falling back to a different model due to rate limits or errors * Adjusting available options based on context discovered during execution # Session Delete Source: https://agentclientprotocol.com/protocol/v2/session-delete Removing sessions from session history The `session/delete` method lets Clients remove sessions from an Agent's `session/list` results, so users can clean up session history from any ACP Client. Before deleting sessions, Clients **MUST** first complete the [initialization](/protocol/v2/initialization) phase and verify the Agent supports this capability. ```mermaid theme={null} sequenceDiagram participant Client participant Agent Note over Agent,Client: Initialized Client->>Agent: session/list Agent-->>Client: session/list response (sessions) alt User deletes a session Client->>Agent: session/delete (sessionId) Agent-->>Client: session/delete response end Client->>Agent: session/list Agent-->>Client: session/list response (without deleted session) ``` ## Checking support Before attempting to delete a session, Clients **MUST** verify that the Agent supports this capability by checking the `session.delete` field in the `initialize` response: ```json highlight={7-9} theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 2, "capabilities": { "session": { "delete": {} } }, "info": { "name": "my-agent", "title": "My Agent", "version": "1.0.0" } } } ``` If `session.delete` is omitted or `null`, the Agent does not support deleting sessions and Clients **MUST NOT** attempt to call `session/delete`. Supplying `{}` means the Agent supports the method. ## Deleting a session Clients delete a session by calling `session/delete` with the session ID to remove from session history: ```json theme={null} { "jsonrpc": "2.0", "id": 3, "method": "session/delete", "params": { "sessionId": "sess_abc123def456" } } ``` **sessionId** `SessionId` *required* Unique identifier for the session to delete. On success, the Agent returns an empty result: ```json theme={null} { "jsonrpc": "2.0", "id": 3, "result": {} } ``` ## Semantics * Deleted sessions no longer appear in future `session/list` results. * Deleting an already-deleted session, or a session that never existed, **SHOULD** succeed silently. * Clients **SHOULD** treat a `-32002` response to `session/delete` as a successful delete. * Agents may implement soft delete or hard delete. ACP only specifies the user-facing session-list behavior. * Later requests for a deleted session, including `session/resume`, fail with `-32002`. See [Unknown Sessions](/protocol/v2/error#unknown-sessions). * If the session is active on any connection, the Agent **MUST** cancel its ongoing work and free its resources as if [`session/close`](/protocol/v2/session-setup#closing-active-sessions) had been called, then delete it. # Session List Source: https://agentclientprotocol.com/protocol/v2/session-list Discovering existing sessions The `session/list` method returns the sessions an Agent knows about. Clients use it to show session history and let users switch between sessions. Agents can also send a `session_info_update` notification when a session's title or metadata changes, so Clients don't have to poll. Before listing sessions, Clients **MUST** first complete the [initialization](/protocol/v2/initialization) phase. Agents that advertise `capabilities.session` **MUST** support `session/list`. ```mermaid theme={null} sequenceDiagram participant Client participant Agent Note over Agent,Client: Initialized Client->>Agent: session/list Agent-->>Client: session/list response (sessions) alt User selects a session Client->>Agent: session/resume (sessionId, replayFrom) Note over Agent,Client: Replay conversation history... Agent-->>Client: session/resume response end Note over Client,Agent: Ready for prompts ``` Agents that also advertise `session.additionalDirectories` may include `additionalDirectories` in returned `SessionInfo` objects to report additional workspace roots for listed sessions. > [!NOTE] > > If the Agent advertises the `session.delete` capability, Clients can remove > sessions from future `session/list` results with > [`session/delete`](/protocol/v2/session-delete). ## Listing sessions Clients discover existing sessions by calling the `session/list` method with optional filtering and pagination parameters: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "session/list", "params": { "cwd": "/home/user/project", "cursor": "eyJwYWdlIjogMn0=" } } ``` All parameters are optional. A request with an empty `params` object returns the first page of sessions. **cwd** `string` Filter sessions by working directory. Must be an absolute path. Agents reject a relative path with `-32602`. Only sessions whose `cwd` is this same directory are returned. Sessions in subdirectories or with it in `additionalDirectories` don't match. Agents **MAY** normalize paths when comparing, for example ignoring a trailing separator. **cursor** `string` Opaque cursor token from a previous response's `nextCursor` field for cursor-based pagination. See [Pagination](#pagination). The Agent **MUST** respond with a list of sessions and optional pagination metadata: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "result": { "sessions": [ { "sessionId": "sess_abc123def456", "cwd": "/home/user/project", "title": "Implement session list API", "updatedAt": "2025-10-29T14:22:15Z", "_meta": { "com.example/messageCount": 12, "com.example/hasErrors": false } }, { "sessionId": "sess_xyz789ghi012", "cwd": "/home/user/another-project", "title": "Debug authentication flow", "updatedAt": "2025-10-28T16:45:30Z" }, { "sessionId": "sess_uvw345rst678", "cwd": "/home/user/project", "updatedAt": "2025-10-27T15:30:00Z" } ], "nextCursor": "eyJwYWdlIjogM30=" } } ``` **sessions** `SessionInfo[]` *required* Array of session information objects. **SessionInfo** **sessionId** `string` *required* Unique identifier for the session. **cwd** `string` *required* Working directory for the session. Always an absolute path. **additionalDirectories** `string[]` If the Agent advertises `session.additionalDirectories`, it **MAY** include this field to report the complete ordered additional-root list associated with the listed session. Omitted and empty values are equivalent: this `SessionInfo` response reports no additional roots. Clients **MUST NOT** merge this field with prior values or infer additional roots from agent-specific state. **title** `string` Human-readable title for the session. May be auto-generated from the first prompt. **updatedAt** `string` RFC 3339 timestamp of the last activity in the session. **\_meta** `object` Agent-specific metadata. See [Extensibility](/protocol/v2/extensibility). **nextCursor** `string` Opaque cursor token. If present, pass this in the next request's `cursor` parameter to fetch the next page. Omitted and `null` are equivalent and mean there are no more results. When no sessions match the criteria, the Agent **MUST** return an empty `sessions` array. ## Pagination `session/list` uses cursor-based pagination. The request includes an optional `cursor`, and the response includes `nextCursor` when more results are available. * Clients **MUST** treat a missing `nextCursor` as the end of results. Only an omitted or `null` `nextCursor` ends the results. An empty string is a valid cursor * Clients **MUST NOT** assume a fixed page size * Clients **MUST** treat cursors as opaque tokens, which means not parsing, modifying, or persisting them * Agents **MUST** return `-32602` if the cursor is invalid * Agents **SHOULD** enforce reasonable page sizes internally ## Updating session metadata Agents **SHOULD** send a `session_info_update` notification via `session/update` on each connection where the session is [active](/protocol/v2/session-setup#session-lifecycle) whenever session metadata changes, including changes requested by a Client. The same response and notification ordering guidance as [`config_option_update`](/protocol/v2/session-config-options#from-the-agent) applies here. ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "session_info_update", "title": "Implement user authentication", "_meta": { "com.example/tags": ["feature", "auth"], "com.example/priority": "high" } } } } ``` All fields are optional. Only include fields that have changed. Omitted fields are left unchanged. Set a nullable field to `null` to clear it. **title** `string | null` Human-readable title for the session. Set to `null` to clear. **updatedAt** `string | null` RFC 3339 timestamp of last activity. Set to `null` to clear. **\_meta** `object | null` Agent-specific metadata patch. Omit to leave unchanged. Set to `null` to clear. An object patches the stored metadata by top-level key. See [Metadata Patches](/protocol/v2/extensibility#metadata-patches). The `sessionId`, `cwd`, and `additionalDirectories` fields are **not** included in the update. `sessionId` is already in the notification's `params`, `cwd` is immutable after session setup, and ACP does not currently define mid-session mutation for `additionalDirectories`. Agents typically send this notification after the first meaningful exchange to auto-generate a title. The Agent sends these updates on each connection where the session is [active](/protocol/v2/session-setup#session-lifecycle). Clients can refresh metadata for other sessions through `session/list`. ## Interaction with other session methods `session/list` only discovers sessions. It does **not** restore or modify them: 1. Client calls `session/list` to discover available sessions 2. User selects a session from the list 3. Client calls [`session/resume`](/protocol/v2/session-setup#resuming-sessions) with the chosen `sessionId` to resume the conversation, optionally setting `replayFrom` to request history replay # Session Setup Source: https://agentclientprotocol.com/protocol/v2/session-setup Creating and resuming sessions Sessions represent a specific conversation or thread between the [Client](/protocol/v2/overview#client) and [Agent](/protocol/v2/overview#agent). Each session has its own context, conversation history, and state, so one Agent can run several independent sessions. Before creating a session, Clients **MUST** first complete the [initialization](/protocol/v2/initialization) phase to establish protocol compatibility and capabilities. If the Agent requires authentication, session methods may fail with `auth_required` (`-32000`) until the Client completes the [authentication flow](/protocol/v2/authentication). ```mermaid theme={null} sequenceDiagram participant Client participant Agent Note over Agent,Client: Initialized alt Client->>Agent: session/new Note over Agent: Create session context Note over Agent: Connect to MCP servers Agent-->>Client: session/new response (sessionId) else Client->>Agent: session/resume (sessionId) Note over Agent: Restore session context Note over Agent: Connect to MCP servers opt replayFrom: start Note over Agent,Client: Replay conversation history... Agent->>Client: session/update Agent->>Client: session/update Note over Agent,Client: All content reported end Agent->>Client: "session/update (current state_update)" Agent-->>Client: session/resume response end Note over Client,Agent: Session active. Foreground state synchronized ``` ## Session lifecycle A session exists from `session/new` until the Agent discards it. Agents choose how long to keep sessions: for example, they may not store a session that was never prompted, may expire old sessions, or may remove one through [`session/delete`](/protocol/v2/session-delete). `session/list` and `session/resume` only see sessions the Agent still has, and resuming one it no longer has fails with `-32002`. On a connection, a session is **active** from a successful `session/new` or `session/resume` until `session/close` or the end of the connection. Agents **SHOULD NOT** discard a session while it is active, except through `session/delete`, which closes it first. * Session-scoped requests such as `session/prompt` and `session/set_config_option` require an active session. Otherwise the Agent responds with `-32002`. See [Unknown Sessions](/protocol/v2/error#unknown-sessions). Agents ignore `session/cancel` for a session that isn't active. * Closing a session ends it on the connection but doesn't discard it. Whether a closed session stays listed and resumable depends on how long the Agent keeps it. * Resuming a session that is already active on the connection synchronizes it again, like any resume. Ongoing work continues, and the request's MCP servers and workspace roots replace the previous ones. * Whether a session can be active on more than one connection at once is up to the Agent. An Agent that doesn't allow it **MAY** reject a `session/resume` for a session active on another connection, or end the session's activity on that other connection as if it were closed, for example when a Client reconnects before the Agent notices the old connection is gone. * When the connection ends, its sessions stop being active. The Agent **MAY** continue or cancel their foreground work. A later `session/resume` reports the outcome in its [current-state snapshot](#current-state-synchronization). ## Creating a session Clients create a new session by calling the `session/new` method with: * The [working directory](#working-directory) for the session * A list of [MCP servers](#mcp-servers) the Agent should connect to ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "session/new", "params": { "cwd": "/home/user/project", "mcpServers": [ { "type": "stdio", "name": "workspace-tools", "command": "/path/to/mcp-server", "args": ["--stdio"], "env": [] } ] } } ``` The Agent **MUST** respond with a unique [Session ID](#session-id) that identifies this conversation: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "sessionId": "sess_abc123def456" } } ``` ## Initial session state New sessions default to `idle` until a `state_update` reports otherwise. Updates may arrive before or after the `session/new` response. Clients **MUST NOT** overwrite an already-reported state when the response arrives. An optional initial idle notification is a snapshot, not a completed turn. Agents **SHOULD** put initial state in the `session/new` response, such as `configOptions` and `availableCommands`, rather than sending notifications before it. Agents **SHOULD NOT** send session-scoped requests, such as permission requests or elicitations, before the response, because the Client cannot yet show them for that session. While a `session/new` is pending, Clients **MAY** buffer notifications for a `sessionId` they don't recognize and apply them in order once the response arrives, or drop them. Agents cannot rely on such notifications being seen. `session/resume` does not imply idle: an existing session may still be running or waiting for user action. See [Current-State Synchronization](#current-state-synchronization). The `session/new` and `session/resume` responses carry the session's [configuration options](/protocol/v2/session-config-options) in `configOptions` and [available slash commands](/protocol/v2/slash-commands) in `availableCommands`. Because a setup response replaces the lists the Client holds, an Agent whose session has configuration options or commands **MUST** include them in that response. For example, a new session can return both: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "sessionId": "sess_abc123def456", "configOptions": [ { "configId": "brave_mode", "name": "Brave Mode", "description": "Skip confirmation prompts and act autonomously", "type": "boolean", "currentValue": false } ], "availableCommands": [ { "type": "command", "name": "test", "description": "Run tests for the current project" } ] } } ``` `configOptions` and `availableCommands` are optional. Each is the complete current list for the session: omission or `[]` means none, and empty lists are omitted when serializing. Agents **MUST NOT** send `null` for these fields. When a `session/new` or `session/resume` response arrives, Clients replace the lists they hold for the session with the response's lists, including lists from updates received before the response. Later `config_option_update` and `available_commands_update` notifications each replace the complete list, including `[]` to clear it. ## Resuming sessions Agents that advertise `capabilities.session` **MUST** support `session/resume`, which Clients use to reconnect to existing sessions. By default, resume restores the session context without replaying prior conversation history. Clients that need history replay can request it with `replayFrom`. To resume an existing session, Clients **MUST** call the `session/resume` method with: * The [Session ID](#session-id) to resume * [MCP servers](#mcp-servers) to connect to * The [working directory](#working-directory) * Optionally, a `replayFrom` cursor ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "session/resume", "params": { "sessionId": "sess_789xyz", "cwd": "/home/user/project", "mcpServers": [ { "type": "stdio", "name": "workspace-tools", "command": "/path/to/mcp-server", "args": ["--mode", "workspace"], "env": [] } ] } } ``` When `replayFrom` is omitted or `null`, the Agent **MUST NOT** replay the conversation history via `session/update` notifications before responding. It restores the session context, reconnects to the requested MCP servers, and returns once the session is active and its current foreground state has been synchronized. The required current-state snapshot is live synchronization, not history replay. Updates that report in-progress work, such as the content of a message that is still streaming, are live updates, not history replay. To request full history replay, Clients set `replayFrom` to `{ "type": "start" }`: Replay cursors are inclusive: replay includes the position identified by the cursor. For `{ "type": "start" }`, that means replaying all retained conversation history. ```json theme={null} { "jsonrpc": "2.0", "id": 3, "method": "session/resume", "params": { "sessionId": "sess_789xyz", "cwd": "/home/user/project", "replayFrom": { "type": "start" } } } ``` When `replayFrom.type` is `"start"`, the Agent **MUST** replay all retained conversation history to the Client in the form of `session/update` notifications before responding. The schema accepts custom and future `replayFrom.type` values so intermediaries can preserve them. An Agent that does not support the supplied cursor type **MUST** reject `session/resume` with `-32602` (Invalid params). It **MUST NOT** silently substitute another cursor or resume without replay. Malformed `replayFrom` values also result in `-32602`. ### Replay contents Replay reports retained history with the same updates and semantics as live delivery: messages, tool calls, [display terminals](/protocol/v2/tool-calls#display-only-terminals), plans, and [compactions](/protocol/v2/prompt-lifecycle#session-compaction). The Agent can replay each entity's updates or only its current state, for example a whole message instead of its chunks, or a terminal `output` snapshot instead of every output chunk. A replayed tool call whose work is no longer running or waiting **SHOULD** have a final status (`completed`, `failed`, or `cancelled`). Work that is still running after resuming keeps its live status and continues with live updates. Replay does not include: * Historical `state_update` notifications. See [Current-State Synchronization](#current-state-synchronization). * [Notices](/protocol/v2/prompt-lifecycle#session-notices), which are live-only and **SHOULD NOT** be replayed. If the condition is still relevant after resuming, the Agent may send a new notice. * Pending permission requests and elicitations. See [Current-State Synchronization](#current-state-synchronization). Agents need not replay historical `usage_update`, `session_info_update`, `config_option_update`, or `available_commands_update` notifications, since they describe past values rather than current ones. See [Current-State Synchronization](#current-state-synchronization). Agents are not required to persist every inserted user message or retain it for any minimum period. Live-only messages, including locally handled commands, may be absent from replay. A successful prompt response confirms insertion, not future availability in history. Absence from replay does not contradict it. For example, a user message from the conversation history: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_789xyz", "update": { "sessionUpdate": "user_message", "messageId": "msg_user_8f7a1", "content": [ { "type": "text", "text": "What's the capital of France?" } ] } } } ``` Followed by the agent's response: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_789xyz", "update": { "sessionUpdate": "agent_message", "messageId": "msg_agent_c42b9", "content": [ { "type": "text", "text": "The capital of France is Paris." } ] } } } ``` During replay, the Agent **MUST** include an opaque `messageId` for each replayed message, unique among messages of the same [type](/protocol/v2/prompt-lifecycle#entity-ids). A retained user message inserted by `session/prompt` **MUST** use the ID returned in that prompt response, including after reconnecting or restarting the Agent. Replaying a command reports its message. It does not execute the command again. Agents **SHOULD** preserve the IDs of all other replayed [entities](/protocol/v2/prompt-lifecycle#entity-ids), such as agent and thought message IDs, `toolCallId`, `terminalId`, `planId`, and `compactionId`, across replay when possible, but these IDs are not guaranteed to remain stable across reconnects or Agent restarts. Clients **MUST NOT** rely on them to deduplicate replay against previously received history. A full replay is authoritative: Clients **SHOULD** rebuild all of the session's entities, such as messages, tool calls, terminals, plans, and compactions, from it rather than merging it into existing state by ID. `user_message`, `agent_message`, and `agent_thought` updates are upserts keyed by `messageId`. Their `content` arrays replace the whole message content, while chunk updates with the same `messageId` append content. When replay reconstructs a message from its beginning using chunks, the Agent **MUST** first send the corresponding message update (`user_message`, `agent_message`, or `agent_thought`) with the same ID and `content: []`. This initializes or clears content under the ID used for that replay before replayed chunks append. It does not reconcile a message previously delivered under a different ID. A full-content message update can instead replace content under the replayed ID directly. Clients apply replayed message updates and chunks in the order they are received. If a message update with `content` arrives after chunks for the same `messageId`, it replaces the content accumulated from those chunks. If chunks arrive after a message update, they append to that update's current content. Message updates that omit `content` can update other optional fields without changing the current content. Replay also applies top-level `_meta` as a [metadata patch](/protocol/v2/extensibility#metadata-patches) and does not reset it. A message update that replaces `content` leaves `_meta` keys it does not mention. When the Client may already hold metadata for an entity, the Agent removes stale keys by setting them to `null`, or sends `_meta: null` before the current object. When all requested replay entries have been reported to the Client, the Agent **MUST** synchronize current state as described below, then respond to the original `session/resume` request. ```json theme={null} { "jsonrpc": "2.0", "id": 3, "result": {} } ``` The response also includes the current `configOptions` and `availableCommands` as described in [Initial Session State](#initial-session-state), whether or not history replay was requested. ### Current-state synchronization For every successful resume, the Agent **MUST** send a current [`state_update`](/protocol/v2/prompt-lifecycle#session-states) after any requested history replay and before the resume response. This is required even when `replayFrom` is omitted or `null`. The snapshot reports the current foreground state after resuming: `idle`, `running`, or `requires_action`. The snapshot carries the [`background`](/protocol/v2/prompt-lifecycle#background-work) list like any other. Before it, the Agent **MUST** send a current update for each listed item that the requested replay did not already deliver at its current state: a `terminal_update` for each terminal, a `tool_call_update` for each tool call. When no replay was requested, this means all of them. Agents **MUST NOT** replay historical `state_update` notifications as current activity. The snapshot and subsequent live state changes **MUST** be delivered in order, without replacing a newer state with a stale snapshot. An idle snapshot may include the last stop reason for context, but does not report a new completion or cancellation. Clients **MUST NOT** reset the state to idle on the resume response. If connection loss made a pending permission request or elicitation unusable, the Agent **SHOULD** reestablish it or safely resolve the wait. Agents **SHOULD** also send current session info through `session_info_update` after any requested history replay and before responding, even when `replayFrom` is omitted or `null`. This synchronizes current state rather than replaying historical configuration or metadata changes. Agents that report usage **MAY** likewise send a current `usage_update` after any requested history replay and before responding. ## Closing active sessions Agents that advertise `capabilities.session` **MUST** support `session/close`, which tells the Agent to cancel any ongoing work for a session and free any resources associated with that active session. To close an active session, Clients **MUST** call the `session/close` method with the session ID: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "session/close", "params": { "sessionId": "sess_789xyz" } } ``` **sessionId** `SessionId` *required* The ID of the active session to close. The Agent **MUST** cancel any ongoing work for that session as if [`session/cancel`](/protocol/v2/prompt-lifecycle#cancellation) had been called, then free the resources associated with the session. Before responding to `session/close`, the Agent **MUST** cancel every pending permission request and [elicitation](/protocol/v2/elicitation#session-cancellation) scoped to that session with `$/cancel_request`. Unlike cancellation, closing also stops the session's background work, including everything in the latest [`background`](/protocol/v2/prompt-lifecycle#background-work) list. After a successful close, the Client **SHOULD** treat every listed tool call, and every tool call that references a listed terminal, that has not reported a final status as `cancelled`, and every listed terminal without `exitStatus` as exited with no known exit status. The Agent **MAY** send final updates for listed work before responding, but does not have to. When closing cancels active foreground work, the Agent **MUST** send the final updates for that work and the idle `state_update` with `stopReason: "cancelled"` before responding successfully to `session/close`. Closing an idle session does not itself require another idle update. Closing also cancels pending `session/prompt` requests whose messages have not been inserted, including [held prompts](/protocol/v2/prompt-lifecycle#prompts-during-active-work). If closing prevents a prompt's user message from being inserted, the Agent **MUST** answer that request with `-32800` (Request Cancelled). If the message has already been inserted, the Agent **MUST** respond successfully with its `messageId`, as described in [Prompt Accepted](/protocol/v2/prompt-lifecycle#2-prompt-accepted). Prompt responses need not precede the close response. After the close response, the Agent sends no other messages for the session on that connection. On success, the Agent responds with an empty result object: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "result": {} } ``` Closing is idempotent. If the session does not exist or is not active, for example because it was already closed, the Agent **SHOULD** respond with the same empty result. Clients **SHOULD** treat a `-32002` response to `session/close` as a successful close. See [Unknown Sessions](/protocol/v2/error#unknown-sessions). ## Additional workspace roots Agents that advertise `session.additionalDirectories` allow Clients to include `additionalDirectories` on supported session lifecycle requests to expand the session's effective workspace root set. The supported stable requests are `session/new` and `session/resume`. ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "session/resume", "params": { "sessionId": "sess_789xyz", "cwd": "/home/user/project", "additionalDirectories": [ "/home/user/shared-lib", "/home/user/product-docs" ] } } ``` When present, `additionalDirectories` has the following behavior: * `cwd` remains the primary working directory and the base for relative paths * each `additionalDirectories` entry **MUST** be an absolute path * omitting the field or providing an empty array activates no additional roots for the resulting session * on `session/resume`, Clients **MUST** send the full intended additional-root list again. That list may differ from any previous or reported list as long as the request `cwd` matches the session's `cwd`, and omitting the field or providing an empty array does not restore stored roots implicitly Clients **MUST** only send `additionalDirectories` when the Agent advertises `session.additionalDirectories`. Agents that advertise the capability **MUST** reject a request with `-32602` if any entry is not an absolute path, and **MAY** reject entries that don't exist or aren't directories. Agents **MAY** ignore duplicate entries and entries equal to `cwd`, so the list reported in [`SessionInfo`](/protocol/v2/session-list) can differ from the request. Agents that don't advertise the capability ignore the field. ## System prompt Agents that advertise `session.systemPrompt` allow Clients to include system-level instructions on `session/new` and `session/resume`. ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "session/new", "params": { "cwd": "/home/user/project", "systemPrompt": { "mode": "append", "content": [ { "type": "text", "text": "You are a code review specialist. Focus on security issues." } ] } } } ``` `systemPrompt` has the following behavior: * `mode` is required and selects how the Agent combines `content` with its own instructions * `mode` values beginning with `_` are reserved for implementation-specific modes, and other unknown values for future ACP modes. Clients **MUST** only use a mode the Agent advertised. An Agent that receives a mode it does not support **MUST** return an error rather than treating it as `append` or `override` * `append` adds `content` to the Agent's own instructions rather than replacing them. The Agent **SHOULD** give it system-level precedence, for example in the model's system prompt or developer instructions rather than in user-turn content. Where it is placed and how it is formatted is up to the Agent * `override` replaces the Agent's built-in default instructions. It does not change tool availability, MCP servers, permissions, or session configuration. Context the Agent supplies from the workspace or environment, such as `AGENTS.md` files or skill listings, **MAY** still be included, and Agents **SHOULD** document what they keep. Clients that use `override` take responsibility for any tool guidance or safety instructions the Agent's default instructions provided * only `text` content blocks are supported for now: Agents **MUST** accept them, and Clients **MUST NOT** send other content block types until a future capability allows them. Agents **MUST** return an error for content blocks they do not support, including unknown types * Clients **MUST NOT** send an empty `content` array. Agents **MAY** reject one with `-32602` without creating or resuming the session * omitting the field or setting it to `null` on `session/new` means the Agent uses its default instructions * on `session/resume`, Clients **SHOULD** send the same `systemPrompt` they used when the session was created. When it is omitted, the Agent may keep a prompt it stored with the session or use its default. When it differs, the Agent **SHOULD** apply it, and **MAY** defer the change until it next rebuilds its prompt (for example, after compaction) when applying it immediately would discard prompt caches or preserved reasoning * if the Agent cannot apply a supplied `systemPrompt`, for example because of an unadvertised mode, an unsupported content block type, or content that exceeds its limits, it **MUST** return an error and **MUST NOT** create or resume the session. JSON-RPC `-32602` (Invalid params) is the **RECOMMENDED** error for malformed or unsupported values Clients **MUST** only send `systemPrompt` when the Agent advertises `session.systemPrompt`, and **MUST** only use `override` mode when the Agent also advertises `session.systemPrompt.mode.override`: ```json highlight={8-10} theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 2, "capabilities": { "session": { "systemPrompt": { "mode": { "override": {} } } } }, "info": { "name": "my-agent", "title": "My Agent", "version": "1.0.0" } } } ``` Content delivered at system level carries more weight with the model than user turns or tool output. Clients **SHOULD** only send content they trust at that level. ## Session ID The session ID returned by `session/new` is a unique identifier for the conversation context. Clients use this ID to: * Send prompt requests via `session/prompt` * Cancel foreground work via `session/cancel` * Resume previous sessions via `session/resume` * Close active sessions via `session/close` ## Working directory The `cwd` (current working directory) parameter establishes the primary file system context for the session. This directory: * **MUST** be an absolute path. Agents reject a request with a relative `cwd` with `-32602`. * **MUST** be used for the session regardless of where the Agent subprocess was spawned * **MUST** remain the base for relative-path resolution * **MUST** be part of the session's effective root set On `session/resume`, Clients **MUST** send the session's working directory. Agents **MAY** reject a different directory with `-32602`. Agents **MAY** normalize paths when comparing, for example ignoring a trailing separator. When `session.additionalDirectories` is in use, the session's effective root set is `[cwd, ...additionalDirectories]`. This root set **SHOULD** serve as a boundary for tool operations on the file system. ### Workspace root security The root set declares the session's scope. It confines shell commands only when a sandbox enforces it. * Clients **SHOULD** only include directories the user expects the Agent to access, such as the workspace or directories the Client provides, like skills. * Agents **SHOULD NOT** treat model output, Agent content, or replayed history as granting access outside the root set. Access outside it goes through a permission request. * Implementations that enforce the root set **SHOULD** check the resolved path at the time of use, compare paths by component, and fail closed. ## MCP servers The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) allows Agents to access external tools and data sources. When creating a session, Clients **MAY** include connection details for MCP servers that the Agent should connect to. MCP servers can be connected to using different transports. Agents advertise supported transports during initialization using `session.mcp.stdio`, `session.mcp.http`, and any extension-specific transport capabilities. Agents **MUST** reject a request with a transport they don't support with `-32602`, including a transport they did not advertise and v1's `sse`. Each server `name` **MUST** be unique within `mcpServers`. Agents reject duplicates with `-32602`. On `session/resume`, `mcpServers` is the complete set of Client-provided servers for the session. Omitted and `[]` mean none. Agents **SHOULD NOT** restore servers from earlier `session/new` or `session/resume` requests. MCP servers the Agent is configured with independently of ACP are unaffected. ### Transport types Every MCP server object has a `type` discriminator that identifies its transport. Custom implementation-specific transport types **MUST** begin with `_`. Unknown non-underscore transport types are reserved for future ACP variants. #### Stdio transport When the Agent supports `session.mcp.stdio`, Clients can specify MCP servers configurations using the stdio transport. **type** `string` *required* Must be `"stdio"` to indicate stdio transport **name** `string` *required* A human-readable identifier for the server **command** `string` *required* The absolute path to the MCP server executable **args** `array` Command-line arguments to pass to the server. Omitted and empty values are equivalent. **env** `EnvVariable[]` Environment variables to set when launching the server. Omitted and empty values are equivalent. **EnvVariable** **name** `string` *required* The name of the environment variable. **value** `string` *required* The value of the environment variable. Example stdio transport configuration: ```json theme={null} { "type": "stdio", "name": "workspace-tools", "command": "/path/to/mcp-server", "args": ["--stdio"], "env": [ { "name": "API_KEY", "value": "secret123" } ] } ``` Agents **SHOULD** launch stdio servers with the session's `cwd` as the working directory. `env` entries are added to the environment the Agent would otherwise give the process, replacing variables with the same name. Each `env` entry **SHOULD** have a unique `name`. Agents **MAY** reject duplicates with `-32602`. Otherwise the last entry with a given name wins. #### HTTP transport When the Agent supports `session.mcp.http`, Clients can specify MCP servers configurations using the HTTP transport. **type** `string` *required* Must be `"http"` to indicate HTTP transport **name** `string` *required* A human-readable identifier for the server **url** `string` *required* The URL of the MCP server **headers** `HttpHeader[]` HTTP headers to include in requests to the server. Omitted and empty values are equivalent. Headers that the MCP transport itself defines, such as `Accept` and `MCP-Protocol-Version`, are owned by the transport: Agents use the transport's values for them. **HttpHeader** **name** `string` *required* The name of the HTTP header. **value** `string` *required* The value to set for the HTTP header. Example HTTP transport configuration: ```json theme={null} { "type": "http", "name": "api-server", "url": "https://api.example.com/mcp", "headers": [ { "name": "Authorization", "value": "Bearer token123" } ] } ``` ### Checking transport support Before using stdio or HTTP transports, Clients **MUST** verify the Agent's capabilities during initialization: ```json highlight={7-10} theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 2, "capabilities": { "session": { "mcp": { "stdio": {}, "http": {} } } }, "info": { "name": "my-agent", "title": "My Agent", "version": "1.0.0" } } } ``` If `session.mcp.stdio` is omitted or `null`, the Agent does not support stdio transport. If `session.mcp.http` is omitted or `null`, the Agent does not support HTTP transport. Supplying `{}` means the Agent supports the corresponding transport. Agents **SHOULD** connect to all MCP servers specified by the Client. If a server fails to launch or connect, the Agent either fails the request or continues without that server. If it continues, it **SHOULD** tell the user, for example with a [notice](/protocol/v2/prompt-lifecycle#session-notices). Clients **MAY** use this ability to provide tools directly to the underlying language model by including their own MCP server. ### Security MCP server configurations can launch processes, and their `env` and `headers` values are credentials. * Agents **SHOULD** launch `command` with `args` as separate arguments, without a shell. * Clients **SHOULD NOT** send a stdio server from workspace files or Agent output until the user has approved its exact command, arguments, and environment variable names. * Agents **SHOULD NOT** include `env` or `headers` values in session updates, errors, `_meta`, `session/list` results, replayed history, model context, or command lines, and **SHOULD NOT** log or persist them. * Agents **SHOULD** send `headers` only to the configured origin. * Clients that persist `mcpServers` **SHOULD** keep credentials in operating-system secret storage and **SHOULD NOT** log them. # Slash Commands Source: https://agentclientprotocol.com/protocol/v2/slash-commands Advertise available slash commands to clients Agents can advertise a set of slash commands that users can invoke. These commands provide quick access to specific agent capabilities and workflows. Commands are run as part of regular [prompt](/protocol/v2/prompt-lifecycle) requests where the Client includes the command text in the prompt. ## Advertising commands ### Initial commands An Agent with commands **MUST** include them in `availableCommands` in the `session/new` and `session/resume` responses, alongside `configOptions` when supported, since a setup response replaces the Client's command list. This lets the Client display commands as soon as [session setup](/protocol/v2/session-setup#initial-session-state) completes, without requiring an `available_commands_update` notification before the `session/new` response. For example, a `session/new` response can advertise a command with text input: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "sessionId": "sess_abc123def456", "availableCommands": [ { "type": "command", "name": "web", "description": "Search the web for information", "input": { "type": "text", "hint": "query to search for" } } ] } } ``` **availableCommands** `AvailableCommand[]` Optional complete list of commands available in this session. Omission or `[]` means none, and Clients replace any list they hold with it. Empty lists are omitted when serializing setup responses. `null` is not a valid outbound value for this field. ### Notifications After session setup, the Agent **MAY** announce commands that were not included in the response, or update the list, via the `available_commands_update` session notification: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "available_commands_update", "availableCommands": [ { "type": "command", "name": "web", "description": "Search the web for information", "input": { "type": "text", "hint": "query to search for" } }, { "type": "command", "name": "test", "description": "Run tests for the current project" }, { "type": "command", "name": "plan", "description": "Create a detailed implementation plan", "input": { "type": "text", "hint": "description of what to plan" } } ] } } } ``` The notification's `availableCommands` array is the complete replacement list, not a delta. An empty array clears all advertised commands. ### AvailableCommand Each command carries a required `type` discriminator. Currently the only type is `command`, a slash command the user invokes by including it in a prompt. **type** `string` *required* The kind of command. Currently always `"command"`. **name** `string` *required* The command name without the leading `/`, such as `web`, `test`, or `plan`. **MUST NOT** contain whitespace and **MUST** be unique within the list. **description** `string` *required* Human-readable description of what the command does **input** `AvailableCommandInput` Optional input specification for the command Command entries can add custom or future `type` values. Custom command types **MUST** begin with `_`. Unknown non-underscore command types are reserved for future ACP variants. Every command type carries `name` and `description`. Clients that don't understand a command type should preserve it when storing, replaying, proxying, or forwarding command metadata, and otherwise either ignore it or display it as a plain command using its `name` and `description`. Entries without a `type`, or with a known `type` that doesn't match its schema, are invalid and are skipped like any other invalid command item. ### AvailableCommandInput Currently supports text input with `type: "text"`: **hint** `string` *required* A hint to display when the input hasn't been provided yet Command input specifications can add custom or future `type` values. Custom input types **MUST** begin with `_`. Unknown non-underscore input types are reserved for future ACP variants. Clients that cannot render an input specification should preserve it when storing, replaying, proxying, or forwarding command metadata, and otherwise display the command without structured input. ## Dynamic updates The Agent can update the list of available commands at any time during a session by sending another `available_commands_update` notification. Each notification replaces the list previously advertised in a setup response or notification, including `[]` to clear it. Agents can use this to add commands as context changes, remove commands that no longer apply, or update descriptions. ## Running commands Commands are included as regular user messages in prompt requests: ```json theme={null} { "jsonrpc": "2.0", "id": 3, "method": "session/prompt", "params": { "sessionId": "sess_abc123def456", "prompt": [ { "type": "text", "text": "/web agent client protocol" } ] } } ``` A prompt invokes a command when its first text block starts with `/` followed by the command `name`. The Agent decides how to interpret the prompt. Clients recognizing a command for highlighting or completion **SHOULD** require the name to be followed by whitespace or the end of the text block, so `/web foo` matches `web`, `/webfoo` does not, and `/web-search foo` matches `web-search`, not `web`. The rest of that text block, after the name and the whitespace following it, is the command's input. Text naming a command the Agent did not advertise is an ordinary prompt. Commands may be accompanied by any other user message content types (images, audio, etc.) in the same prompt array. The same [prompt insertion contract](/protocol/v2/prompt-lifecycle#2-prompt-accepted) applies to commands: the successful response returns the inserted user message's `messageId`, and the Agent reports that message through a `user_message` update or `user_message_chunk` updates with the same ID. If a command is handled locally and the runtime does not record it, the adapter inserts a live-only user message into the ACP conversation. It need not wait for a runtime insertion event or keep a permanent transcript entry. If the command is retained and replayed later, it uses the same message ID and is not executed again. For example, an adapter can report a locally handled `/compact` as a live-only user message containing `/compact`, even if the runtime records only a summary. The ACP user message represents the command invocation. It need not match the runtime's transcript or expanded instructions. Local handling still uses the [foreground lifecycle](/protocol/v2/prompt-lifecycle#work-boundaries-and-local-commands). From idle, the Agent **MUST** report an active state for command handling and `idle` when no foreground work remains, even if no model call or tool invocation occurs. A command with no user-action wait uses `running` → `idle`, and **SHOULD** include `stopReason: "end_turn"` for successful completion. Completing an individual command while other foreground activity continues does not require an idle boundary. # Tool Calls Source: https://agentclientprotocol.com/protocol/v2/tool-calls How Agents report tool call execution Tool calls are actions the language model asks the Agent to perform during a [session](/protocol/v2/prompt-lifecycle), such as reading a file or running a command. The Agent executes them on the model's behalf. Agents report tool calls through [`session/update`](/protocol/v2/prompt-lifecycle#3-agent-reports-output) notifications, which Clients use to show progress and results to users. Tool call updates may arrive while the Agent reports `idle`. They do not change the state. Agents may ask the user for approval before running a tool call. See [Requesting Permission](#requesting-permission). ## Reporting When the language model requests a tool invocation, the Agent **SHOULD** report it to the Client with a `tool_call_update`: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "tool_call_update", "toolCallId": "call_001", "title": "Reading configuration file", "name": "read_file", "kind": "read", "status": "pending" } } } ``` **toolCallId** `ToolCallId` *required* A unique identifier for this tool call within the session **title** `string` A human-readable title describing what the tool is doing. Agents **SHOULD** include the title the first time they report a `toolCallId`. **name** `string` The programmatic name of the invoked tool, such as `read_file`. This identifies which tool is being used. `title` describes this invocation for users, while `kind` provides a coarse presentation category. Agents **SHOULD** include the name the first time they report a `toolCallId` when it is available and **SHOULD NOT** change it later except to correct metadata. Names are opaque, informational metadata and do not advertise a capability or grant authorization. **kind** `ToolKind` The category of tool being invoked. **kinds** * `read` - Reading files or data * `edit` - Modifying files or content * `delete` - Removing files or data * `move` - Moving or renaming files * `search` - Searching for information * `execute` - Running commands or code * `think` - Internal reasoning or planning * `fetch` - Retrieving external data * `switch_mode` - Changing the session's mode, a [config option](/protocol/v2/session-config-options) with the `mode` category * `other` - Other tool types (default) Tool kinds help Clients choose appropriate icons and optimize how they display tool execution progress. Custom or future tool kinds can be used when Clients can fall back to generic tool display behavior. Custom tool kinds **MUST** begin with `_`. Unknown non-underscore tool kinds are reserved for future ACP variants. Clients display a tool kind they don't recognize as `other`. **status** `ToolCallStatus` The current [execution status](#status) (defaults to `pending`) **content** `ToolCallContent[]` [Content produced](#content) by the tool call **locations** `ToolCallLocation[]` [File locations](#following-the-agent) affected by this tool call **rawInput** `unknown` The raw input sent to the tool. It may be any JSON value, including an object, array, scalar, or `null`. **rawOutput** `unknown` The raw output returned by the tool. It may be any JSON value, including an object, array, scalar, or `null`. The `tool_call_update` notification is an upsert keyed by `toolCallId`. For existing tool calls, fields other than `_meta` leave the previous value unchanged when omitted, reset the field to its default when `null`, and replace the previous value when concrete values are sent. A new `toolCallId` starts with every field at its default: `status` is `pending`, `kind` is `other`, `content` and `locations` are empty, and `title`, `name`, `rawInput`, and `rawOutput` are unset. Clients can show a generic title when `title` is unset. `content` and `locations` are replaced as whole arrays. Send `[]` or `null` to clear them. For `_meta`, omit the field to leave it unchanged or set it to `null` to clear it. An object patches the stored metadata by top-level key: a key set to `null` is removed, any other value replaces that key whole, and keys the object omits are unchanged. See [Metadata Patches](/protocol/v2/extensibility#metadata-patches). Use `tool_call_content_chunk` when a tool produces content incrementally and the Client should append each item instead of replacing the whole `content` collection. Display-only terminal bytes use `terminal_output_chunk` instead. `rawInput` and `rawOutput` follow the same patch rule, even though `null` is also a valid arbitrary JSON value: omission leaves the stored value unchanged, `null` clears it, and any non-null JSON value replaces it. Consequently this patch representation cannot distinguish storing a literal JSON `null` from clearing the field. The Agent **MAY** also report a tool call that the model did not request, for [background work](/protocol/v2/prompt-lifecycle#background-work) that has no other tool call. ## Updating As tools execute, Agents send updates to report progress and results. ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "tool_call_update", "toolCallId": "call_001", "status": "in_progress", "content": [ { "type": "content", "content": { "type": "text", "text": "Found 3 configuration files..." } } ] } } } ``` All fields except `toolCallId` are optional in updates. Only the fields being changed need to be included. ## Streaming content As tools execute, Agents **MAY** stream individual content items with `tool_call_content_chunk`: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "tool_call_content_chunk", "toolCallId": "call_001", "content": { "type": "content", "content": { "type": "text", "text": "Found 3 configuration files..." } } } } } ``` **toolCallId** `ToolCallId` *required* The ID of the tool call this content belongs to **content** `ToolCallContent` *required* A single [content item](#content) produced by the tool call Clients apply `tool_call_update` and `tool_call_content_chunk` notifications in the order they are received for each `toolCallId`. A `tool_call_content_chunk` appends its `content` item to the current tool-call content. A later `tool_call_update` with `content` replaces all content currently stored for that tool call, including content accumulated from earlier chunks. Later chunks append to that replacement content. A `tool_call_update` with `content: []` or `content: null` clears the tool-call content. A `tool_call_content_chunk`'s `_meta`, when present, is chunk-scoped. A chunk for a `toolCallId` the Client hasn't seen creates the tool call with its [defaults](#reporting), then appends to its content. An Agent can stream a tool's text output the way it streams message text, by sending each piece as a text content item in its own `tool_call_content_chunk`. Clients can present adjacent text items as one continuous text. ## Requesting permission Permission requests do not by themselves change the session's foreground state. While foreground work is blocked on a permission response, the Agent **SHOULD** report `requires_action`. Once reported, it **MUST** report `running` when foreground progress resumes, or `idle` if the work ends without resuming. Requests for independent background activity may arrive while the session remains `idle`. See [Waiting for User Action](/protocol/v2/prompt-lifecycle#waiting-for-user-action) for concurrent requests and late answers. The Agent **MAY** request permission from the user before proceeding with an operation, such as executing a tool call, by calling the `session/request_permission` method: ```json theme={null} { "jsonrpc": "2.0", "id": 5, "method": "session/request_permission", "params": { "sessionId": "sess_abc123def456", "title": "Approve file edit?", "description": "Allow the agent to edit src/main.rs?", "subject": { "type": "tool_call", "toolCall": { "toolCallId": "call_001" } }, "options": [ { "optionId": "allow-once", "name": "Allow once", "kind": "allow_once" }, { "optionId": "reject-once", "name": "Reject", "kind": "reject_once" } ] } } ``` **sessionId** `SessionId` *required* The session ID for this request **title** `string` *required* Title shown with the permission prompt. This text is separate from any `toolCall` update and does not replace the tool-call title. **description** `string` Optional explanation shown with the permission prompt. This text is separate from any `toolCall` update and does not replace tool-call content. Omitted or `null` means no separate permission description was provided. **subject** `RequestPermissionSubject` Optional structured context about the operation requiring permission. For tool calls, use `type: "tool_call"` with a `toolCall` update containing details about the operation. Omitted or `null` means no structured subject was provided. Custom or future subject types may appear. Clients that do not understand a subject **SHOULD** preserve it when proxying and use the common prompt fields or decline according to policy with the `cancelled` outcome. A permission request for listed [background work](/protocol/v2/prompt-lifecycle#background-work) **SHOULD** reference the listed item in `subject`, by `toolCallId` or `terminalId`. The Agent **MUST** list that work before sending the request. `session/cancel` does not cover listed work, so these requests stay open. See [Cancellation](/protocol/v2/prompt-lifecycle#cancellation). Clients apply a `tool_call` subject's `toolCall` to their stored tool call exactly like a [`tool_call_update`](#reporting) notification, in the order it was received relative to `session/update` notifications and before showing the prompt. A first-seen `toolCallId` creates the tool call. **options** `PermissionOption[]` *required* Available [permission options](#permission-options) for the user to choose from. Must contain at least one option. For a proposed command, the subject can describe the command directly: ```json theme={null} { "title": "Run the test suite?", "subject": { "type": "command", "command": "cargo test", "cwd": "/home/user/project", "toolCallId": "call_001", "terminalId": "term_001" }, "options": [ { "optionId": "allow-once", "name": "Allow once", "kind": "allow_once" } ] } ``` For `type: "command"`, `command` and `cwd` are required, and `cwd` **MUST** be an absolute path. `toolCallId`, `terminalId`, and `_meta` are optional and nullable. Omission and `null` are equivalent and mean the value was not provided. The IDs only associate the permission with displayed state and may be unavailable before execution starts. Selecting an allow option authorizes the Agent to execute the command. It does not ask the Client to execute anything. The Client responds with the user's decision: ```json theme={null} { "jsonrpc": "2.0", "id": 5, "result": { "outcome": { "outcome": "selected", "optionId": "allow-once" } } } ``` Clients **MAY** automatically allow or reject permission requests according to the user settings. A permission request cancelled with [`$/cancel_request`](/protocol/v2/cancellation), for example after [`session/cancel`](/protocol/v2/prompt-lifecycle#cancellation), is answered with the `"cancelled"` outcome: ```json theme={null} { "jsonrpc": "2.0", "id": 5, "result": { "outcome": { "outcome": "cancelled" } } } ``` Clients also send `cancelled` when the user dismisses the prompt or the Client declines it by policy, including when no `reject_*` option is offered. After a `cancelled` outcome, the Agent **MUST NOT** proceed with the operation. **outcome** `RequestPermissionOutcome` *required* The user's decision. Known outcomes are `cancelled` when the [active work was cancelled](/protocol/v2/prompt-lifecycle#cancellation), the user dismissed the prompt, or the Client declined it, and `selected` with an `optionId` for the selected permission option. If `optionId` doesn't match an offered option, the Agent **MUST** treat the request as not approved. Custom or future outcomes may appear. Agents that do not understand the outcome **MUST NOT** treat it as approval. ### Permission options Each permission option provided to the Client contains: **optionId** `string` *required* Identifier for this option. **MUST** be unique within the request. **name** `string` *required* Human-readable label to display to the user **kind** `PermissionOptionKind` *required* A hint to help Clients choose appropriate icons and UI treatment for each option. * `allow_once` - Allow this operation only this time * `allow_always` - Allow this operation and remember the choice * `reject_once` - Reject this operation only this time * `reject_always` - Reject this operation and remember the choice Custom or future permission option kinds can be used as UI hints. Custom kinds **MUST** begin with `_`. Unknown non-underscore kinds are reserved for future ACP variants. Clients that do not understand a kind should preserve the value and use a generic permission option treatment. The Agent owns remembered decisions. When the user selects an `allow_always` or `reject_always` option, the Agent stores the decision, decides its scope (for example a tool, a command, or a directory) and how long it lasts, and applies it by not asking again. Clients **SHOULD NOT** infer the scope from `kind`. The option `name` describes it. ### Security * Clients **SHOULD** describe the operation from `subject`, present `title` as Agent-authored text, and show commands and paths in full. * Agents **SHOULD NOT** give an option a `name` that contradicts its `kind`, and **SHOULD** act on a selected option according to its known `kind`. * Automatic approval **SHOULD NOT** rely only on `title`, `description`, or option `name`. Unless the user's policy allows all requests, it **SHOULD NOT** allow a request with an absent or unknown subject. * Agents **SHOULD** perform only the operation the approved request described, and **SHOULD** request again if the command or resolved target changes. * Agents **SHOULD** state the scope of a remembered decision (`allow_always`, `reject_always`) in the option `name` and **SHOULD NOT** apply it beyond that scope. * Agents **SHOULD NOT** switch to a configuration that reduces user oversight without user action. ## Status Tool calls progress through different statuses during their lifecycle: **pending** The tool call hasn't started running yet, for example because its input is streaming, it is awaiting approval, or it is scheduled to run later **in\_progress** The tool call is currently running **paused** The tool call has started, is not running now, and will not continue until something resumes it **completed** The tool call completed successfully **failed** The tool call failed with an error **cancelled** The tool call was cancelled before it completed Custom or future status values can be used when Clients can display a generic progress state. Custom status values **MUST** begin with `_`. Unknown non-underscore statuses are reserved for future ACP variants. Clients treat a tool call with an unrecognized status as still in progress. Clients **SHOULD** show `in_progress` as active, `pending` as waiting or scheduled, and `paused` as paused. Statuses never go back to `pending`: a scheduled wakeup goes from `pending` to `completed` when it fires, and the work it triggers is new foreground work. `in_progress` and `paused` may alternate any number of times. How work is paused and resumed is up to the Agent. `completed`, `failed`, and `cancelled` are final. If work goes on after its tool call is final, the Agent reports it on a new tool call. When foreground work ends, whether it finished, was [cancelled](/protocol/v2/prompt-lifecycle#cancellation), or failed, the Agent **SHOULD** give each of that work's unfinished tool calls a final status. Tool calls in the session's [`background`](/protocol/v2/prompt-lifecycle#background-work) list are not part of that work. If a tool call's [permission request](#requesting-permission) is rejected or answered with `cancelled`, the Agent reports the tool call as `cancelled` or `failed` rather than leaving it `pending`. ### Cancelling tool calls A tool call can advertise that the Client may cancel it on its own, without cancelling the rest of the session's work. `tool_call_update` carries an optional `capabilities` field: ```json theme={null} { "sessionUpdate": "tool_call_update", "toolCallId": "call_012", "status": "in_progress", "capabilities": { "cancel": {} } } ``` `capabilities` is a nullable patch: omitted leaves it unchanged, `null` clears it, and an object replaces the whole previous value. Within it, an omitted or `null` `cancel` means unsupported, and `{}` advertises support. A `pending` or `paused` tool call may advertise it too, for example to delete a scheduled job. The Agent **SHOULD** stop advertising `cancel` once the tool call reaches a final status. The Client cancels the tool call with a `tool_call/cancel` request: ```json theme={null} { "jsonrpc": "2.0", "id": 7, "method": "tool_call/cancel", "params": { "sessionId": "sess_abc123def456", "toolCallId": "call_012" } } ``` * The Client **MUST NOT** send it unless the tool call currently advertises `capabilities.cancel`. * The Agent responds with an empty result once it has accepted the cancellation. The response does not mean the work has stopped. The Agent confirms that with a `tool_call_update` to a final status, normally `cancelled`, and may send `completed` or `failed` if the work finished first. * The Agent responds with `-32602` if the tool call is unknown, already final, or not cancellable. * Cancelling a tool call does not change the foreground state by itself. This works for foreground tool calls too, so a user can stop one long-running step without cancelling the rest of the work. ## Content Tool calls can produce different types of content: Tool call content `type` values can also be custom or future variants. Implementations **SHOULD** preserve unknown content payloads when storing, replaying, proxying, or forwarding tool calls, and otherwise render a generic content item or ignore the item if no safe display is available. ### Regular content Standard [content blocks](/protocol/v2/content) like text, images, or resources: ```json theme={null} { "type": "content", "content": { "type": "text", "text": "Analysis complete. Found 3 issues." } } ``` ### Display-only terminals A terminal content item references an Agent-owned terminal by ID: ```json theme={null} { "type": "terminal", "terminalId": "term_001" } ``` The item is only a display anchor. `terminalId` is required. Optional nullable `_meta` is scoped to this content item. Omission and `null` both mean that no item metadata was provided. `terminalId` is unique within the session, remains stable for the terminal's lifetime, and **MUST NOT** be reused for a different terminal. It is independent of `toolCallId`, even when an Agent uses the same string for both. The reference and the terminal's session updates may arrive in either order, so Clients retain state for a first-seen `terminalId`. Agents create and update stored terminal state with `terminal_update`: ```json theme={null} { "sessionUpdate": "terminal_update", "terminalId": "term_001", "command": "cargo test", "cwd": "/home/user/project", "size": { "cols": 120, "rows": 40 }, "output": { "data": "cnVubmluZyB0ZXN0cw0K" }, "exitStatus": { "exitCode": 0, "signal": null } } ``` `terminal_update` is an upsert keyed by required `terminalId`. Other fields are patches: omission leaves the previous value unchanged, `null` clears it, and a concrete value replaces it. On a first-seen ID, omitted fields start unknown or empty. * `command` describes the command being run. Agents **SHOULD** provide it on the first update when applicable. * `cwd` is the command's working directory and **MUST** be absolute when supplied. * `size` is the terminal size the command runs with, in character cells, with required `cols` and `rows`. It is optional. When present, Clients can render output at this size so that column layouts, progress bars, and cursor-positioned output display as the program wrote them. Without it, Clients choose a size. * `output` is an authoritative replacement snapshot. Its required `data` is RFC 4648 base64-encoded bytes with JSON Schema `contentEncoding: "base64"`. A concrete snapshot is the complete byte sequence the Agent wants the Client to retain for the terminal at that point. It replaces all previously stored bytes. Clients **MUST NOT** merge or splice bytes from the previous snapshot into it. Optional nullable `output._meta` is scoped to that snapshot. Omission and `null` both mean no snapshot metadata was provided. * A concrete `exitStatus` marks the terminal as exited. Its optional nullable `exitCode` and `signal` report known exit information. Its optional nullable `_meta` is scoped to that exit information. For all three fields, omission and `null` both mean the value was not provided. Conventional POSIX signal names include `SIGTERM`, `SIGKILL`, and `SIGINT`. Other platforms may use platform-specific names. Terminal exit and tool call status are independent. * The top-level `_meta` is terminal-scoped and follows the same patch semantics, except that an object patches the stored metadata by top-level key. See [Metadata Patches](/protocol/v2/extensibility#metadata-patches). For example, a process terminated by a POSIX termination signal can report `"exitStatus": { "signal": "SIGTERM" }`. For live output, Agents send `terminal_output_chunk`: ```json theme={null} { "sessionUpdate": "terminal_output_chunk", "terminalId": "term_001", "data": "cGFzc2VkDQo=" } ``` `terminalId` and `data` are required. Each `data` value is an independently RFC 4648 base64-encoded byte chunk with JSON Schema `contentEncoding: "base64"`. Clients decode each chunk separately and append the decoded bytes in received order for that `terminalId`. They **MUST NOT** concatenate encoded strings before decoding. Chunk boundaries may split UTF-8 code points or terminal escape sequences, so decoders retain parser state across chunks. Optional nullable `_meta` is chunk-scoped. Omission and `null` both mean no chunk metadata was provided. A chunk for a `terminalId` the Client hasn't seen creates the terminal with unknown fields and empty output, then appends to it. Clients **SHOULD** ignore a chunk, or the `output` snapshot of a `terminal_update`, whose `data` isn't valid base64, keeping the bytes they already have. The other fields of that `terminal_update` still apply. Agents **SHOULD** send all output before a concrete `exitStatus`, but Clients still append output that arrives after it. Clients **MAY** bound how much output they keep, for example by dropping the oldest bytes. A later `output` snapshot replaces whatever they kept. Terminal output is Agent content. Clients **SHOULD** render it so that it cannot write the clipboard, send input or query responses, or open links without user action, and sanitizers **SHOULD** keep state across chunks. #### Cancelling terminals A terminal may keep running after its tool call returns control to the model, as [background work](/protocol/v2/prompt-lifecycle#background-work). The tool call that started it keeps referencing the terminal, so the Client can show its output in place. Terminals are display-only except for one opt-in control: `terminal_update` carries an optional `capabilities` field with the same shape and patch rules as on tool calls. ```json theme={null} { "sessionUpdate": "terminal_update", "terminalId": "term_003", "command": "npm run dev", "capabilities": { "cancel": {} } } ``` The Agent **SHOULD** stop advertising `cancel` once the terminal reports `exitStatus`. The Client stops the process with a `terminal/cancel` request with the `sessionId` and `terminalId`: * The Client **MUST NOT** send it unless the terminal currently advertises `capabilities.cancel`. * The Agent responds with an empty result once it has accepted the cancellation. The response does not mean the process has stopped. The Agent confirms that with a `terminal_update` that sets `exitStatus`. * The Agent responds with `-32602` if the terminal is unknown, has already exited, or is not cancellable. * Cancelling stops the process but does not release the terminal: its output remains available for display and replay. It does not change the foreground state or the status of any tool call that references the terminal. Input, resize, and other interactive control remain out of scope. ### Diffs File modifications shown as diffs. A diff always includes structured file changes and can optionally include renderable patch text. `changes` is authoritative for affected absolute paths and operations. `patch`, when present, provides renderable text for some or all of those changes and **MUST** be consistent with `changes`: it describes only those paths and operations. Agents **SHOULD** provide `patch` whenever feasible. Clients **MUST** handle diffs where `patch` is omitted or `null`, and **SHOULD** follow `changes` when `patch` disagrees with it. A diff describes each file's change from its state before the change. Each `path` value appears in at most one entry of `changes`. A move or copy's `oldPath` may also appear as another entry's `path`, for example a file copied and then edited, or a file moved and replaced by a new one. A move or copy that also edits the file is a single `move` or `copy` entry, with the edits in `patch`. ```json theme={null} { "type": "diff", "changes": [ { "operation": "modify", "path": "/home/user/project/src/config.json", "fileType": "text", "mimeType": "application/json" } ], "patch": { "format": "git_patch", "text": "diff --git /home/user/project/src/config.json /home/user/project/src/config.json\n--- /home/user/project/src/config.json\n+++ /home/user/project/src/config.json\n@@ -1,3 +1,3 @@\n {\n- \"debug\": false\n+ \"debug\": true\n }\n" } } ``` **changes** `DiffChange[]` *required* Structured file changes described by this diff. **patch** `DiffPatch` Optional renderable patch text. Agents **SHOULD** provide this whenever feasible. Omitted or `null` means no patch text was provided. **patch.format** `string` *required* Patch format. `git_patch`, the only ACP-defined value, is one or more `diff --git` sections in Git's `--patch` (`-p`) text format. Unlike Git, which writes paths relative to the repository root, every path **MUST** be absolute, including in `rename from`, `rename to`, `copy from`, and `copy to` lines, and **MUST NOT** have a prefix such as Git's default `a/` and `b/`. Otherwise paths follow Git: `/dev/null` names the missing side of an added or deleted file in the `---` and `+++` lines, and paths with unusual characters are [quoted as Git quotes them](https://git-scm.com/docs/git-config#Documentation/git-config.txt-corequotePath). Each path, once unquoted, is the same native absolute path string as the matching `changes` entry, for example `C:\repo\src\a.rs` on Windows. Surrounding commit metadata and email envelopes **MUST NOT** be included. Custom formats **MUST** begin with `_`. Clients treat a `patch` with a format they don't recognize as if `patch` were omitted, and render from `changes`. Git can produce most of this. With `$ROOT` set to the repository root, `git diff --src-prefix="$ROOT/" --dst-prefix="$ROOT/"` writes absolute `diff --git`, `---`, and `+++` lines. Git never prefixes `rename from`, `rename to`, `copy from`, or `copy to` paths, so those still need the repository root prepended, with Git's quoting applied to the full path. On Windows, Git still writes `/` after the root (`C:\repo/src/a.rs`), so Agents convert those paths to native separators before quoting. Many diff parsers strip one leading path component by default to remove Git's `a/` and `b/` prefixes. Don't strip anything from an absolute path, which has no such prefix. A Client can still strip a leading `a/` or `b/` from a relative path to tolerate Agents that send Git's default output, as long as `changes` decides which file a patch belongs to. Take paths from `changes`, or from the `---`, `+++`, rename, and copy lines, rather than by splitting the `diff --git` header, which is ambiguous when paths contain spaces. **patch.text** `string` *required* Renderable patch text in the format named by `patch.format`. **changes\[].operation** `string` *required* File operation: `add`, `delete`, `modify`, `move`, or `copy`. Custom operations **MUST** begin with `_`. Clients show an operation they don't recognize generically, using `path` and `oldPath` when present. **changes\[].path** `string` *required* The absolute path after the operation. For deletes, this is the deleted path. **changes\[].oldPath** `string` The absolute path before the operation. Required for `move` and `copy`. **changes\[].fileType** `string` Optional file kind after the operation (for `delete`, of the deleted file): `text`, `binary`, `directory`, or `symlink`. Custom file types **MUST** begin with `_`, and Clients treat a file type they don't recognize as unknown. **changes\[].mimeType** `string` Optional MIME type of the file contents after the operation (for `delete`, of the deleted file). Omit `patch` when there is no useful text patch, such as a same-path binary update or symlink target change: ```json theme={null} { "type": "diff", "changes": [ { "operation": "modify", "path": "/home/user/project/assets/logo.png", "fileType": "binary", "mimeType": "image/png" } ] } ``` Clients **SHOULD** show affected paths from `changes`, not from `patch` headers. ## Following the Agent Tool calls can report the file locations they're working with. Clients can use this to follow along, showing which files the Agent is reading or modifying as it works. ```json theme={null} { "path": "/home/user/project/src/main.py", "line": 42 } ``` **path** `string` *required* The absolute file path being accessed or modified **line** `integer | null` Optional 1-based line number within the file, represented as an unsigned 32-bit integer. `0` is invalid. Omission and `null` are equivalent and mean no specific line was provided. Locations are display metadata and do not grant file access. Clients **SHOULD NOT** automatically open locations outside the session's [root set](/protocol/v2/session-setup#workspace-root-security). # Transports Source: https://agentclientprotocol.com/protocol/v2/transports Mechanisms for agents and clients to communicate with each other ACP uses JSON-RPC to encode messages. JSON-RPC messages **MUST** be UTF-8 encoded. The protocol currently defines one transport mechanism for agent-client communication: [stdio](#stdio), communication over standard in and standard out. A remote transport based on Streamable HTTP is being specified in the [transport RFD](/rfds/streamable-http-websocket-transport). Agents and clients **SHOULD** support stdio whenever possible. It is also possible for agents and clients to implement [custom transports](#custom-transports). ## stdio In the **stdio** transport: * The client launches the agent as a subprocess. * The agent reads JSON-RPC messages from its standard input (`stdin`) and sends messages to its standard output (`stdout`). * Each message is a single JSON-RPC request, notification, or response object. * Messages are delimited by newlines (`\n`), and **MUST NOT** contain embedded newlines. * The agent **MAY** write UTF-8 strings to its standard error (`stderr`) for logging purposes. Clients **MAY** capture, forward, or ignore this logging. * The agent **MUST NOT** write anything to its `stdout` that is not a valid ACP message. * The client **MUST NOT** write anything to the agent's `stdin` that is not a valid ACP message. ```mermaid theme={null} sequenceDiagram participant Client participant Agent Process Client->>+Agent Process: Launch subprocess loop Message Exchange Client->>Agent Process: Write to stdin Agent Process->>Client: Write to stdout Agent Process--)Client: Optional logs on stderr end Client->>Agent Process: Close stdin, terminate subprocess deactivate Agent Process ``` ### Shutdown To end the connection, the Client closes the Agent's `stdin`. The Agent treats end of input as the end of the connection: its sessions stop being [active](/protocol/v2/session-setup#session-lifecycle), and it **SHOULD** exit once it has finished or stopped its work. If the Agent does not exit within a reasonable time, the Client **MAY** terminate the process, for example with `SIGTERM` and then `SIGKILL`. When the connection ends, either side treats requests it sent that have no response as failed. ## Message timing After the `initialize` exchange completes successfully, Agents **MAY** send requests and notifications at any time: between Client requests, before a pending response, or after a response. Clients **MUST** be prepared to handle these messages independently of the responses they are awaiting, including when no Client request is pending. This permission does not override capability requirements or method-specific lifecycle and ordering rules. For example, session-scoped messages still require a valid session. ## Message order Transports **MUST** deliver messages in the order they were sent. Receivers **MUST** apply a session's `session/update` notifications in the order they are received. ## No batches ACP does not use JSON-RPC 2.0 batches. Senders **MUST NOT** send a JSON array of messages, and receivers reject one with a single `-32600` (Invalid Request) response with `id: null`. ## Custom transports Agents and clients **MAY** implement additional custom transport mechanisms to suit their specific needs. The protocol is transport-agnostic and can be implemented over any communication channel that supports bidirectional message exchange. Implementers who choose to support custom transports **MUST** ensure they preserve the JSON-RPC message format, message order, and lifecycle requirements defined by ACP. Custom transports **SHOULD** document their specific connection establishment and message exchange patterns to aid interoperability. A transport **MAY** add its own requirements, such as reconnection, keepalive, or stream resumption, provided it doesn't change the messages ACP defines. # Publications Source: https://agentclientprotocol.com/publications ACP publications, talks, presentations, and videos ## Talks > [card] [AI Builders Berlin: Agents in the IDE](https://raw.githubusercontent.com/agentclientprotocol/agent-client-protocol/main/docs/assets/publications/ACP%20Talk%20Berlin%2C%202025.11.26.pdf) > > November 26, 2025 · Ben Brandt > [card] [OpenAI | Codex Meetup Berlin: Integrating Codex Into IntelliJ](https://raw.githubusercontent.com/agentclientprotocol/agent-client-protocol/main/docs/assets/publications/ACP%20AppServer%2C%20Berlin%2C%2028.01.26.pdf) > > January 28, 2026 · Anna Zhdan > [card] [AI Builders Amsterdam: AI Agents and IDEs](https://raw.githubusercontent.com/agentclientprotocol/agent-client-protocol/main/docs/assets/publications/ACP%20talk%20Amsterdam%2C%2029.01.26.pdf) > > January 29, 2026 · Sergey Ignatov > [card] [JUG Bern: Your AI Agent In Any Editor](https://raw.githubusercontent.com/agentclientprotocol/agent-client-protocol/main/docs/assets/publications/ACP%20Schweiz%2C%2017.02.26.pdf) > > February 11, 2026 · Anna Zhdan > [card] [Munich AI Tech Meetup @ JetBrains: Your AI Agent In Any Editor](https://raw.githubusercontent.com/agentclientprotocol/agent-client-protocol/main/docs/assets/publications/ACP%20M%C3%BCnchen%2C%2025.02.26.pdf) > > February 25, 2026 · Anna Zhdan > [card] [London Agentic AI Meetup](https://raw.githubusercontent.com/agentclientprotocol/agent-client-protocol/main/docs/assets/publications/ACP%20talk%20London%2C%2011.03.26.pdf) > > March 11, 2026 · Ben Brandt, Sergey Ignatov > [card] [Copilot Developer Camp Shanghai: GitHub Copilot in JetBrains AI Assistant via ACP](https://raw.githubusercontent.com/agentclientprotocol/agent-client-protocol/main/docs/assets/publications/ACP%20talk%20Shanghai%2C%2021.03.26.pdf) > > March 21, 2026 · Jun Han > [card] [GitHub Copilot Dev Days Shanghai: Agent Client Protocol in GitHub Copilot](https://raw.githubusercontent.com/agentclientprotocol/agent-client-protocol/main/docs/assets/publications/ACP%20talk%20Shanghai%2C%2011.04.26.pdf) > > April 11, 2026 · Jun Han > [card] [London AI Meetup @ Revolut: ACP Beyond the Editor](https://raw.githubusercontent.com/agentclientprotocol/agent-client-protocol/main/docs/assets/publications/ACP%20talk%20London%2C%2002.06.26.pdf) > > June 2, 2026 · Sergey Ignatov ## Videos > [card] [What Is the Agent Client Protocol — and Why JetBrains and Zed Are Building It Together](https://www.youtube.com/watch?v=n11pDnBXPgk) > > Conversation with Ben Brandt, Sergey Ignatov, and Jan-Niklas Wortmann > [card] [Agent Client Protocol in GitHub Copilot](https://www.bilibili.com/video/BV1bDQ4B9Eri/) > > Jun Han # Requests for Dialog (RFDs) Source: https://agentclientprotocol.com/rfds/about Our process for introducing changes to the protocol A "Request for Dialog" (RFD) is ACP's version of the RFC process. RFDs are the primary mechanism for proposing new features, collecting community input on an issue, and documenting design decisions. ## When to write an RFD You should consider writing an RFD if you intend to make a "substantial" change to ACP or its documentation. What constitutes a "substantial" change is evolving based on community norms and varies depending on what part of the ecosystem you are proposing to change. Some changes do not require an RFD: * Rephrasing, reorganizing or refactoring * Addition or removal of warnings * Additions that strictly improve objective, numerical quality criteria (speedup, better browser support) * Fixing objectively incorrect behavior ## The RFD Process ### 1. Propose by opening a PR [Fork the repo](https://github.com/agentclientprotocol/agent-client-protocol) and copy `docs/rfds/TEMPLATE` to `docs/rfds/my-feature.mdx` (using kebab-case naming). The RFD can start minimal - just an elevator pitch and status quo are enough to begin dialog. Pull requests become the discussion forum where ideas get refined through collaborative iteration. ### 2. Merge to "Draft" when championed RFD proposals are merged into the "Draft" section if a core team member decides to champion them. The champion becomes the point-of-contact and will work with authors to make it reality. Draft means the proposal belongs in the RFD process, but it may still be waiting for design work, implementation work, or maintainer bandwidth. Experimental implementation may begin, properly feature-gated with the RFD name, to prove out the design before broader adoption. RFDs are living documents that track implementation progress. PRs working towards an RFD will typically update it to reflect changes in design or direction. ### 2b. Move to "To be removed" RFDs that have never landed may be closed at the discretion of a core team member. RFDs that have landed in draft form are moved to "To be removed" instead until there has been time to remove them fully from the codebase, then they are removed entirely. ### 3. Move to "Active" when it has current maintainer or working-group focus When core maintainers or a working group are actively spending bandwidth on an RFD, the champion can open a PR to move it to "Active." Active RFDs are the proposals the project is currently trying to move forward. This is a visibility signal, not a stability commitment or final approval. Active RFDs should have a current owner, a plausible implementation or design plan, and should be updated as the work changes. If work pauses or the owner no longer has bandwidth, the RFD can move back to Draft. ### 4. Move to "Preview" when fully implemented When the champion feels the RFD is ready for broader review, they open a PR to move it to "Preview." This signals the community to provide feedback. The PR stays open for a few days before the champion decides whether to land it. ### 5. Completed Once in preview, the RFD can be moved to "completed" with a final PR. The core team should comment and express concerns, but **final decision is always made by the core team lead**. Depending on what the RFD is about, "completed" is the only state that can represent a 1-way door (if there is a stability commitment involved), as changes might require a breaking change to the protocol after this point. Preview RFDs don't have to be completed. They may also go back to draft to await further changes or even be moved to "To be removed". ### 6. Lifecycle summary #### RFD Lifecycle * **Early drafts**: Initial ideas, brainstorming, early exploration * **Mature drafts**: Well-formed proposals ready for broader review * **Active**: Current implementation or design work is being driven by core maintainers or a working group * **Preview**: Fully implemented and ready for broad review before completion * **To be removed (yet?)**: Decided against for now, but preserved for future consideration * **Completed**: Implementation finished and merged ### Ordering RFD lists Keep the RFD navigation in `docs/docs.json` and overview lists ordered from oldest to newest within each lifecycle stage. Preserve subgroups such as v2, and apply the same ordering within them: * For Draft, Active, and Preview, use the merge that first introduced the proposal. * For Completed, use the completion or stabilization merge. Later edits do not change an RFD's position. Keep [RFD Updates](/rfds/updates) newest first by lifecycle event date. ## Governance The project currently has a design team with the [Zed team as the lead (BDFL)](../community/governance). Champions from the core team guide RFDs through the process, but final decisions rest with the team lead. This structure maintains velocity while anticipating future governance expansion. ## Discussion and Moderation Detailed discussions often happen on [Zulip](https://agentclientprotocol.zulipchat.com/), with PR comments for process decisions. The results of detailed discussions should be incorporated into the relevant RFD. RFD champions actively curate discussions by collecting questions in the FAQ section. If PR discussions become too long, they should be closed, feedback summarized, and reopened with links to the original. ## Licensing All RFDs are licensed under Apache 2.0. The project remains open source. ## # ACP Agent Registry Source: https://agentclientprotocol.com/rfds/acp-agent-registry **Author:** [@ignatov](https://github.com/ignatov) **Champion:** [@benbrandt](https://github.com/benbrandt) ## Elevator pitch ACP needs a single, trusted registry of agents so clients can discover integrations, understand their capabilities, and configure them automatically. This RFD proposes (1) a canonical manifest format that every agent must publish, (2) a dedicated `agentclientprotocol/registry` repo where maintainers contribute those manifests, and (3) tooling that aggregates and publishes a searchable catalog for editors and other clients. ## Status quo There is no canonical listing of ACP-compatible agents. Information lives in scattered READMEs or proprietary feeds, which makes it hard to: * Let users discover agents directly inside ACP-aware clients. * Ensure protocol-version compatibility or capability coverage. * Keep metadata consistent (hosting model, license, etc.). Every editor builds bespoke manifests or scrapes GitHub, leading to duplication and stale data. ## Agent manifest format (core proposal) Each agent advertises itself via a manifest stored as `/agent.json` in the registry repo. Fields marked with **\*** are required: | Field | Description | | - | - | | `id` **\*** | Unique agent identifier. Lowercase letters, digits, and hyphens; must start with a letter (pattern: `^[a-z][a-z0-9-]*$`). Also the folder name in the registry repo. | | `name` **\*** | Human-readable display name. | | `version` **\*** | Semantic version of the agent release (e.g. `1.0.0`). | | `description` **\*** | Brief description of the agent's functionality and purpose. | | `distribution` **\*** | Object describing how to obtain and run the agent. Supports three distribution types: `binary` (platform-specific archives), `npx` (Node packages), and `uvx` (Python packages). At least one distribution type must be provided. See [Distribution](#distribution) for details. | | `repository` | Source code repository URL. | | `authors` | Array of author/organization names. | | `license` | SPDX license identifier or `"proprietary"`. | | `icon` | Path to icon file (relative path or absolute URL). Must be SVG format, 16×16, monochrome using `currentColor` (enables light/dark theme adaptation). See [Icon requirements](#icon-requirements). | ### Distribution The `distribution` object supports three mutually independent strategies. An agent may provide one or more: #### `binary` Platform-specific archive downloads. Keyed by `-` targets: | Target | OS | Architecture | | - | - | - | | `darwin-aarch64` | macOS | ARM64 | | `darwin-x86_64` | macOS | x86-64 | | `linux-aarch64` | Linux | ARM64 | | `linux-x86_64` | Linux | x86-64 | | `windows-aarch64` | Windows | ARM64 | | `windows-x86_64` | Windows | x86-64 | When using `binary` distribution, builds **must be provided for all three operating systems** (darwin, linux, windows). CI will reject entries that only cover a subset. Each target is an object with: | Field | Required | Description | | - | - | - | | `archive` | Yes | URL to download archive | | `cmd` | Yes | Command to execute after extraction | | `args` | No | Array of command-line arguments | | `env` | No | Object of environment variables | #### `npx` / `uvx` Package-manager-based distribution (Node via `npx`, Python via `uvx`). Each is an object with: | Field | Required | Description | | - | - | - | | `package` | Yes | Package name (with optional version spec) | | `args` | No | Array of command-line arguments | | `env` | No | Object of environment variables | ### Icon requirements Icons must meet the following requirements to pass CI validation: * **SVG format** — only `.svg` files are accepted. * **16×16 dimensions** — via `width`/`height` attributes or `viewBox`. * **Monochrome using `currentColor`** — all `fill` and `stroke` values must use `currentColor` or `none`. Hardcoded colors (e.g. `fill="#FF5500"`, `fill="red"`) are rejected. Using `currentColor` lets icons adapt automatically to the client's light or dark theme. ### Example: binary distribution ```jsonc theme={null} { "id": "someagent", "name": "SomeAgent", "version": "1.0.0", "description": "Agent for code editing", "repository": "https://github.com/example/someagent", "authors": ["Example Team"], "license": "MIT", "icon": "icon.svg", "distribution": { "binary": { "darwin-aarch64": { "archive": "https://github.com/example/someagent/releases/latest/download/someagent-darwin-arm64.zip", "cmd": "./someagent", "args": ["acp"], }, "darwin-x86_64": { "archive": "https://github.com/example/someagent/releases/latest/download/someagent-darwin-x64.zip", "cmd": "./someagent", "args": ["acp"], }, "linux-aarch64": { "archive": "https://github.com/example/someagent/releases/latest/download/someagent-linux-arm64.zip", "cmd": "./someagent", "args": ["acp"], }, "linux-x86_64": { "archive": "https://github.com/example/someagent/releases/latest/download/someagent-linux-x64.zip", "cmd": "./someagent", "args": ["acp"], }, "windows-x86_64": { "archive": "https://github.com/example/someagent/releases/latest/download/someagent-windows-x64.zip", "cmd": "./someagent.exe", "args": ["acp"], "env": { "SOMEAGENT_MODE_KEY": "", }, }, }, }, } ``` ### Example: package distribution ```jsonc theme={null} { "id": "pyagent", "name": "PyAgent", "version": "2.1.0", "description": "A Python-based ACP agent", "repository": "https://github.com/example/pyagent", "license": "Apache-2.0", "distribution": { "uvx": { "package": "pyagent@latest", "args": ["--mode", "acp"], }, }, } ``` ## Registry schema The aggregated `registry.json` file conforms to the registry schema and contains: | Field | Description | | - | - | | `version` | Registry schema version (semver, e.g. `1.0.0`). | | `agents` | Array of agent entries (each following the agent manifest schema above, sourced from `agent.json` files). | ## Authentication requirements To be listed in the registry, an agent **must support at least one** of the following authentication methods: * **Agent Auth** — the agent handles the OAuth flow independently (opens the user's browser, runs a local callback server, exchanges the authorization code for tokens). * **Terminal Auth** — the agent provides an interactive terminal-based setup experience (launched with additional args/env specified in the auth method). CI verifies this by checking that the agent returns an `authMethods` array in its `initialize` response, with at least one method. See the [Terminal Authentication RFD](./auth-methods) for the terminal flow. ## What we propose to do about it 1. **Manifest spec** (above) becomes normative; we publish the JSON Schema and validator script so maintainers can lint locally. 2. **Registry repository** `github.com/agentclientprotocol/registry`: * Structure: `/agent.json`, optional `icon.svg`, optional `README.md`. * CI validates manifests on every PR: schema compliance, slug uniqueness, icon format (16×16 SVG, monochrome `currentColor`), URL accessibility for all distribution URLs, authentication support via ACP handshake, and binary OS coverage. * Push to `main` triggers a build that aggregates all entries into `registry.json` and publishes versioned + `latest` GitHub releases. 3. **Aggregated outputs**: * `registry.json`: deterministic list of all agents with icons copied to `dist/.svg`. 4. **Distribution & search**: * Clients fetch `registry.json` from `https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json`. * Static site offers filters for deployment model, license, and distribution type. ## Shiny future * Agent maintainers make PRs to update their manifests; CI keeps data clean. * Automated version updates run hourly, checking npm, PyPI, and GitHub releases for new versions of registered agents and opening PRs automatically. * Editors/clients can bootstrap ACP support by fetching one JSON file and filtering locally. * The ACP website displays the same data for humans, ensuring consistency. * Package-based distribution (`npx`, `uvx`) lowers the barrier for agents that don't need platform-specific binaries. ## Implementation details and plan **Phase 1 – Spec & repo bootstrap** * Finalize JSON Schema and documentation. * Create registry repo with CI (GitHub Actions) that validates on PRs and publishes on merge. * Seed with reference agents. * Implement automated version update workflow (hourly cron via GitHub Actions). * Enforce authentication requirements via CI handshake verification. ## Revision history * 2025-11-28: Initial draft. * 2025-12-16: Minors. * 2026-02-04: Updated to match latest schema — removed `schema_version`, `homepage`, `capabilities`, and `auth` fields; added `icon` field; restructured `distribution` into `binary`, `npx`, and `uvx` types. # Additional Workspace Roots for Session Lifecycle Requests Source: https://agentclientprotocol.com/rfds/additional-directories * Author(s): [egor-baranov](https://github.com/egor-baranov) * Champion: [benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? ACP currently standardizes `cwd` on session lifecycle requests, but does not define a standard way to declare additional filesystem roots for a session. This RFD proposes an optional field: ```ts theme={null} additionalDirectories?: string[] ``` on: * `NewSessionRequest` * `ResumeSessionRequest` * `ForkSessionRequest` * `LoadSessionRequest` and an optional capability: ```ts theme={null} sessionCapabilities.additionalDirectories?: {} ``` `cwd` remains the primary working directory. `additionalDirectories` expands filesystem scope only. It does not replace `cwd`, define directory contents, or introduce new RPC methods. ## Status quo > How do things work today and what problems does this cause? Why would we change things? ACP currently allows a client to identify one primary workspace root through `cwd`. That is sufficient for single-root projects, but it does not provide a standard way to expose additional roots in multi-root repositories or environments where project code, shared instructions, skills, or mounted workspaces live at separate absolute paths. Without a standardized field, clients and agents must rely on implementation-specific conventions. `_meta` is not appropriate for interoperable workspace-root semantics. This leaves multi-root behavior fragmented and less predictable across implementations. ## What we propose to do about it > What are you proposing to improve the situation? Add `additionalDirectories?: string[]` to the session lifecycle request schemas listed above, and add optional additional-root discovery metadata to `session/list` responses. The proposal is scoped to session lifecycle requests, session discovery requests, and session discovery metadata only: * no new RPC methods are added; * `cwd` remains unchanged as the primary root; and * ACP remains agnostic to directory naming and directory contents. Agents advertise support with `sessionCapabilities.additionalDirectories`. Clients MUST gate usage on that capability. This proposal also allows Agents to include `additionalDirectories` in `SessionInfo` returned by `session/list`. Because Agents are not required to persist additional-root metadata, Clients treat `SessionInfo.additionalDirectories` as optional discovery metadata rather than required session state. `session/load` and `session/resume` remain explicit-list only: omitting `additionalDirectories` or supplying an empty array means no additional roots are activated for the resulting session, while a non-empty array-valued `additionalDirectories` becomes the complete resulting additional-root list for that request. Clients MAY change the additional-root list on `session/load` or `session/resume` from any previously used or reported list, as long as the request `cwd` matches the session's `cwd` and the Agent accepts the requested roots. ## Shiny future > How will things will play out once this feature exists? Clients can declare multi-root workspace scope in a standard way while preserving existing `cwd` behavior. Agents can treat a session as an ordered root set starting with `cwd` and followed by any array-valued `additionalDirectories` entries, and apply the same discovery and resource-handling behavior they already apply under `cwd` to the other declared roots. Security boundaries remain explicit: declared roots communicate intended scope, while sandboxing, approvals, and OS permissions continue to govern actual access. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? ### Goals / Non-goals #### Goals * Standardize additional workspace roots on session lifecycle entry points. * Preserve `cwd` as the primary working directory for the session. * Define clear validation and error-handling rules. * Enable generic multi-root discovery and resource handling by agents across all declared roots. * Expand the filesystem scope without changing the existing RPC method structure. #### Non-goals * Defining any required directory names or layouts, such as `.agents/`, `skills/`, or `./`. * Defining a standard instruction, skill, or configuration file format. * Replacing `cwd` with a list-valued field. * Changing relative-path semantics. * Adding new RPC methods. * Defining per-root read/write permissions in the protocol. ### Schema changes The following optional property is added to each request type named above: ```ts theme={null} additionalDirectories?: string[] ``` The following optional property is also added to `SessionInfo`: ```ts theme={null} additionalDirectories?: string[] ``` The following capability is added to `SessionCapabilities`: ```ts theme={null} additionalDirectories?: {} ``` Clients MUST send `additionalDirectories` only when `sessionCapabilities.additionalDirectories` is present. If an Agent advertises `sessionCapabilities.additionalDirectories` and also supports `session/list`, it MAY include `SessionInfo.additionalDirectories` to report the complete ordered additional-root list associated with a listed session. Omitted and empty values are equivalent: the `SessionInfo` response reports no additional roots. Clients MUST NOT merge this field with prior values or infer additional roots from agent-specific state. `ListSessionsRequest` is not extended with `additionalDirectories`. `session/list` filtering remains defined around existing list parameters such as `cwd`; Clients that need to find sessions by additional-root state can filter locally when Agents return `SessionInfo.additionalDirectories`. The session-setup, session-list, and filesystem documentation describe the effective root set rather than `cwd` alone as the session filesystem context or boundary. ### Capability advertisement example ```json theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "sessionCapabilities": { "additionalDirectories": {} } } } } ``` ### `session/list` example When an Agent supports both `sessionCapabilities.additionalDirectories` and `session/list`, Clients may still filter by `cwd`. Agents that track additional-root state may include the complete additional-root list on each returned `SessionInfo`: ```json theme={null} { "jsonrpc": "2.0", "id": 5, "method": "session/list", "params": { "cwd": "/home/user/project" } } ``` ```json theme={null} { "jsonrpc": "2.0", "id": 5, "result": { "sessions": [ { "sessionId": "sess_abc123", "cwd": "/home/user/project", "additionalDirectories": [ "/home/user/shared-lib", "/home/user/product-docs" ], "updatedAt": "2026-03-24T12:00:00Z" } ] } } ``` ### Field definition `additionalDirectories` has the following properties: * The field MUST be an array of strings when present. * Each entry MUST be an absolute path under the same platform path rules used for `cwd`. * Empty strings MUST be rejected. * `null` is not a valid value for the field or for any entry. ACP does not define a wire-level lexical normalization algorithm for `cwd` or `additionalDirectories`. Clients SHOULD remove exact duplicate path strings before sending the request. Clients SHOULD also avoid entries whose path string exactly matches `cwd`. Overlapping or nested roots are not semantically redundant for ACP purposes: because discovery across the effective ordered root list is ordered and implementation-defined, such entries MAY affect behavior even when they do not change the union of accessible paths. Agents MAY remove exact duplicate path strings, including entries identical to `cwd`, provided doing so preserves the first occurrence order of the remaining entries and does not expand scope. When returning `SessionInfo.additionalDirectories`, implementations that normalize or canonicalize path strings SHOULD apply the same platform-appropriate rule consistently to stored session state and the returned `SessionInfo.additionalDirectories`. ### Semantics `cwd` remains the primary working directory for the session. It continues to define: * the default base for relative-path resolution; * the primary working directory semantics already defined by ACP; and * the primary workspace root for clients or agents that distinguish one root as primary. `additionalDirectories` defines zero or more extra filesystem roots that are part of the same session workspace scope. The effective ordered root list for a session is: * `[cwd]` when `additionalDirectories` is omitted or is an empty array * `[cwd, ...additionalDirectories]` when `additionalDirectories` is a non-empty array This ordered root list has the following semantics: * The session workspace is a multi-root workspace. * The roots form a logical union of accessible roots. * The roots are not a virtual overlay filesystem. * ACP does not define shadowing, mount, or merge semantics between roots. * Relative paths MUST continue to resolve only against `cwd`. A file path is in scope for the session if, after platform-appropriate path resolution for access control, it is contained within at least one declared root. This proposal expands workspace scope only. It does not imply that all in-scope paths are writable, nor does it bypass client capability checks, user approvals, sandbox rules, or operating-system permissions. ### Request-specific behavior For `NewSessionRequest`, the resulting additional root list is: * `additionalDirectories` when present with a non-empty array value; * otherwise `[]`. For `LoadSessionRequest` and `ResumeSessionRequest`: * when `additionalDirectories` is present with a non-empty array value, it is the complete resulting list of additional roots for the active session, even if that list differs from the session's previously stored or reported additional roots, provided the request `cwd` matches the session's `cwd`; * when omitted or present as an empty array, the resulting additional root list is `[]`. Agents MUST NOT implicitly reactivate stored additional roots that were not supplied on the `session/load` or `session/resume` request. Supplying `additionalDirectories` on `session/load` or `session/resume` is allowed when the capability is advertised and `cwd` matches the session being loaded or resumed, and doing so may preserve, replace, reduce, or expand the session's previously stored or reported additional-root list for the resulting active session, subject to validation and policy checks. Clients that need to preserve a session's additional roots across restarts or across client instances MUST obtain, persist, or reconstruct the full list and resend it on load or resume. When `session/list` includes `SessionInfo.additionalDirectories`, that value can help with this purpose, but Clients MUST NOT assume it is always returned. For `ForkSessionRequest`: * when `additionalDirectories` is present with a non-empty array value, it is a full replacement list for the forked session; * when omitted or present as an empty array, the resulting additional root list is `[]`. Agents MUST NOT implicitly inherit additional roots from the source session unless the implementation can prove that the active root list is already authoritative to the requesting client on the current connection. Otherwise, the agent MUST fail the request or require the client to provide the full list explicitly. For all lifecycle methods, an agent MAY reject the request if the resulting roots are incompatible with stored session state, fork semantics, sandbox policy, or other implementation constraints. An agent MUST NOT silently drop unsupported or unauthorized roots. This RFD defines lifecycle-time workspace scope only. It does not define mid-session mutation of `additionalDirectories`. ### Agent behavior expectations Agents MUST treat paths under `additionalDirectories` as part of the session's accessible workspace scope in the same sense as paths under `cwd`, subject to capabilities and permissions actually available for that session. For any discovery, indexing, or resource-loading behavior an agent applies under `cwd` such as instructions, skills, configuration, or other agent-specific artifacts, the agent SHOULD apply the same behavior to each declared root in `additionalDirectories`, subject to the same capabilities and permissions. If an implementation resolves conflicts across multiple roots, earlier roots in the effective ordered root list SHOULD take precedence over later roots. Conflict resolution within a single root remains implementation-defined. ACP does not define: * required directory names or layouts; * the contents or file formats of discovered artifacts; * whether an agent MUST perform any discovery at all; or * how discovered artifacts affect prompting or execution. Implementations MAY define such behavior independently, but ACP remains agnostic to directory contents. ### Validation and error handling An agent receiving a session lifecycle request with `additionalDirectories` MUST validate the field before creating, loading, resuming, or forking the session. The agent MUST reject the request if: * `additionalDirectories` is not an array; * any entry is not a string; * any entry is empty; * any entry is not absolute. `invalid_params` is the RECOMMENDED error class for malformed values. If an entry is syntactically valid but cannot be granted under the implementation's policy, sandbox, or user-consent model, the agent MUST fail the request with an appropriate error. The agent MUST NOT silently ignore invalid, unauthorized, or unsupported entries and proceed with a reduced root set. ACP does not require a specific lexical normalization algorithm for validating `cwd` or `additionalDirectories`. Implementations that normalize or canonicalize path strings for comparison, deduplication, or storage SHOULD apply the same platform-appropriate rule consistently to both fields, but authorization and containment checks MUST NOT rely solely on lexical normalization. When enforcing root boundaries for subsequent file access, implementations SHOULD use canonical or real paths where available and MUST prevent escapes through symlinks, junctions, mount points, or equivalent mechanisms. If the implementation cannot safely determine whether a path is within an allowed root, it MUST fail closed. ### Client responsibilities A client that sends `additionalDirectories`: * MUST send only paths it intends to expose to the session; * MUST ensure those paths are absolute; * MUST send the full intended active additional root list on `session/load` and `session/resume`; * SHOULD obtain user consent or otherwise act consistently with the client's trust and permission model; * SHOULD remove exact duplicate path strings and entries identical to `cwd` before sending; and * MUST NOT assume an agent will infer extra roots from project metadata, directory conventions, or prior session state. If a client mediates filesystem access through ACP client capabilities such as `fs/read_text_file` and `fs/write_text_file`, it MUST enforce the effective root set for that session when authorizing path-based access. ACP's filesystem methods are client-mediated and operate on absolute paths, so the client remains responsible for boundary enforcement in those flows. When the client learns about an existing session through `session/list`, it SHOULD use `cwd` together with any `SessionInfo.additionalDirectories` entries returned for that session as the reported root set. Omitted and empty values report no additional roots. Any subsequent lifecycle request establishes the resulting active root set explicitly. If a client launches an agent with direct filesystem access, `additionalDirectories` is not, by itself, a sandbox. Clients that need root boundaries to be enforced in that deployment model SHOULD apply operating-system or runtime sandboxing consistent with the declared root set. ### Examples #### `session/new` ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "session/new", "params": { "cwd": "/home/user/project", "additionalDirectories": [ "/home/user/shared-lib", "/home/user/product-docs" ], "mcpServers": [] } } ``` #### `session/load` ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "session/load", "params": { "sessionId": "sess_abc123", "cwd": "/home/user/project", "additionalDirectories": [ "/home/user/shared-lib", "/home/user/product-docs" ], "mcpServers": [] } } ``` #### `session/resume` ```json theme={null} { "jsonrpc": "2.0", "id": 3, "method": "session/resume", "params": { "sessionId": "sess_abc123", "cwd": "/home/user/project", "additionalDirectories": [ "/home/user/shared-lib", "/home/user/product-docs" ], "mcpServers": [] } } ``` #### `session/fork` ```json theme={null} { "jsonrpc": "2.0", "id": 4, "method": "session/fork", "params": { "sessionId": "sess_abc123", "cwd": "/home/user/project", "additionalDirectories": [ "/home/user/shared-lib", "/home/user/product-docs" ], "mcpServers": [] } } ``` ### Security considerations `additionalDirectories` increases the set of filesystem paths the agent may be able to inspect or modify. This increases the potential impact of user error, client misconfiguration, or insufficient sandboxing. Clients MUST NOT send directories that the user has not granted to the session under the client's trust model. Clients SHOULD default to explicit selection or other clear workspace-grant semantics for roots outside the primary project directory. Agents and clients MUST treat root enforcement as a security boundary when they claim to enforce it. Boundary checks MUST account for symlink and path-resolution attacks. Ambiguous cases MUST fail closed. This field does not create a new privilege model. All existing permission prompts, approval flows, filesystem capabilities, sandbox controls, and operating-system access rules continue to apply. Because ACP does not define directory contents, agents SHOULD avoid assuming that any discovered file under an additional root is safe, authoritative, or intended for automatic execution. Discovery is not equivalent to trust. ### Backward compatibility This proposal is additive at the schema level. Requests that omit `additionalDirectories` behave exactly as they do today. Existing clients that do not need multi-root support require no changes. Updated agents MUST continue to accept requests that do not include the field. Older implementations may validate request objects strictly against older schemas and MAY reject unknown fields. Clients therefore MUST gate usage on `sessionCapabilities.additionalDirectories`. This proposal intentionally does not extend the responses to `session/new`, `session/load`, `session/resume`, or `session/fork` to surface additional-root state directly. That remains consistent with existing ACP response shapes, which also do not return `cwd`. Instead, when `session/list` is supported, Agents MAY expose the complete ordered additional-root list for listed sessions through `SessionInfo.additionalDirectories`. Omitted and empty values report no additional roots for that `SessionInfo`. `SessionInfoUpdate` remains unchanged because this RFD does not define mid-session mutation of `additionalDirectories`. Clients that need multi-root continuity across `session/load` or `session/resume` MUST still send the full intended list explicitly, and MAY change that list from a previously used or reported list as long as the request `cwd` matches the session's `cwd`. `session/list` filtering remains independent of `additionalDirectories`. Sessions that differ by `additionalDirectories` are distinguishable only when the Agent surfaces that state through `SessionInfo.additionalDirectories`; Clients that need additional-root matching can filter those returned sessions locally. This RFD does not add a new RPC method. It also does not change the meaning of `cwd`, `sessionId`, or `mcpServers`. ### Drawbacks * It expands the workspace surface area and therefore the risk of accidental data exposure. * It introduces another dimension of interoperability for clients and agents to test. * It does not standardize discovery behavior, so implementations may still differ in how they use additional roots. * Older strict validators may reject the new field until they adopt the updated schema. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why not use `_meta`? `_meta` is intended for implementation-specific custom data. A standardized workspace-root concept should be protocol-level, typed, and interoperable across implementations. ### Why not replace `cwd` with `workspaceRoots`? `cwd` already has established semantics as the primary working directory. Replacing it with an array would blur relative-path behavior, reduce clarity for existing implementations, and create a larger migration surface. ### Does ACP define `.agents`, `skills`, or instruction directory conventions? No. ACP does not define `.agents`, `skills`, or other instruction directory conventions. This proposal only defines additional accessible roots. Agents SHOULD handle resources under `additionalDirectories` the same way they handle analogous resources under `cwd`, but the names, layouts, and file formats of those resources remain implementation-defined. ### How should clients handle older agents that may not support this field? Clients MUST gate `additionalDirectories` on `sessionCapabilities.additionalDirectories`. If support is absent, clients SHOULD omit the field and preserve existing behavior. ### Why not restore stored roots on `session/load` or `session/resume` when the field is omitted? Even when `SessionInfo.additionalDirectories` is available through `session/list`, implicit restoration would still let an Agent reactivate filesystem scope that the current request did not state explicitly. Some Agents also do not persist or surface this state at all. That is undesirable for Clients that do not use `session/list`, for Clients resuming a session by ID without first listing it, and for Clients that want request-time control over the active root set. This proposal therefore keeps load and resume explicit-list only for additional roots: omitting the field or supplying an empty array activates none, while supplying a non-empty array is explicitly allowed and sets the complete resulting additional-root list for that request. That list may differ from any previously used or reported list, as long as the request `cwd` matches the session's `cwd` and the Agent accepts the requested roots. ### What alternative approaches did you consider, and why did you settle on this one? Alternatives considered: * putting extra roots in `_meta`; * adding a new workspace-configuration RPC method; and * requiring clients to copy or mount everything under `cwd`. This proposal is preferred because it is additive, keeps `cwd` semantics stable, avoids new methods, and standardizes multi-root scope at session lifecycle boundaries. ## Revision history * 2026-05-21: Moved to Preview. * 2026-03-24: Initial draft. # Terminal Authentication Source: https://agentclientprotocol.com/rfds/auth-methods Author(s): [anna239](https://github.com/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. ```json v1 theme={null} { "id": "agent-login", "name": "Log in from the terminal", "description": "Open the Agent's interactive login flow", "type": "terminal", "args": ["--login"], "env": { "ACP_INTERACTIVE_LOGIN": "1" } } ``` ```json v2 theme={null} { "methodId": "agent-login", "name": "Log in from the terminal", "description": "Open the Agent's interactive login flow", "type": "terminal", "args": ["--login"], "env": [ { "name": "ACP_INTERACTIVE_LOGIN", "value": "1" } ] } ``` 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. ```json v1 theme={null} { "clientCapabilities": { "auth": { "terminal": true } } } ``` ```json v2 theme={null} { "capabilities": { "auth": { "terminal": {} } } } ``` 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](https://github.com/agentclientprotocol/agent-client-protocol/pull/289). 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-08-20: Moved terminal authentication to Completed and stabilized its v1 and v2 SDK types, schemas, capabilities, and protocol documentation. * 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. # Boolean Config Option Type Source: https://agentclientprotocol.com/rfds/boolean-config-option * Author(s): [fscarponi](https://github.com/fscarponi) * Champion: [benbrandt](https://github.com/benbrandt) ## Elevator pitch Add a new `boolean` type to session configuration options, enabling agents to expose simple ON/OFF toggles (e.g., "Brave Mode", "Read Only", "Produce Report") as first-class config options alongside the existing `select` type. ## Status quo Currently, `SessionConfigKind` only supports the `select` type, which allows agents to expose dropdown-style selectors with a list of named values. This works well for choosing models, modes, or reasoning levels. However, there is no native way to represent a simple boolean on/off toggle. To expose a boolean option today, agents must use a `select` with two artificial options (e.g., "on"/"off"), and clients need custom, non-agnostic logic to detect that a particular select is actually a boolean toggle. This defeats the purpose of a standardized protocol. ## What we propose to do about it * Add a `SessionConfigBoolean` struct with a `current_value: bool` field * Add a `Boolean(SessionConfigBoolean)` variant to the `SessionConfigKind` enum, discriminated by `"type": "boolean"` * Add a `SessionConfigOptionValue` internally-tagged enum so that `SetSessionConfigOptionRequest` can carry both string values (for `select`) and boolean values (for `boolean`) with an explicit `type` discriminator * Add a v1 `session.configOptions.boolean` client capability so Agents only send boolean config options to Clients that explicitly opt in * Provide convenience constructors and `From` impls for ergonomic usage * Update documentation and regenerate schema files ## Shiny future Clients can natively render boolean config options as toggle switches or checkboxes, without any custom logic. Agents can expose options like "Brave Mode", "Produce Report", or "Read Only" in a standardized way that any ACP-compliant client understands out of the box. ## Implementation details and plan ### Client capability In v1, Clients opt in by setting `session.configOptions.boolean` in `initialize`: ```json theme={null} { "jsonrpc": "2.0", "id": 0, "method": "initialize", "params": { "protocolVersion": 1, "clientCapabilities": { "session": { "configOptions": { "boolean": {} } } } } } ``` Omitting `session`, `configOptions`, or `boolean` means the Client does not advertise support. `null` at any of those levels is equivalent to omission. Agents **MUST NOT** include `type: "boolean"` config options in v1 `configOptions` payloads unless the Client advertised `session.configOptions.boolean: {}`. This applies to `session/new`, `session/load`, `session/update`, and `session/set_config_option` responses. Agents that need to support older Clients should omit the boolean option or provide a `select` fallback. Protocol v2 does not add an equivalent capability field for this extension. v2 peers are boolean-aware by construction; compatibility layers that down-convert v2 client capabilities to v1 advertise `session.configOptions.boolean: {}` by default. ### Wire format: declaring a boolean option In a `session/new` response (or any response containing `configOptions`): ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "sessionId": "sess_abc123", "configOptions": [ { "id": "brave_mode", "name": "Brave Mode", "description": "Skip confirmation prompts and act autonomously", "type": "boolean", "currentValue": true }, { "id": "mode", "name": "Session Mode", "category": "mode", "type": "select", "currentValue": "code", "options": [ { "value": "ask", "name": "Ask" }, { "value": "code", "name": "Code" } ] } ] } } ``` ### Wire format: setting a boolean option The `session/set_config_option` request carries a `type` discriminator alongside the `value`. The `type` field describes the *shape* of the value, not the option kind. For boolean options, Clients send `type: "boolean"` with a boolean value: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "session/set_config_option", "params": { "sessionId": "sess_abc123", "configId": "brave_mode", "type": "boolean", "value": true } } ``` For select and other id-based options, Clients send `type: "id"` with a `SessionConfigValueId` string: ```json theme={null} { "jsonrpc": "2.0", "id": 3, "method": "session/set_config_option", "params": { "sessionId": "sess_abc123", "configId": "mode", "type": "id", "value": "code" } } ``` The response returns the full set of config options with current values, as with `select`: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "result": { "configOptions": [ { "id": "brave_mode", "name": "Brave Mode", "description": "Skip confirmation prompts and act autonomously", "type": "boolean", "currentValue": true }, { "id": "mode", "name": "Session Mode", "category": "mode", "type": "select", "currentValue": "code", "options": [..] } ] } } ``` Key changes: 1. `SessionConfigBoolean` struct with `current_value: bool` 2. `Boolean(SessionConfigBoolean)` variant in `SessionConfigKind` (tagged via `"type": "boolean"`) 3. `SessionConfigOptionValue` enum using `#[serde(tag = "type")]` with an untagged `OtherSessionConfigOptionValue` fallback for future value shapes: * `Id { value: SessionConfigValueId }` — matched when `type` is `"id"` * `Boolean { value: bool }` — matched when `type` is `"boolean"` * `Other(OtherSessionConfigOptionValue)` — preserves unrecognized typed value payloads 4. `SessionConfigOptionValue` is flattened (`#[serde(flatten)]`) onto `SetSessionConfigOptionRequest`, producing top-level `type` and `value` fields on the wire 5. The `value` field in `SetSessionConfigOptionRequest` is a `SessionConfigOptionValue`, flattened onto the request 6. The v1 `ClientCapabilities.session.config_options.boolean` field path serializes as `session.configOptions.boolean` 7. v2 requires a `type` field so future value shapes can be captured without ambiguity ### Client capabilities Clients that receive a config option with an unrecognized `type` should still ignore it. However, boolean config options also change the `session/set_config_option` request shape from the v1 string-only `value` convention to a boolean-valued payload. To avoid breaking Clients or SDKs that do not tolerate that shape, v1 Agents must treat boolean config options as capability-gated and only send them after the Client advertises `session.configOptions.boolean: {}`. ## Frequently asked questions ### What alternative approaches did you consider, and why did you settle on this one? We considered reusing the existing `select` type with a convention (e.g., options named "on"/"off"), but this would require clients to implement non-agnostic detection logic, which contradicts the goal of a standardized protocol. A dedicated `boolean` type is cleaner and lets clients render the appropriate UI control without guessing. ### Is this a breaking change? For v1 peers that do not advertise support, Agents must not send boolean config options, so the existing string-only config option behavior is preserved. v2 requires a `type` field on `session/set_config_option` so id values, boolean values, and future value shapes are distinguishable. For peers that opt in with `session.configOptions.boolean: {}`, boolean options introduce a new `type: "boolean"` setter shape with a boolean `value`. While no one would set a value of type boolean that doesn't support it, there is an issue with possible string deserialization causing the entire session/new or other response to fail deserialization. Most SDKs would process this gracefully, but if popular agents start using it, they could break existing clients. ## Revision history * 2026-07-06: Moved to Completed and stabilized boolean config options in the protocol artifacts. * 2026-06-30: Moved to Preview. * 2026-06-22: Added the v1 `session.configOptions.boolean` client capability gate so boolean config options are only sent to Clients that explicitly opt in, and made v2-to-v1 compatibility conversion advertise the capability by default * 2026-03-05: Updated to reflect final implementation — `flag` renamed to `boolean`, value type changed from untagged `String | Bool` enum to internally-tagged enum with `type` discriminator and untagged `ValueId` fallback, feature-gated behind `unstable_boolean_config` * 2026-02-24: Initial proposal # Client-Provided System Prompt Source: https://agentclientprotocol.com/rfds/client-system-prompt * Author(s): [@wpfleger96](https://github.com/wpfleger96) * Champion: [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? Allow clients to provide system-level instructions for a session in ACP v1 and v2. Today, ACP has no mechanism for a client to deliver system-level instructions to an agent — the only content a client can send is user-role messages via `session/prompt`. This means behavioral instructions, persona definitions, and platform context all compete with user content in the same message role, instead of reaching the instructions the agent gives the model at system level. We propose: * A `systemPrompt` session capability, advertised by agents at `initialize`, so clients know before creating a session whether system prompt delivery is supported. * An optional `systemPrompt` object on `session/new` with a `mode` and `content`. `content` is a `ContentBlock[]` for consistency with `session/prompt`, with text as the baseline. Clients re-send the object on the other session lifecycle requests, as they already do for `cwd` and `mcpServers`. * Two modes: **append** (the baseline: client instructions are added to the agent's own instructions) and **override** (client content replaces the agent's built-in default instructions), the latter gated behind an `override` sub-capability. ## Status quo > How do things work today and what problems does this cause? Why would we change things? Aside from the extensibility `_meta` field present on every request, ACP's `session/new` accepts only `cwd`, `mcpServers`, and `additionalDirectories`, and `session/prompt` accepts only `sessionId` and `prompt` (a `ContentBlock[]` of user content). There is no `systemPrompt`, `instructions`, or equivalent field on any ACP method in v1 or v2. This creates several problems for clients that need to provide behavioral instructions to agents: **Workarounds are fragmented and non-standard.** Every implementation works around the gap differently: * [`claude-agent-acp`](https://github.com/agentclientprotocol/claude-agent-acp) added a `_meta.systemPrompt` extension ([issue #90](https://github.com/agentclientprotocol/claude-agent-acp/issues/90), [PR #91](https://github.com/agentclientprotocol/claude-agent-acp/pull/91)). A string replaces the Claude Code preset and an object with `append` adds to it — the same two modes this RFD proposes. But the spec states implementations "MUST NOT make assumptions about values at these keys," making `_meta` unsuitable for instruction delivery that agents are expected to act on. The implementation silently dropped `excludeDynamicSections` for months ([issue #581](https://github.com/agentclientprotocol/claude-agent-acp/issues/581)), demonstrating the fragility of non-standard extensions. * [Buzz](https://github.com/block/buzz) is a Nostr-based team collaboration and messaging platform where AI agents are first-class workspace members. Each managed agent has a persona (behavioral instructions, role definition, platform context) that the ACP harness needs to deliver as system-level instructions. Today, Buzz injects this as `[System]\n{content}` prepended to the user message on every turn — content that never reaches the LLM's system slot. Buzz's own [Persona Pack Spec](https://github.com/block/buzz/blob/main/crates/buzz-persona/PERSONA_PACK_SPEC.md) lists "true system prompt injection via ACP" as a planned feature, explicitly acknowledging the current approach is a workaround. * [Goose](https://github.com/aaif-goose/goose) builds its system prompt internally via `PromptManager` and stores per-session overrides and additions, but the only way for an ACP client to set them is a Goose-specific extension method, `_goose/unstable/session/system-prompt/set`, with `set` (replace) and `append` modes. Goose has [an open issue](https://github.com/aaif-goose/goose/issues/7596) documenting the same gap in terms of its "recipe" system — recipes are Goose's mechanism for injecting behavioral instructions into a session, and the issue notes "there is no recipe field on `NewSessionRequest` and no logic to load/apply a recipe to the new session's agent." Goose's `_goose/session/update_project` method works around this by sending a project ID that the agent resolves to a file on disk — a Goose-specific indirection, not a protocol-level solution. * Codex supports both modes through configuration — `developer_instructions` adds a developer message and `model_instructions_file` replaces its base instructions — but before this RFD, [`codex-acp`](https://github.com/agentclientprotocol/codex-acp) exposed neither to ACP clients. **Instruction following degrades when instructions are in user messages.** OpenAI's Instruction Hierarchy paper ([arXiv 2404.13208](https://arxiv.org/abs/2404.13208)) trains models to prioritize system messages over user and third-party content, and reports robustness gains of up to 63% (for defending against system prompt extraction). Research on system message compliance ([SysBench, arXiv 2408.10943](https://arxiv.org/abs/2408.10943)) further demonstrates that LLMs are specifically trained and evaluated on their ability to follow system-role instructions — a capability that ACP clients currently cannot leverage. **ACP is an outlier.** Comparable protocols and model APIs provide a place for system-level instructions: | Protocol or API | Field | Type | Placement | | - | - | - | - | | MCP `initialize` result | `instructions` | `string` | Per connection; hosts MAY add it to the system prompt | | MCP `sampling/createMessage` | `systemPrompt` | `string` | Per sampling request (the server asks the client's LLM) | | OpenAI Responses API | `instructions` | `string` | Per request | | Anthropic Messages API | `system` | `string \| TextBlock[]` | Per request | Agent frameworks follow the same pattern: AutoGen has `system_message`, CrewAI has `role`/`goal`/`backstory`, LangGraph has `prompt`. Only Google's A2A protocol is similarly silent — but A2A is agent-to-agent transport, a fundamentally different abstraction layer than ACP's client-to-agent communication. Harnesses also already distinguish delivery modes: Claude Code exposes `--system-prompt` (replace the built-in prompt) and `--append-system-prompt` (add to it), Codex has `model_instructions_file` and `developer_instructions`, and Goose has `set` and `append`. A protocol-level design needs to be able to express both. ## What we propose to do about it > What are you proposing to improve the situation? ### Capability advertisement Agents that support client-provided system prompts advertise a `systemPrompt` session capability in the `initialize` response, following the established convention: omitted or `null` means unsupported, `{}` means supported. In v1 it lives under `agentCapabilities.sessionCapabilities`: ```json theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "sessionCapabilities": { "systemPrompt": {} } } } } ``` In v2 it lives at `capabilities.session.systemPrompt`. Clients **MUST NOT** include `systemPrompt` in any request unless the agent advertised the capability. ### Setting a system prompt Clients provide the system prompt on `session/new` as an object with a `mode` and `content`. `content` is a `ContentBlock[]`, matching the content model used by `session/prompt`: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "session/new", "params": { "cwd": "/home/user/project", "mcpServers": [], "systemPrompt": { "mode": "append", "content": [ { "type": "text", "text": "You are a code review specialist. Focus on security vulnerabilities, performance issues, and adherence to the team's style guide. Be thorough but concise." } ] } } } ``` `session/new` is the natural place for this — it already serves as the configuration point for `cwd` and `mcpServers`, and system prompts are fundamentally session-scoped (they define the agent's behavioral context for the entire interaction). `mode` is required, so every request states which behavior it asks for. The object can also carry `_meta` for agent-specific options that only make sense alongside the prompt. Text content blocks are the baseline: any agent advertising the capability **MUST** accept `ContentBlock::Text`. Other content block types are not part of the initial baseline and may be introduced later as sub-capabilities (see FAQ). Clients **MUST NOT** send an empty `content` array. Agents **MAY** reject one with `invalid_params` without creating, loading, resuming, or forking the session. This matches the rule for an empty `prompt` array on `session/prompt`. ### Delivery modes: append and override * **`"append"`**: the client content is added to the agent's own instructions rather than replacing them. Agents **SHOULD** give it system-level precedence — for example, in the model's system prompt or developer instructions rather than in user-turn content — but where it is placed, in what order, and how it is formatted is implementation-defined. Every agent that advertises the capability **MUST** support append mode. Existing harnesses already behave this way: Goose adds appended text under an `# Additional Instructions` heading, Claude Code's `append` adds text after its preset, and Codex delivers `developer_instructions` as a developer message alongside its base instructions. * **`"override"`**: the client content replaces the agent's built-in default instructions. This mode only changes the instructions the agent itself authors: it does not change tool availability, MCP servers, permissions, or session configuration. Context the agent supplies from the workspace or environment — project instruction files such as `AGENTS.md`, environment details, skill listings — **MAY** still be included; every harness surveyed keeps some of it (see FAQ), and agents **SHOULD** document what they keep. Clients that use override take responsibility for any tool guidance or safety instructions the agent's default prompt provided. This mode is opt-in on both sides: agents advertise it via the `mode.override` sub-capability, and clients **MUST NOT** request it unless advertised. ```json theme={null} { "cwd": "/home/user/project", "mcpServers": [], "systemPrompt": { "mode": "override", "content": [{ "type": "text", "text": "..." }] } } ``` Mode sub-capabilities are grouped under `mode`, mirroring the request's `mode` field. Append needs no entry because every agent advertising the capability supports it. An agent supporting both modes advertises: ```json theme={null} "sessionCapabilities": { "systemPrompt": { "mode": { "override": {} } } } ``` ### Session lifecycle The same `systemPrompt` object is accepted on the other session lifecycle requests: `session/load`, `session/resume`, and `session/fork` in v1, and `session/resume` and `session/fork` in v2. This follows the existing pattern for client-supplied session settings, which clients already re-send on these requests (`cwd`, `mcpServers`, `additionalDirectories`). * Clients **SHOULD** send the same `systemPrompt` on these requests that they used when the session was created. Agents that rebuild their prompt from request parameters depend on it. * When a lifecycle request omits `systemPrompt`, the resulting prompt is implementation-defined: the agent **MAY** keep using a prompt it stored with the session, or fall back to its default. Existing harnesses already persist the prompt in different ways (see FAQ), so this RFD requires agents neither to store it nor to discard a stored one. * When a lifecycle request supplies a `systemPrompt` that differs from the one the session was using, the agent **SHOULD** apply it. An agent **MAY** defer the change until it next rebuilds its prompt (for example, after compaction) when applying it immediately would discard prompt caches or preserved reasoning. Changing the prompt of a live session outside these lifecycle requests is out of scope. ### Errors If an agent that advertises the capability cannot apply a supplied `systemPrompt` — for example, an unadvertised mode, a content block type it does not support, or content that exceeds its limits — it **MUST** return an error and **MUST NOT** create, load, resume, or fork the session. `invalid_params` is the RECOMMENDED error for malformed or unsupported values. This gives clients an explicit failure rather than a session running without the instructions they intended. ### Design choices * **Capability-gated opt-in.** Without a capability, an "optional" field is a de facto breaking change: existing agents would silently ignore it, and the requirements below would retroactively put every existing agent in violation. The capability lets agents opt in and then be held to the behavior, and gives clients reliable feature detection — `protocolVersion` cannot serve that role since it only tracks major versions. * **A `systemPrompt` object with `mode` and `content`.** Keeping the mode next to the content means there is no mode without a prompt to rule out, and leaves room for prompt-scoped `_meta` (see FAQ). * **Content as `ContentBlock[]`.** Consistent with `session/prompt` and the rest of the protocol's content model. Text is the required baseline; richer types are future sub-capabilities (see FAQ for why they are excluded from the initial version). * **Both modes, append as baseline.** Append is what Claude Code, Codex, and Goose already support and is the mode every advertising agent must support. Override has real demand (Claude Code, Codex, and Goose ship it) but changes the safety posture — so it is double opt-in: agent advertises, client explicitly requests. * **Re-sent on lifecycle requests.** This follows the pattern for `cwd`, `mcpServers`, and `additionalDirectories`, while leaving room for harnesses that already persist the prompt (see FAQ). ## Shiny future > How will things will play out once this feature exists? Clients provide behavioral instructions through a standard protocol field, and agents deliver them as system-level instructions. The current landscape of fragmented workarounds — `_meta` extensions, agent-specific extension methods, user-message injection, pre-session environment configuration — is replaced by a single interoperable mechanism with explicit feature detection. Buzz's managed agent personas — role definitions, platform context, behavioral guidelines — reach the model as system-level instructions across every agent that advertises the capability (Goose, Claude Code adapters, or others). The same persona works across those agents without agent-specific plumbing. Goose's recipe system can deliver instructions through the protocol instead of relying on filesystem indirection. An IDE can provide project-specific coding guidelines as system-level instructions. A CI/CD pipeline can configure an agent's behavioral constraints for automated workflows. Adapters for harnesses that support prompt replacement (e.g., `claude-agent-acp`) can additionally expose override mode. Agents that don't support client system prompts continue working exactly as they do today — they simply don't advertise the capability, and clients never send the field. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? ### Implemented The unstable schema landed in [PR #2361](https://github.com/agentclientprotocol/agent-client-protocol/pull/2361) and was stabilized for both protocol versions: * Both protocol versions define `SystemPrompt`, `SystemPromptMode`, and the `SessionSystemPrompt*Capabilities` types, and accept `systemPrompt` on their session lifecycle requests. `session/fork` itself remains unstable, so the field on fork requests stays behind `unstable_session_fork`. * The stable JSON schemas and protocol guides for both versions describe the capability and the field. See the [v1 guide](/protocol/v1/session-setup#system-prompt) and [v2 guide](/protocol/v2/session-setup#system-prompt). ### External implementation evidence Agent implementations have landed for both protocol versions: | Implementation | Reference | Behavior | | - | - | - | | Claude Agent adapter | [PR #1366](https://github.com/agentclientprotocol/claude-agent-acp/pull/1366), included in [v0.92.0](https://github.com/agentclientprotocol/claude-agent-acp/releases/tag/v0.92.0) | Advertises `append` and `override`. Accepts the prompt on `session/new`, `session/load`, `session/resume`, and `session/fork`, and rejects unsupported modes and non-text content with `invalid_params` before creating a session. A changed prompt on resume takes effect at the next compaction. | | Codex adapter | [PR #653](https://github.com/agentclientprotocol/codex-acp/pull/653), included in [v2.3.0](https://github.com/agentclientprotocol/codex-acp/releases/tag/v2.3.0) | Advertises `append` only and delivers the text as developer instructions. Keeps the prompt for an omitted `systemPrompt` while the adapter session is open. A changed prompt takes effect at the next compaction, and is rejected with `invalid_params` while the session has work or background terminals running. | ### Schema changes Add a `systemPrompt` session capability (advertised in the `initialize` response): ```typescript theme={null} interface SessionCapabilities { // ...existing capabilities systemPrompt?: SessionSystemPromptCapabilities | null; // omitted/null = unsupported, {} = supported } interface SessionSystemPromptCapabilities { mode?: SessionSystemPromptModeCapabilities | null; // omitted/null = append only _meta?: { [key: string]: unknown } | null; } interface SessionSystemPromptModeCapabilities { override?: SessionSystemPromptOverrideCapabilities | null; // omitted/null = unsupported, {} = override supported _meta?: { [key: string]: unknown } | null; } interface SessionSystemPromptOverrideCapabilities { _meta?: { [key: string]: unknown } | null; } ``` Add the `SystemPrompt` type and an optional `systemPrompt` field to the session lifecycle requests: ```typescript theme={null} interface SystemPrompt { mode: SystemPromptMode; content: ContentBlock[]; _meta?: { [key: string]: unknown } | null; } type SystemPromptMode = "append" | "override"; interface NewSessionRequest { // ...existing fields systemPrompt?: SystemPrompt | null; // omitted and null are equivalent: no client prompt supplied } // The same optional field is added to LoadSessionRequest (v1 only), // ResumeSessionRequest, and ForkSessionRequest. ``` `content` is deserialized strictly, like `session/prompt`'s `prompt`: content blocks the agent cannot parse are not silently dropped, so the agent can return the error described above. This is additive — no existing fields change, no breaking modifications. ### ACP v1 and v2 The feature has the same shape in both protocol versions: | | v1 | v2 | | - | - | - | | Capability | `agentCapabilities.sessionCapabilities.systemPrompt` | `capabilities.session.systemPrompt` | | Requests carrying it | `session/new`, `session/load`, `session/resume`, `session/fork` | `session/new`, `session/resume`, `session/fork` | | Unknown content block types | Rejected when parsing | Preserved as `ContentBlock::Other`; agents reject types they don't support | In both versions, `mode` follows the [enum variant extension](/rfds/v2/enum-variant-extension) rule, like other values that receivers act on, such as v2 MCP server transports. Values beginning with `_` are reserved for implementation-specific modes, and other unknown values for future ACP modes. Receivers parse unknown modes instead of failing, so proxies and older SDKs can store and forward them. Clients **MUST** only use a mode the agent advertised; custom modes are advertised however their extension defines, for example in `_meta`. An agent that receives a mode it does not support **MUST** return an error rather than treating it as `append` or `override`. ### Agent behavior Agents that advertise the `systemPrompt` capability: * **MUST** accept `ContentBlock::Text` content * **MUST** support append mode, and **MUST** support override mode if they advertise the `mode.override` sub-capability * **MUST** apply a `systemPrompt` supplied on `session/new` in the requested mode, or return an error as described above When `systemPrompt` is absent from `session/new`, the agent uses its own default system prompt (current behavior, unchanged). Agents that do not advertise the capability are unaffected — clients never send them the field. ### Client behavior * Clients **MUST NOT** include `systemPrompt` in any request unless the agent advertised the `systemPrompt` capability * Clients **MUST NOT** use `"mode": "override"` unless the agent advertised the `mode.override` sub-capability * Clients **MUST NOT** include content block types other than text unless a future sub-capability allows them * Clients **MUST NOT** send an empty `content` array * Clients **SHOULD** re-send the session's `systemPrompt` on `session/load`, `session/resume`, and `session/fork` ### Security considerations Content delivered at system level carries more weight with the model than user turns or tool output. Clients **SHOULD** only send content they trust at that level; for example, a persona authored by another workspace member is a trust decision for the client, not just a formatting choice. Override mode removes the agent's default instructions, which can include tool guidance and safety rules. Agents that do not want to delegate their default instructions simply do not advertise `override`. Agents **MAY** reject a system prompt that violates their own policy or limits, using the error behavior above. ### Backward compatibility The field is optional and capability-gated, so there is no default behavior change anywhere: * Existing clients that don't send `systemPrompt` see no difference. * Existing agents never receive the field, because they don't advertise the capability and clients gate on it. The unknown-param hazard — an old agent may silently ignore the field (no error, no incorporation) or, if it validates strictly, reject the request — is closed by construction, matching the approach taken by [`additionalDirectories`](/rfds/additional-directories). * Capability detection follows the established rule from [initialization](https://agentclientprotocol.com/protocol/v1/draft/initialization#capabilities): all capabilities omitted in the `initialize` response are treated as unsupported, and introducing a new capability is not a breaking change. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why `ContentBlock[]` and not `string`? An earlier draft proposed a plain `string`, matching MCP's `sampling/createMessage`. Review feedback pushed toward consistency with the rest of ACP, and it's the right call: `session/prompt` already uses `ContentBlock[]`, the capability object gives us a natural place to gate richer content types later, and the marginal implementation cost over a string is near zero once the capability exists. Clients that only need plain text send a single text block. ### Why is text the only baseline content type? The `session/prompt` baseline requires text **and** resource links, so deviating for `systemPrompt` deserves justification. Each of the other `ContentBlock` variants is either hard to apply at session creation or has no known use case: * **`resource_link`** is a pointer, not content. The agent would have to fetch and resolve the URI to text before session creation, with unspecified failure and lifecycle semantics (missing or oversized resources, snapshot-once vs. re-read, unreachable URIs). In a user prompt the agent can address a link with its own tools mid-turn; at session creation there is no turn to do it in. * **`image` / `audio`** have no known use case. Model system slots are typically text-only (Anthropic's `system` accepts text blocks only, and OpenAI's `instructions` is a plain string), so an agent would have to deliver media elsewhere, such as a developer or user message at the start of the conversation, the way Claude Code delivers CLAUDE.md. The append rules allow that, but no client needs it yet. * **`resource`** (embedded content) is the borderline case — inline delivery, can carry text mime-types — and is the plausible first future sub-capability if a real use case emerges. It's excluded from the baseline because it adds URI/mime handling with no known consumer. Keeping the baseline at text keeps the implementation floor low — an advertising agent just concatenates strings — which maximizes adoption. Richer types can be added later as sub-capabilities without breaking changes. ### Why a `systemPrompt` object instead of a separate mode field? An earlier draft used a bare `ContentBlock[]` plus a sibling `systemPromptMode` field. That allowed a mode without a prompt and needed extra client and agent rules to rule it out. An object keeps `mode` and `content` together, gives agent-specific options (such as Claude's `excludeDynamicSections`) a `_meta` slot scoped to the prompt, and is a single field to repeat on lifecycle requests. It also matches existing shapes. Elicitation selects its behavior with a `mode` field and gates each mode with a sub-capability, and both `claude-agent-acp`'s `_meta.systemPrompt` and Goose's `_goose/unstable/session/system-prompt/set` carry the mode alongside the text. ### What does override replace in existing harnesses? Every surveyed harness replaces only its own default instructions. Tools stay available, and workspace context such as project instruction files is still supplied, either elsewhere in the conversation or appended after the replaced text: | Harness | Append | Override | Still supplied after override | | - | - | - | - | | Claude Code / Agent SDK | `--append-system-prompt`, preset `append` | `--system-prompt`, custom `systemPrompt` string | Tools, CLAUDE.md, and environment details, which Claude Code delivers in the conversation rather than the system prompt. The preset's tool guidance and safety instructions are replaced ([docs](https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts#compare-the-four-approaches)). | | Codex | `developer_instructions`, delivered as a [developer message](https://github.com/openai/codex/blob/a06545b311fe01e51ce855c7aa5d8da21e9e7aaf/codex-rs/core/src/context/developer_instructions.rs#L22-L24) | `model_instructions_file` / `base_instructions` | AGENTS.md instructions ([separate fragment](https://github.com/openai/codex/blob/a06545b311fe01e51ce855c7aa5d8da21e9e7aaf/codex-rs/core/src/context/user_instructions.rs#L15-L24)), environment context, developer instructions, and tools. | | Goose | Session prompt extras under `# Additional Instructions`; `append` mode of [`_goose/unstable/session/system-prompt/set`](https://github.com/aaif-goose/goose/blob/cd1da62ac539451948cb38d9e4f245ddd03a3a50/crates/goose-sdk-types/src/custom_requests.rs#L189-L218) | Session `system_prompt_override`; `set` mode of the same method | Hints files and prompt extras, [appended after the override](https://github.com/aaif-goose/goose/blob/cd1da62ac539451948cb38d9e4f245ddd03a3a50/crates/goose/src/agents/prompt_manager.rs#L143-L181). | What each harness keeps differs in the details, so this RFD defines override by what it replaces (the agent's built-in default instructions) and what it must not change (tools, MCP servers, permissions, session configuration), and leaves the rest to the agent to document. ### Why re-send the prompt on load, resume, and fork instead of having the agent restore it? An earlier draft required agents to store the prompt and restore it on load and resume, and required forks to inherit it. Existing agents don't agree on where the prompt lives: | Agent | Prompt persisted with the session? | Omitted on resume | Different prompt on resume | | - | - | - | - | | `claude-agent-acp` over Claude Code | The adapter does not store it: it [reads `_meta.systemPrompt` from each request](https://github.com/agentclientprotocol/claude-agent-acp/blob/908c994901b857918c23655670468298f6bbd33b/src/acp-agent.ts#L9426-L9448). Claude Code records the prompt on the session's first request and keeps that record until compaction. | The recorded prompt is used until compaction, then the adapter's default. | The adapter [recreates the live session](https://github.com/agentclientprotocol/claude-agent-acp/blob/908c994901b857918c23655670468298f6bbd33b/src/acp-agent.ts#L9239-L9282), but Claude Code only uses the new text after compaction, or immediately with `snapshot: false` at the cost of the prompt cache ([docs](https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)). | | Codex | Yes: base instructions are stored in the rollout's [`SessionMeta`](https://github.com/openai/codex/blob/a06545b311fe01e51ce855c7aa5d8da21e9e7aaf/codex-rs/protocol/src/protocol.rs#L3237-L3290). | Restored from the rollout; forks inherit them. | Configured `base_instructions` [take precedence](https://github.com/openai/codex/blob/a06545b311fe01e51ce855c7aa5d8da21e9e7aaf/codex-rs/core/src/session/session.rs#L811-L830) over the stored ones. `codex-acp` did not expose a prompt setting when this survey was written. | | Goose | Yes: [override and extras live on the session](https://github.com/aaif-goose/goose/blob/cd1da62ac539451948cb38d9e4f245ddd03a3a50/crates/goose/src/agents/prompt_manager.rs#L55-L58), as does the recipe. | Restored on `session/load`. | Changed through `_goose/unstable/session/system-prompt/set`. | No single storage rule fits all of them. Requiring agents to restore the prompt would force adapters like `claude-agent-acp` to add their own storage, because Claude Code only keeps its record until compaction. Requiring "omitted means no prompt", the rule `additionalDirectories` uses, would force Codex, Goose, and Claude Code to discard a prompt their harness already persists, which Claude Code cannot do before compaction. Asking clients to re-send the prompt, and leaving the omitted case implementation-defined, works with all of them and matches how clients already treat `cwd` and `mcpServers`. ### How does a client remove a prompt from an existing session? It can't through this RFD. Omitting `systemPrompt` on a lifecycle request leaves the prompt implementation-defined, and clients **MUST NOT** send an empty `content` array. Changing the prompt of a live session, including removing it, is out of scope (see the alternatives below). A client that needs a session without its earlier prompt can create a new session. ### How does this interact with session config options and modes? [Session config options](https://agentclientprotocol.com/protocol/session-config-options) (and v1 session modes) are agent-defined settings the client selects from; `systemPrompt` is client-authored content. They are independent mechanisms. Selecting a mode or config option does not remove the client-provided prompt, but how an agent combines its own mode- or config-driven instructions with it is implementation-defined — for example, an agent may add plan-mode instructions alongside an appended client prompt. ### Why include both append and override in the first version? Append alone looked sufficient until we accounted for existing harness behavior: Claude Code, Codex, and Goose all ship both a replace option and an append option, so ACP adapters over them could expose override on day one — deferring override wouldn't buy simplicity, just a guaranteed second design round. The two modes have different safety postures, which the design reflects: append is the baseline (agents keep their own instructions), while override requires the agent to advertise the `override` sub-capability *and* the client to explicitly request the mode. An agent that never wants to give up its default instructions simply advertises `systemPrompt: {}` and never sees an override request. ### What alternative approaches did you consider, and why did you settle on this one? * **`systemPrompt` on `session/prompt` (per-turn)**: Would allow mid-session updates, matching how most LLM APIs send system content per-request. But it introduces ambiguous semantics when `systemPrompt` is omitted on a turn (inherit last value? revert to default?) and moves system prompt delivery from a one-time configuration to a repeated per-turn concern. For the common case — set instructions once at session start — `session/new` is simpler and sufficient. * **Dedicated `session/set_system_prompt` method**: Changing the prompt of a live session is a separate feature; Goose already ships one as `_goose/unstable/session/system-prompt/set`. This RFD covers session creation and the lifecycle requests, and a dedicated method can be added later without conflicting with it. * **Standardize `_meta.systemPrompt`**: Violates `_meta` design intent (see Status quo). * **CWD file conventions** (e.g., placing instruction files in the session `cwd`): Agent-specific, not portable, and relies on the agent voluntarily reading the file. Not a protocol-level solution. * **Environment variables or CLI flags**: Pre-session only, not portable across agent implementations, can't be session-specific without restarting the agent. ## Revision history * 2026-05-18: Initial draft * 2026-05-19: Upgraded to MUST with response acknowledgment per PR review feedback * 2026-05-21: Replaced the response acknowledgment (`systemPromptStatus`) with a JSON-RPC error when the agent cannot apply the prompt * 2026-07-21: Capability-gated opt-in under `sessionCapabilities`, type changed to `ContentBlock[]` with text-only baseline, explicit append/override delivery modes with `override` sub-capability, invalid-combination and load/resume/fork semantics — per maintainer review * 2026-10-09: Moved to Draft. Replaced the bare array and `systemPromptMode` with a `systemPrompt` object, grouped the `override` capability under `mode`, accepted it on load/resume/fork with re-send semantics based on a survey of existing agents, covered ACP v1 and v2, defined what override replaces, and relaxed requirements that agents could not observe or implement * 2026-10-12: Added the unstable v1 and v2 schema behind `unstable_session_system_prompt`, with draft docs. Made `mode` extensible under the enum variant extension rule * 2026-10-30: Moved to Preview. Clients must not send an empty `content` array, and Agents may reject one. Added the Claude Agent and Codex adapter implementations * 2026-11-06: Moved to Completed. Stabilized `systemPrompt` and its capability in both protocol versions with the Preview semantics unchanged. Protocol v2 remains draft overall # Configurable LLM Providers Source: https://agentclientprotocol.com/rfds/custom-llm-endpoint * Author(s): [@anna239](https://github.com/anna239), [@xtmq](https://github.com/xtmq) ## Elevator pitch > What are you proposing to change? Add the ability for clients to discover and configure agent LLM providers (identified by `id`) via dedicated provider methods: * `providers/list` * `providers/set` * `providers/disable` This allows clients to route LLM requests through their own infrastructure (proxies, gateways, or self-hosted models) without agents needing to know about this configuration in advance. ## Status quo > How do things work today and what problems does this cause? Why would we change things? ACP does not currently define a standard method for configuring LLM providers. In practice, provider configuration is usually done via environment variables or agent-specific config files. That creates several problems: * No standard way for clients to discover what providers an agent exposes * No standard way to update one specific provider by id * No standard way to disable a specific provider at runtime while preserving provider discoverability * Secret-bearing values in headers are difficult to handle safely when configuration must be round-tripped This particularly affects: * **Client proxies**: clients want to route agent traffic through their own proxies, for example to add headers or logging * **Enterprise deployments**: organizations want to route LLM traffic through internal gateways for compliance, logging, and cost controls * **Self-hosted models**: users running local servers (vLLM, Ollama, etc.) need to redirect agent traffic to local infrastructure * **API gateways**: organizations using multi-provider routing, rate limiting, and caching need standardized endpoint configuration ## Shiny future > How will things play out once this feature exists? Clients will be able to: 1. Understand whether an agent supports client-managed LLM routing 2. See where the agent is currently sending LLM requests (for example in settings UI) 3. Route agent LLM traffic through their own infrastructure (enterprise proxy, gateway, self-hosted stack) 4. Update routing settings from the client instead of relying on agent-specific env vars 5. Disable a provider when needed and later re-enable it explicitly 6. Apply these settings before starting new work in sessions ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? ### Intended flow ```mermaid theme={null} sequenceDiagram participant Client participant Agent Client->>Agent: initialize Agent-->>Client: initialize response (agentCapabilities.providers = {}) Client->>Agent: providers/list Agent-->>Client: providers/list response Client->>Agent: providers/set (id = "main") Agent-->>Client: providers/set response Client->>Agent: providers/disable (optional) Agent-->>Client: providers/disable response Client->>Agent: session/new ``` 1. Client initializes and checks `agentCapabilities.providers`. 2. Client calls `providers/list` to discover available providers, their current routing targets (or disabled state), supported protocol types, and whether they are required. 3. Client calls `providers/set` to apply new (required) configuration for a specific provider ID. 4. Client may call `providers/disable` when a non-required provider should be disabled. 5. Client creates or loads sessions. ### Capability advertisement The agent advertises support with an empty object capability: ```typescript theme={null} interface AgentCapabilities { // ... existing fields ... /** * Provider configuration support. * If present, the agent supports providers/list, providers/set, and providers/disable. */ providers?: {}; } ``` If `providers` is absent, clients must treat provider methods as unsupported. ### Types ```typescript theme={null} /** * Well-known API protocol identifiers for LLM providers. * * This is an open string type: agents and clients MUST handle unknown * protocol identifiers gracefully. * * Protocol names beginning with `_` are free for custom use, like other * ACP extension methods. Protocol names that do not begin with `_` are * reserved for the ACP spec. */ type LlmProtocol = "anthropic" | "openai" | "azure" | "vertex" | "bedrock" | string; interface ProviderCurrentConfig { /** Protocol currently used by this provider. */ apiType: LlmProtocol; /** Base URL currently used by this provider. */ baseUrl: string; } type ProviderId = string; interface ProviderInfo { /** Provider identifier, for example "main" or "openai". */ providerId: ProviderId; /** Supported protocol types for this provider. */ supported: LlmProtocol[]; /** * Whether this provider is mandatory and cannot be disabled via providers/disable. * If true, clients must not call providers/disable for this provider ID. */ required: boolean; /** * Current effective non-secret routing config. * Null or omitted means provider is disabled. */ current?: ProviderCurrentConfig | null; /** Extension metadata */ _meta?: Record; } ``` ### `providers/list` ```typescript theme={null} interface ProvidersListRequest { /** Extension metadata */ _meta?: Record; } interface ProvidersListResponse { /** Configurable providers with current routing info suitable for UI display. */ providers: ProviderInfo[]; /** Extension metadata */ _meta?: Record; } ``` ### `providers/set` `providers/set` updates the full configuration for one provider ID. ```typescript theme={null} interface SetProviderRequest { /** Provider ID to configure. */ providerId: ProviderId; /** Protocol type for this provider. */ apiType: LlmProtocol; /** Base URL for requests sent through this provider. */ baseUrl: string; /** * Full headers map for this provider. * May include authorization, routing, or other integration-specific headers. * Omitting this field is equivalent to an empty map (no headers). */ headers?: Record; /** Extension metadata */ _meta?: Record; } interface SetProviderResponse { /** Extension metadata */ _meta?: Record; } ``` ### `providers/disable` ```typescript theme={null} interface DisableProviderRequest { /** Provider ID to disable. */ providerId: ProviderId; /** Extension metadata */ _meta?: Record; } interface DisableProviderResponse { /** Extension metadata */ _meta?: Record; } ``` ### Example exchange **initialize Response:** ```json theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentInfo": { "name": "MyAgent", "version": "2.0.0" }, "agentCapabilities": { "providers": {}, "sessionCapabilities": {} } } } ``` **providers/list Request:** ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "providers/list", "params": {} } ``` **providers/list Response:** ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "providers": [ { "providerId": "main", "supported": ["bedrock", "vertex", "azure", "anthropic"], "required": true, "current": { "apiType": "anthropic", "baseUrl": "http://localhost/anthropic" } }, { "providerId": "openai", "supported": ["openai"], "required": false, "current": null } ] } } ``` **providers/set Request:** ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "providers/set", "params": { "providerId": "main", "apiType": "anthropic", "baseUrl": "https://llm-gateway.corp.example.com/anthropic/v1", "headers": { "X-Request-Source": "my-ide" } } } ``` **providers/set Response:** ```json theme={null} { "jsonrpc": "2.0", "id": 2, "result": {} } ``` **providers/disable Request:** ```json theme={null} { "jsonrpc": "2.0", "id": 3, "method": "providers/disable", "params": { "providerId": "openai" } } ``` **providers/disable Response:** ```json theme={null} { "jsonrpc": "2.0", "id": 3, "result": {} } ``` ### Behavior 1. **Capability discovery**: agents that support provider methods MUST advertise `agentCapabilities.providers: {}` in `initialize`. Clients SHOULD only call `providers/*` when this capability is present. 2. **Timing and session impact**: provider methods MUST be called after `initialize`. Clients SHOULD configure providers before creating or loading sessions. Agents MAY choose not to apply changes to already running sessions, but SHOULD apply them to sessions created or loaded after the change. 3. **List semantics**: `providers/list` returns configurable providers, their supported protocol types, current effective routing, and `required` flag. Providers SHOULD remain discoverable in list after `providers/disable`. 4. **Client behavior for required providers**: clients SHOULD NOT call `providers/disable` for providers where `required: true`. 5. **Disabled state encoding**: in `providers/list`, `current` omitted or `current: null` means the provider is disabled and MUST NOT be used by the agent for LLM calls. 6. **Set semantics and validation**: `providers/set` replaces the full configuration for the target `id` (`apiType`, `baseUrl`, `headers`); an omitted `headers` field is treated as an empty map. If `id` is unknown, `apiType` is unsupported for that provider, or params are malformed, agents SHOULD return `invalid_params`. 7. **Disable semantics**: `providers/disable` disables the target provider at runtime. A disabled provider MUST appear in `providers/list` with `current` omitted or `current: null`. If target provider has `required: true`, agents MUST return `invalid_params`. Disabling an unknown `id` SHOULD be treated as success (idempotent behavior). 8. **Scope and persistence**: provider configuration is process-scoped and SHOULD NOT be persisted to disk. ## Frequently asked questions > What questions have arisen over the course of authoring this document? ### What does `null` mean in `providers/list`? `current` omitted or `current: null` means the provider is disabled. When disabled, the agent MUST NOT route LLM calls through that provider until the client enables it again with `providers/set`. ### Why is there a `required` flag? Some providers are mandatory for agent operation and must not be disabled. `required` lets clients hide or disable the provider-disable action in UI and avoid calling `providers/disable` for those ids. ### Why not a single `providers/update` method for full list replacement? A full-list update means the client must send complete configuration (including `headers`) for all providers every time. If the client wants to change only one provider, it may not know headers for the others. In that case it cannot safely build a correct full-list payload. Also, `providers/list` does not return headers, so the client cannot simply "take what the agent returned" and send it back with one edit. Per-provider methods (`set` and `disable`) avoid this problem and keep updates explicit. ### Why doesn't `providers/list` return headers? Header values may contain secrets and should not be echoed by the agent. `providers/list` is intentionally limited to non-secret routing information (`current.apiType`, `current.baseUrl`). ### Why are `providers/list` and `providers/set` payloads different? `providers/set` accepts `headers`, including secrets, and is write-oriented. `providers/list` is read-oriented and returns only non-secret routing summary (`current`) for UI and capability discovery. ### Why is this separate from `initialize` params? Clients need capability discovery first, then provider discovery, then configuration. A dedicated method family keeps initialization focused on negotiation and leaves provider mutation to explicit steps. ### Why not use `session-config` with a `provider` category instead? `session-config` is a possible alternative, and we may revisit it as the spec evolves. We did not choose it as the primary approach in this proposal because provider routing here needs dedicated semantics that are difficult to express with today's session config model: * Multiple providers identified by `id`, each with its own lifecycle * Structured payloads (`apiType`, `baseUrl`, full `headers` map) rather than simple scalar values * Explicit discoverable (`providers/list`) and disable (`providers/disable`) semantics Today, `session-config` values are effectively string-oriented and do not define a standard multi-value/structured model for this use case. ## Revision history * 2026-04-19: Made `ProviderInfo.current` optional in `providers/list`; disabled state may be encoded as omitted `current` or `current: null` * 2026-03-22: Finalized provider disable semantics - `providers/remove` renamed to `providers/disable`, required providers are non-disableable, and disabled state is represented as `current: null` * 2026-03-21: Initial draft of provider configuration API (`providers/list`, `providers/set`, `providers/remove`) * 2026-03-07: Rename "provider" to "protocol" to reflect API compatibility level; make `LlmProtocol` an open string type with well-known values; resolve open questions on identifier standardization and model availability * 2026-03-04: Revised to use dedicated `setLlmEndpoints` method with capability advertisement * 2026-02-02: Initial draft - preliminary proposal to start discussion # Elicitation: Structured User Input Source: https://agentclientprotocol.com/rfds/elicitation * Author(s): [@yordis](https://github.com/yordis) * Champion: [@benbrandt](https://github.com/benbrandt) ## Elevator pitch Add support for agents to request information from users through a standardized elicitation mechanism, aligned with the form and URL data model in the locked [MCP 2026-07-28 release candidate](https://modelcontextprotocol.io/specification/draft/client/elicitation). This allows agents to ask follow-up questions, coordinate secure authentication flows, gather preferences, and request required information without ad-hoc client UI implementations. ## Status quo Currently, agents have two limited mechanisms for gathering user input: 1. **Session Config Options** (PR #210): Pre-declared, persistent configuration (model, mode, etc.) with default values required. These are available at session initialization and changes are broadcast to the client. 2. **Unstructured text in turn responses**: Agents can include prompts in their responses, but clients have no standardized way to recognize auth requests, form inputs, or structured selections, leading to inconsistent UX across agents. However, there is no mechanism for agents to: * Request ad-hoc information during a turn (e.g., "Which of these approaches should I proceed with?" from PR #340) * Coordinate authentication without passing credentials through ACP (pain point from PR #330) * Collect open-ended text input with validation constraints * Handle decision points that weren't anticipated at session initialization * Request sensitive information via out-of-band mechanisms (browser-based OAuth) The community has already identified the need for this: PR #340 explored a `session/select` mechanism but concluded that leveraging an MCP-like elicitation pattern would be more aligned with how clients will already support MCP servers. PR #330 recognized that authentication requests specifically need special handling separate from regular session data. This gap limits the richness of agent-client interaction and forces both agents and clients to implement ad-hoc solutions for structured user input. ## What we propose to do about it We propose introducing an elicitation mechanism for agents to request information from users, aligned with the locked [MCP 2026-07-28 release-candidate elicitation specification](https://modelcontextprotocol.io/specification/draft/client/elicitation). This addresses discussions from PR #340 about standardizing user selection flows and PR #330 about secure authentication handling. The mechanism would: 1. **Use restricted JSON Schema** (as discussed in PR #210): Like MCP, constrain JSON Schema to a useful subset—flat objects with primitive properties (`string`, `number`, `integer`, `boolean`) plus supported formats and enum values. Clients decide how to render UI based on the schema. 2. **Support two elicitation modes** (drawing on the historical design in [MCP SEP-1036](https://modelcontextprotocol.io/seps/1036-url-mode-elicitation-for-secure-out-of-band-intera); the locked release candidate is the normative alignment target): * **Form mode** (in-band): Structured data collection via JSON Schema forms * **URL mode** (out-of-band): Browser-based flows for sensitive operations like OAuth (addressing PR #330 authentication pain points) 3. **Request/response pattern**: Agents send elicitation requests via an `elicitation/create` method and receive responses. The agent controls when to send requests and whether to wait for responses before proceeding. Unlike Session Config Options (which are persistent), elicitation requests are transient. 4. **Support client capability negotiation**: Clients declare elicitation support via a structured capability object that distinguishes between `form`-based and `url`-based elicitation (following MCP's capability model). This allows clients to support one or both modalities, enables agents to pass capabilities along to MCP servers, and handles graceful degradation when clients have limited elicitation support. 5. **Provide rich context**: Agents can include title, description, detailed constraints, and examples—helping clients render consistent, helpful UI without custom implementations. 6. **Enable out-of-band flows**: Support URL-mode elicitation (like MCP) for sensitive operations like authentication, where credentials do not transit over ACP or enter the Client or model context (addressing the core pain point in PR #330). ## Shiny future Once implemented, agents can: * Ask users "Which approach would you prefer: A or B?" and receive a structured response * Request text input: "What's the name for this function?" * Collect multiple related pieces of information in a single request * Guide users through decision trees with follow-up questions * Provide rich context (descriptions, examples, constraints) for what they're asking for Clients can: * Present a consistent, standardized UI for elicitation across all agents * Validate user input against constraints before sending to the agent * Cache elicitation history and offer suggestions based on previous responses * Provide keyboard shortcuts and accessibility features for common elicitation types ## Implementation details and plan ### Alignment with MCP This proposal adopts the form and URL payloads, response actions, restricted JSON Schema approach, and safety guidance from the locked [MCP 2026-07-28 release-candidate elicitation specification](https://modelcontextprotocol.io/specification/draft/client/elicitation). MCP delivers an `elicitation/create` input request inside an `InputRequiredResult`, after which the Client retries the originating request. ACP adapts that data model to its persistent bidirectional connection by sending `elicitation/create` directly from the Agent to the Client. Key differences from MCP: * MCP carries elicitation only inside an `InputRequiredResult` associated with an originating Client request; ACP sends a direct request and makes its scope explicit as session-scoped, tool-call-scoped, or request-scoped * ACP requires an explicit `mode`; MCP permits form mode requests to omit it * ACP negotiates Client capabilities during initialization, while MCP 2026-07-28 carries them per request * ACP requires `form` or `url` to be explicitly advertised in Client capabilities; unlike MCP, an empty capability object does not imply form support * ACP URL requests add `elicitationId` and MAY be followed by `elicitation/complete`; MCP 2026-07-28 has neither and determines completion when the Client retries the originating request * ACP has no separate URL-required error; Agents request URL mode directly * ACP includes an optional `toolCallId` field to support tool-call-scoped elicitations (e.g., when an agent receives an MCP elicitation during a tool call and needs to redirect it to the user) * ACP omits MCP's optional `$schema` field because ACP fixes the exact restricted schema subset rather than allowing the sender to select or annotate a schema dialect * ACP extends MCP's restricted schema subset with `pattern`, schema-level `title` and `description`, descriptions on titled enum options, and `_meta`. ACP preserves unknown schema types and response actions for forward compatibility, and does not support MCP's deprecated `enumNames` * ACP must integrate with existing Session Config Options (which also use schema constraints) ### Elicitation Request Structure Agents send elicitation requests when they need information from the user. This is a request/response pattern—the agent sends the request and waits for the client's response. **Example 1: Form Mode - User Selection (from PR #340)** ```json theme={null} { "sessionId": "sess_abc123", "mode": "form", "message": "How would you like me to approach this refactoring?", "requestedSchema": { "type": "object", "properties": { "strategy": { "type": "string", "title": "Refactoring Strategy", "description": "Choose how aggressively to refactor", "oneOf": [ { "const": "conservative", "title": "Conservative - Minimal changes", "description": "Make minimal changes and avoid broad cleanup." }, { "const": "balanced", "title": "Balanced (Recommended)", "description": "Fix the issue and clean nearby code when it lowers risk." }, { "const": "aggressive", "title": "Aggressive - Maximum optimization", "description": "Refactor more broadly to optimize the affected area." } ], "default": "balanced" } }, "required": ["strategy"] } } ``` **Example 2: URL Mode - Authentication (from PR #330, out-of-band OAuth)** ```json theme={null} { "requestId": 12, "mode": "url", "elicitationId": "github-oauth-123", "url": "https://agent.example.com/connect?elicitationId=github-oauth-123", "message": "Please authorize access to your GitHub repositories to continue." } ``` **Example 3: Form Mode - Text Input with Constraints** ```json theme={null} { "sessionId": "sess_abc123", "mode": "form", "message": "What should this function be named?", "requestedSchema": { "type": "object", "properties": { "name": { "type": "string", "title": "Function Name", "description": "Must be a valid identifier", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$", "default": "processData" } }, "required": ["name"] } } ``` **Example 4: Form Mode - Multiple Fields** ```json theme={null} { "sessionId": "sess_abc123", "mode": "form", "message": "Please provide configuration details", "requestedSchema": { "type": "object", "properties": { "name": { "type": "string", "title": "Project Name" }, "port": { "type": "integer", "title": "Port Number", "minimum": 1024, "maximum": 65535, "default": 3000 }, "enableLogging": { "type": "boolean", "title": "Enable Logging", "default": true } }, "required": ["name"] } } ``` ### Elicitation Modes Following the locked MCP release candidate's approach, elicitation supports two modes. [SEP-1036](https://modelcontextprotocol.io/seps/1036-url-mode-elicitation-for-secure-out-of-band-intera) provides historical design background for URL mode. **Form mode** (in-band): Agents request structured data from users using restricted JSON Schema. The Client decides how to render the form UI based on the schema. **URL mode** (out-of-band): Agents direct users to external URLs for sensitive interactions. Inputs entered during the interaction do not transit over ACP or enter the Client or model context (OAuth flows, payments, credential collection, etc.). This distinction is reflected in the client capabilities model, allowing clients to declare support for one or both modalities. **Normative requirements:** * Form support exists only when `form` is present and non-null, and URL support exists only when `url` is present and non-null. `{}` and objects whose mode fields are all omitted or `null` advertise no supported modes. * Agents MUST NOT send elicitation requests with modes that are not supported by the client. * For URL mode, the `url` parameter MUST contain a valid URL. Unknown elicitation `mode` values are reserved for future ACP variants or implementation-specific extensions. Implementation-specific modes MUST begin with `_`. Clients that do not understand a mode should preserve the raw payload when storing, replaying, proxying, or forwarding elicitation requests, but MUST NOT render it as `form` or `url` or otherwise treat it as supported. ### User Interaction Requirements Clients MUST clearly identify the Agent requesting information, respect user privacy, and provide clear decline and cancel controls. For form mode, Clients MUST let users review and modify responses before sending them. For URL mode, Clients MUST display the target host and obtain consent before navigating to it. Clients SHOULD present the request's `message` so users understand what is requested and why. ### Restricted JSON Schema Aligning with the locked [MCP 2026-07-28 release-candidate elicitation specification](https://modelcontextprotocol.io/specification/draft/client/elicitation), form mode elicitation uses a restricted subset of JSON Schema. Schemas are limited to flat objects with primitive properties only—the client decides how to render appropriate input UI based on the schema. Senders MUST include both `type: "object"` and `properties` in every `requestedSchema`. For compatibility, ACP readers tolerate an omitted, `null`, or malformed `type` by treating it as `"object"`, and tolerate omitted `properties` by treating it as an empty map; `null` is not valid for `properties`. This reader tolerance does not relax the sender requirements. ACP does not include MCP's optional `$schema` field because the ACP protocol defines the exact restricted subset and does not support sender-selected schema dialects. ACP extends MCP's restricted subset with `pattern`, schema-level `title` and `description`, descriptions on titled enum options, and `_meta`. It also preserves unknown schema types and response actions for forward compatibility. ACP does not support MCP's deprecated `enumNames`; use `oneOf` for titled single-select choices and `anyOf` for titled multi-select choices. **Supported primitive types:** 1. **String Schema** ```json theme={null} { "type": "string", "title": "Display Name", "description": "Description text", "minLength": 3, "maxLength": 50, "pattern": "^[A-Za-z]+$", "format": "email", "default": "user@example.com" } ``` Because `pattern` is supplied by an Agent, implementations that evaluate it MUST use a regex engine or execution limits that bound evaluation time and resource use. A malicious or pathological pattern MUST NOT be allowed to block Client UI or unboundedly consume resources. Known formats include `email`, `uri`, `date`, and `date-time`. Other string format values are annotations. Implementations MUST preserve unknown formats when storing, replaying, proxying, or forwarding schemas and MUST NOT reject a schema solely because its string format is unknown. 2. **Number Schema** ```json theme={null} { "type": "number", "title": "Display Name", "description": "Description text", "minimum": 0, "maximum": 100, "default": 50 } ``` Also supports `"type": "integer"` for whole numbers. 3. **Boolean Schema** ```json theme={null} { "type": "boolean", "title": "Display Name", "description": "Description text", "default": false } ``` 4. **Enum Schema** (for selections) Single-select enum (without titles): ```json theme={null} { "type": "string", "title": "Color Selection", "description": "Choose your favorite color", "enum": ["Red", "Green", "Blue"], "default": "Red" } ``` Single-select enum (with titles): ```json theme={null} { "type": "string", "title": "Color Selection", "description": "Choose your favorite color", "oneOf": [ { "const": "#FF0000", "title": "Red", "description": "High emphasis and warning-oriented." }, { "const": "#00FF00", "title": "Green", "description": "Positive status and success-oriented." }, { "const": "#0000FF", "title": "Blue", "description": "Neutral and informational." } ], "default": "#FF0000" } ``` Multi-select enum (without titles): ```json theme={null} { "type": "array", "title": "Color Selection", "description": "Choose your favorite colors", "minItems": 1, "maxItems": 2, "items": { "type": "string", "enum": ["Red", "Green", "Blue"] }, "default": ["Red", "Green"] } ``` Multi-select enum (with titles): ```json theme={null} { "type": "array", "title": "Color Selection", "description": "Choose your favorite colors", "minItems": 1, "maxItems": 2, "items": { "anyOf": [ { "const": "#FF0000", "title": "Red", "description": "High emphasis and warning-oriented." }, { "const": "#00FF00", "title": "Green", "description": "Positive status and success-oriented." }, { "const": "#0000FF", "title": "Blue", "description": "Neutral and informational." } ] }, "default": ["#FF0000", "#00FF00"] } ``` Unknown multi-select `items.type` values are reserved for future ACP variants or implementation-specific extensions. Implementation-specific values MUST begin with `_`. Clients that do not understand a multi-select item type should preserve the raw `items` schema when storing, replaying, proxying, or forwarding elicitation requests, but MUST NOT render it as string multi-select items. **Request schema structure:** ```json theme={null} { "requestedSchema": { "type": "object", "properties": { "propertyName": { "type": "string", "title": "Display Name", "description": "Description of the property" }, "anotherProperty": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": ["propertyName"] } } ``` **Not supported** (to simplify client implementation): * Complex nested objects/arrays (beyond enum arrays) * Conditional validation Unknown property schema `type` values are reserved for future ACP variants or implementation-specific extensions. Implementation-specific values MUST begin with `_`. Clients that do not understand a property schema type should preserve the raw schema when storing, replaying, proxying, or forwarding elicitation requests, but MUST NOT render it as a known input control. Clients use this schema to generate appropriate input forms, validate user input before sending, and provide better guidance to users. All primitive types support optional default values; clients SHOULD pre-populate form fields with these values. **Security note:** Following MCP, Agents MUST NOT use form mode elicitation to request secrets or credentials that grant access or authorize transactions, such as passwords, API keys, access or refresh tokens, private keys, recovery codes, or payment credentials. Ordinary profile information such as a name, email address, or username is not categorically prohibited. Sensitive interactions MUST use URL mode, where inputs do not transit over ACP or enter the Client or model context. If the Client does not support URL mode, the Agent MUST NOT fall back to form mode; it MUST use another safe flow or fail the operation. ### Elicitation Request The agent sends an `elicitation/create` request when it needs information from the user: **Form mode example:** ```json theme={null} { "jsonrpc": "2.0", "id": 43, "method": "elicitation/create", "params": { "sessionId": "...", "toolCallId": "tc_123", "mode": "form", "message": "How would you like me to approach this refactoring?", "requestedSchema": { "type": "object", "properties": { "strategy": { "type": "string", "title": "Refactoring Strategy", "oneOf": [ { "const": "conservative", "title": "Conservative", "description": "Make minimal changes and avoid broad cleanup." }, { "const": "balanced", "title": "Balanced (Recommended)", "description": "Fix the issue and clean nearby code when it lowers risk." }, { "const": "aggressive", "title": "Aggressive", "description": "Refactor more broadly to optimize the affected area." } ], "default": "balanced" } }, "required": ["strategy"] } } } ``` **URL mode example:** ```json theme={null} { "jsonrpc": "2.0", "id": 44, "method": "elicitation/create", "params": { "requestId": 12, "mode": "url", "elicitationId": "github-oauth-001", "url": "https://agent.example.com/connect?elicitationId=github-oauth-001", "message": "Please authorize access to your GitHub repositories." } } ``` URL mode is not a substitute for authorizing the Client's access to the Agent. Agents MUST NOT send credentials or tokens obtained through URL mode back over ACP or place them in Client or model context. The scope fields are flattened at the top level of the request. Elicitation supports two scoping variants: * **Session scope**: `sessionId` is set — tied to a specific session. Optionally includes `toolCallId` when tied to a specific tool call within that session (e.g., when an agent receives an elicitation from an MCP server during a tool call and needs to redirect it to the user). * **Request scope**: `requestId` is set — tied to a specific JSON-RPC request outside of a session (e.g., auth/configuration phases before any session is started). Agents MUST bind every elicitation and its related state to the receiving Client connection and, when authentication exists, the verified user identity. A `sessionId` alone or an unverified Client-provided identity is not sufficient. **Request-scoped example:** ```json theme={null} { "jsonrpc": "2.0", "id": 45, "method": "elicitation/create", "params": { "requestId": 12, "mode": "form", "message": "Please provide your workspace name to continue setup.", "requestedSchema": { "type": "object", "properties": { "workspaceName": { "type": "string", "title": "Workspace Name", "description": "The name of your workspace" } }, "required": ["workspaceName"] } } } ``` The client presents the elicitation UI to the user. For form mode, the client generates appropriate input UI based on the JSON Schema. For URL mode, the client opens the URL in a secure browser context. ### User Response Elicitation responses use a three-action model (following MCP) to clearly distinguish between different user actions: **Accept** - User explicitly approved and submitted with data: ```json theme={null} { "jsonrpc": "2.0", "id": 43, "result": { "action": "accept", "content": { "strategy": "balanced" } } } ``` **Decline** - User explicitly declined the request: ```json theme={null} { "jsonrpc": "2.0", "id": 43, "result": { "action": "decline" } } ``` **Cancel** - User dismissed without making an explicit choice (closed dialog, pressed Escape, etc.): ```json theme={null} { "jsonrpc": "2.0", "id": 43, "result": { "action": "cancel" } } ``` The `content` field is optional on `accept`; receivers treat omission and `null` equivalently. It is only meaningful for `accept`; receivers ignore it for `decline` and `cancel`. For an accepted form elicitation, `content` SHOULD conform to the original `requestedSchema`. For an accepted URL elicitation, clients normally omit `content` because the interaction happens out of band. Unknown elicitation `action` values are reserved for future ACP variants or implementation-specific extensions. Implementation-specific actions MUST begin with `_`. Agents that do not understand an action should preserve the raw payload when storing, replaying, proxying, or forwarding elicitation responses, but MUST NOT treat it as `accept`, `decline`, or `cancel`. For URL mode elicitation, the response with `action: "accept"` indicates that the user consented to the interaction. It does not mean the interaction is complete—the interaction occurs out-of-band and the client is not aware of the outcome until the agent sends a completion notification. Agents MUST NOT assume an elicitation succeeds. They MUST handle every response action and request or protocol failure by safely falling back, retrying, or failing the originating operation as appropriate: * **Accept**: Process the submitted data * **Decline**: Handle explicit decline (e.g., use default, offer alternatives) * **Cancel**: Handle dismissal (e.g., use default, prompt again later) * **Failure**: Retry only when safe, use an appropriate fallback, or fail the originating operation ### Message Flow #### Form Mode Flow ```mermaid theme={null} sequenceDiagram participant User participant Client participant Agent Note over Agent: Agent initiates elicitation Agent->>Client: elicitation/create (mode: form) Note over User,Client: Present elicitation UI User-->>Client: Provide requested information Note over Agent,Client: Complete request Client->>Agent: Return user response Note over Agent: Continue processing with new information ``` #### URL Mode Flow ```mermaid theme={null} sequenceDiagram participant UserAgent as User Agent (Browser) participant User participant Client participant Agent Note over Agent: Agent initiates elicitation Agent->>Client: elicitation/create (mode: url) Client->>User: Present consent to open URL User-->>Client: Provide consent Client->>UserAgent: Open URL Client->>Agent: Accept response Note over User,UserAgent: User interaction UserAgent-->>Agent: Interaction complete Agent-->>Client: elicitation/complete (optional) Note over Agent: Continue processing with new information ``` ### Completion Notifications for URL Mode Unlike MCP 2026-07-28, which determines URL-flow completion when the Client retries the originating request, ACP retains a completion notification for its direct request flow. The Agent MUST keep each `elicitationId` unique among outstanding URL elicitations on that Agent-Client connection, and the Client MUST treat it as opaque. Agents MAY send `elicitation/complete` when an out-of-band interaction started by URL mode elicitation is completed: ```json theme={null} { "jsonrpc": "2.0", "method": "elicitation/complete", "params": { "elicitationId": "github-oauth-001" } } ``` Agents sending notifications: * MUST only send the notification to the same client that received the original elicitation request * MUST include the `elicitationId` established in the original request Clients: * MUST ignore notifications referencing unknown or already-completed IDs * MAY use this notification to automatically retry requests, update UI, or continue an interaction * SHOULD provide manual controls for the user to retry or cancel if the notification never arrives ### Error Handling Clients MUST return standard JSON-RPC errors for common failure cases: * When the agent sends an `elicitation/create` request with a mode not declared in client capabilities: `-32602` (Invalid params) ACP has no separate URL-required error. Agents request URL mode directly through `elicitation/create`. ### Client Capabilities Clients declare elicitation support during the `initialize` phase via `ClientCapabilities`. The capability uses MCP's `form` and `url` mode structure, with each supported mode advertised explicitly: ```json theme={null} { "jsonrpc": "2.0", "id": 0, "method": "initialize", "params": { "protocolVersion": 1, "clientCapabilities": { "fs": { "readTextFile": true, "writeTextFile": true }, "terminal": true, "elicitation": { "form": {}, "url": {} } }, "clientInfo": { "name": "my-client", "version": "1.0.0" } } } ``` **Capability structure:** * An omitted or `null` top-level `elicitation` field means the Client does not support elicitation. * A present `elicitation.form` object means the Client can render form UI from restricted JSON Schema (strings, numbers, integers, booleans, enums). Omitted or `null` means the field is not advertised. * A present `elicitation.url` object means the Client can open URLs for out-of-band flows (OAuth, payments, credential collection). Omitted or `null` means the field is not advertised. * A present capability object may advertise zero, one, or both modes. `"elicitation": {}` and `"elicitation": {"form": null, "url": null}` advertise no supported modes. This is a deliberate divergence from MCP 2026-07-28. MCP retains a backward-compatible form-only meaning for an empty elicitation capability, but ACP requires the supported mode or modes to be explicit. **Example: Headless client (no browser access):** ```json theme={null} { "elicitation": { "form": {} } } ``` **Example: Simple terminal with URL support only:** ```json theme={null} { "elicitation": { "url": {} } } ``` **Example: Full-featured client:** ```json theme={null} { "elicitation": { "form": {}, "url": {} } } ``` This structure: 1. Allows clients to declare partial support based on their environment 2. Enables agents to translate capabilities for MCP servers they connect to 3. Retains MCP's form and URL mode structure while making support explicit 4. Provides clear semantics for graceful degradation Agents must gracefully handle clients that omit this field, set it to `null`, only advertise one mode, or advertise no supported modes. ### Backward Compatibility * If a Client omits `elicitation` or sets it to `null`, Agents MUST treat elicitation as unsupported. * If a Client only declares `elicitation.form`, Agents MUST NOT send URL-mode elicitation requests. * If a Client only declares `elicitation.url`, Agents MUST NOT send form-mode elicitation requests. * Omitted and `null` mode fields are equivalent and do not advertise that mode. * A present capability object with no non-null mode fields advertises no supported modes, not form support. * Agents SHOULD gracefully fall back when the required mode is unavailable and SHOULD NOT require elicitation support for otherwise unrelated operations. * If an interaction requires secrets or credentials, Agents MUST NOT fall back to form mode when URL mode is unavailable; they MUST use another safe flow or fail the operation. ### Statefulness Most practical uses of elicitation require that the agent maintain state about users: * Whether required information has been collected (e.g., the user's display name via form mode elicitation) * Status of resource access (e.g., API keys or a payment flow via URL mode elicitation) Agents implementing elicitation MUST securely associate this state with the receiving Client connection and, when authentication exists, the verified user identity. Specifically: * State MUST NOT be associated with session IDs alone * State MUST be bound to the Client connection that received the elicitation * State storage MUST be protected against unauthorized access * When an Agent authenticates users, state MUST be bound to the Agent-authenticated user (for example, an identity derived from a verified `sub` claim) Agents MUST NOT rely on client-provided user identification without agent-side verification, as this can be forged. ## Frequently asked questions ### Can an agent request multiple pieces of information at once? Yes—a single form mode elicitation request can include multiple fields in its `requestedSchema`. The schema is an object with multiple properties, and the client renders a form with all requested fields. For sequential information gathering, agents can send multiple elicitation requests and wait for each response before proceeding. This allows agents to adapt follow-up questions based on previous answers. The request/response model gives agents flexibility: they control when to send elicitation requests and whether to wait for responses or continue with other work. ### How does this differ from session config options? Excellent question from PR #210 discussions. Both use restricted JSON Schema, but serve different purposes: | Aspect | Session Config Options | Elicitation | | - | - | - | | **Lifecycle** | Persistent, pre-declared at session init | Transient, request/response | | **Scope** | Session-wide configuration | Single decision point or data collection | | **Defaults** | Required (agents must have defaults) | Optional (schema's `required` array determines mandatory fields) | | **State management** | Client maintains full state, broadcast on changes | Agent receives response and decides how to proceed | | **Use cases** | Model selection, session mode, persistent settings | Authentication, clarifying questions, one-time data collection | Session Config Options are great for "how should you run this session?" Elicitation is for "what should I do next?" ### Why align with MCP's elicitation instead of creating something different? As identified in PR #340, clients will already implement MCP elicitation support for MCP servers. Aligning ACP's elicitation with MCP: * Reduces client implementation burden * Creates consistent UX across MCP and ACP agents * Lets code be shared or reused * Follows the protocol design principle of only constraining when necessary PR #340 specifically concluded: "I think we'd rather have an MCP elicitation story in general, and maybe offer the same interface outside of tool calls." ### How does authentication flow work with URL-mode elicitation? From PR #330: URL-mode elicitation allows agents to request authentication without exposing credentials to the protocol. This flow adapts the safety model from the locked [MCP 2026-07-28 release-candidate elicitation specification](https://modelcontextprotocol.io/specification/draft/client/elicitation), while using ACP's `elicitationId` and completion notification. URL mode does not itself authorize the Client's access to the Agent: 1. Agent sends elicitation request with `mode: "url"`, an `elicitationId`, and a URL to the agent's own connect endpoint (not directly to the OAuth provider) 2. Client displays the URL to the user and requests consent to open it 3. Client responds with `action: "accept"` to indicate the user consented 4. User opens URL in their browser (out-of-band process) 5. Agent's connect page verifies the user identity matches the elicitation request 6. Agent redirects user to the OAuth provider's authorization endpoint 7. User authenticates and grants permission 8. OAuth provider redirects back to the agent's redirect\_uri 9. Agent exchanges the authorization code for tokens and stores them bound to the user's identity 10. Agent sends an `elicitation/complete` notification to inform the client **Key guarantees**: * Agents MUST NOT send credentials or tokens obtained through URL mode over ACP or place them in Client or model context; the Agent's out-of-band service remains responsible for any tokens it receives and stores * The Agent MUST securely store third-party tokens * The Agent MUST verify user identity to prevent phishing attacks **Security requirements** (adapted from the MCP 2026-07-28 release candidate): Agents requesting URL mode elicitation: * MUST NOT include sensitive information about the end-user (credentials, PII, etc.) in the URL * MUST NOT provide a URL which is pre-authenticated to access a protected resource * SHOULD NOT include URLs intended to be clickable in any field of a form mode elicitation request * SHOULD use HTTPS URLs for non-development environments Clients implementing URL mode elicitation: * MUST NOT automatically pre-fetch the URL or any of its metadata * MUST NOT open the URL without explicit consent from the user * MUST show the full URL to the user for examination before consent * MUST open the URL in a secure manner that does not enable the client or LLM to inspect the content or user inputs (e.g., SFSafariViewController on iOS, not WKWebView) * SHOULD highlight the domain of the URL to mitigate subdomain spoofing * SHOULD have warnings for ambiguous/suspicious URIs (e.g., containing Punycode) * SHOULD NOT render URLs as clickable in any field of an elicitation request, except for the `url` field in a URL mode elicitation request (with the restrictions detailed above) **Phishing prevention**: The agent MUST verify that the user who started the elicitation request is the same user who completes the OAuth flow. This is typically done by checking session cookies against the Agent-authenticated user identity. ### Can agents use elicitation for information required before responding? Yes. ACP adapts MCP's elicitation payload model but carries it as a direct request/response, so the Agent controls its own flow. The Agent can: * Send an elicitation request and wait for the response before proceeding * Continue with other work while waiting for user input * Chain multiple elicitations as needed for multi-step workflows This flexibility is why elicitation is modeled as a separate request/response rather than being tightly coupled to turns. ### What if a user doesn't respond to an elicitation request? Elicitation requests require a response. If the user dismisses the elicitation without making an explicit choice (closes the dialog, presses Escape, etc.), the client responds with `action: "cancel"`. The agent then decides how to proceed—it may use a default value, prompt again later, or fail the turn. This ties into the broader request cancellation work: elicitation requests can be cancelled like any other request, and the `cancel` action provides a clear signal that the user chose not to engage rather than explicitly declining. ### Should elicitation support complex nested data structures? We follow MCP's design here. MCP intentionally restricts elicitation schemas to flat objects with primitive properties to simplify client implementation and user experience. Complex nested structures, arrays of objects (beyond enum arrays), and advanced JSON Schema features are explicitly not supported. Future MCP changes do not automatically change ACP; adopting them requires a separate ACP protocol change. ### How should agents handle clients that don't support elicitation? Agents should always design to gracefully degrade: * Check `elicitation.form` and `elicitation.url` capabilities before sending requests * If the required mode is not supported, use a safe fallback when one exists * Describe what they're requesting in turn content (text) as fallback * Continue only when the fallback is appropriate for the operation * Never use a form or turn text as a fallback for secrets or credentials; use another safe out-of-band flow or fail the operation * For agents connecting to MCP servers: translate the client's elicitation capabilities for the MCP server so it can also make informed decisions. Advertise each supported mode explicitly, and omit the MCP capability when the client advertises no modes, since an empty MCP capability means form support ### Can we extend this to replace the existing Permission-Request mechanism? We recommend keeping them separate. Permission requests are fundamentally security decisions—allowing a tool call to proceed is distinct from the model asking for clarification or collecting user preferences. Keeping these separate allows clients to: * Offer a consistent, recognizable UX for security-sensitive decisions (permissions) * Clearly distinguish "the agent needs approval to do something" from "the agent needs information to continue" * Apply different policies (e.g., "always allow file reads" vs. per-request elicitation responses) This is the same reasoning behind keeping authentication flows (URL mode) distinct from data collection (form mode). While we may reuse some types between these mechanisms, conflating the features would blur important security boundaries. ### What about validating user input on the client side? Clients SHOULD validate user input against the provided JSON Schema **before** sending the response to the agent. This prevents invalid data from reaching the agent and provides immediate feedback to the user. Agents SHOULD also validate received data matches the requested schema, as defense-in-depth against malformed or malicious responses. If the agent requires additional validation beyond what's expressible in JSON Schema: 1. Agent validates the received value in the next turn 2. If validation fails, agent can fail the turn with an error 3. Client can then re-prompt the user (or fall back to the original default) For v1, we recommend starting with JSON Schema validation only. If more complex validation patterns emerge from real-world usage, a future RFD can specify additional validation mechanisms. ## Revision history * 2026-10-29: Agents translate, rather than pass through, elicitation capabilities for MCP servers, since `{}` means no modes in ACP but form support in MCP. * 2026-07-22: Moved to Completed and stabilized elicitation in the protocol artifacts. Audited the data model and safety guidance against the locked MCP 2026-07-28 release candidate and documented ACP's direct-request, capability, scope, and URL-completion differences. * 2026-07-09: Moved to Preview. * 2026-07-01: Removed the separate URL-required error flow; URL elicitations use `elicitation/create` and optional `elicitation/complete`. * 2026-02-06: Spec alignment review. Fixed OAuth URL examples to use agent connect endpoints (not direct OAuth provider URLs) per MCP phishing prevention guidance. Added normative requirements section (MUST support at least one mode, MUST NOT send unsupported modes, url MUST be valid). Added Error Handling section for unsupported elicitation modes. Added message flow diagrams (form mode and URL mode). Expanded safe URL handling requirements (pre-fetch prohibition, Punycode warnings, non-clickable URLs in form fields). Added server-side schema validation SHOULD requirement. Added Statefulness subsection with normative requirements for state association and user identification. * 2026-02-05: Major revision to align with the MCP draft elicitation specification. Updated enum schema to use `oneOf`/`anyOf` with `const`/`title` instead of `enumNames`. Added multi-select array support and ACP's `pattern` extension for strings. Added completion notifications and expanded security considerations including phishing prevention. Updated examples to the aligned payload model. * 2026-02-05: Initial MCP alignment. Removed explicit "input types" in favor of restricted JSON Schema (client decides rendering). Added `mode` field (`form`/`url`). Updated capability model to use `form`/`url` sub-objects per MCP SEP-1036. Added three-action response model (`accept`/`decline`/`cancel`). Removed `password` type (MCP prohibits sensitive data in form mode). * 2026-01-12: Initial draft based on community discussions in PR #340 (user selection), PR #210 (session config alignment), and PR #330 (authentication use cases). Aligned with MCP elicitation patterns. # End-Turn Token Usage Source: https://agentclientprotocol.com/rfds/end-turn-token-usage * Author(s): [@ahmedhesham6](https://github.com/ahmedhesham6) * Champion: [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? Explore a standard way for agents to report token usage when a prompt turn ends. This RFD is intentionally kept in Draft while token accounting semantics are still being refined. Session-level context window size and cumulative cost are covered separately in the [Session Context Size and Cost RFD](/rfds/session-usage). ## Status quo > How do things work today and what problems does this cause? Why would we change things? ACP does not currently define a stable token usage shape for completed prompt turns. Agents may receive token accounting from model providers, but provider responses differ in what they count and when the final numbers become available. This creates several problems: * **No standard turn summary** - Clients cannot show a consistent token breakdown after a turn completes * **Provider mismatch** - Input, output, reasoning, and cache token categories do not map cleanly across all providers * **Ambiguous totals** - It is unclear whether reported values should describe only the completed turn or cumulative session usage * **Prompt lifecycle coupling** - The shape needs clear semantics across stop reasons, streaming updates, and model requests The session-level context and cost proposal no longer depends on resolving these token accounting questions. ## What we propose to do about it > What are you proposing to improve the situation? The current strawman is to add an optional `usage` field to the turn-completion signal. In v1, that signal is `PromptResponse`. In v2, where `session/prompt` returns when the prompt is accepted, the same `usage` object is carried on the idle `state_update` that ends foreground work. ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "stopReason": "end_turn", "usage": { "totalTokens": 53000, "inputTokens": 35000, "outputTokens": 12000, "thoughtTokens": 5000, "cachedReadTokens": 5000, "cachedWriteTokens": 1000 } } } ``` For v2, the equivalent carrier is: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "state_update", "state": "idle", "stopReason": "end_turn", "usage": { "totalTokens": 53000, "inputTokens": 35000, "outputTokens": 12000, "thoughtTokens": 5000, "cachedReadTokens": 5000, "cachedWriteTokens": 1000 } } } } ``` This shape is not ready for Preview. The RFD should resolve the open design questions before standardizing it. ### Strawman Fields * `usage` (object, optional, nullable) - Token usage reported for the completed prompt turn * If `usage` is omitted or `null`, the agent is not reporting token usage for this turn. * `totalTokens` (number, required, non-null) - Total token count according to the final accounting semantics * `inputTokens` (number, required, non-null) - Input token count according to the final accounting semantics * `outputTokens` (number, required, non-null) - Output token count according to the final accounting semantics * `thoughtTokens` (number, optional, nullable) - Thought or reasoning tokens, if the model exposes them * `cachedReadTokens` (number, optional, nullable) - Cache read tokens, if the model exposes them * `cachedWriteTokens` (number, optional, nullable) - Cache write tokens, if the model exposes them For the optional token fields, omission and `null` are equivalent. Both mean the agent is not reporting that token category. ### Open Questions 1. **Per-turn vs cumulative** - Should token values describe only the completed prompt turn, cumulative session totals, or both? 2. **Provider category mapping** - How should ACP map provider-specific categories such as reasoning, cache read, cache write, audio, image, or tool-related tokens? 3. **Streaming semantics** - Should partial usage be allowed during streaming, or should the protocol only report final usage on the turn-completion signal? 4. **Stop reason semantics** - Should usage be included for `end_turn`, `max_tokens`, `max_turn_requests`, `refusal`, and `cancelled` stop reasons? 5. **Cost separation** - Should any per-turn cost estimate exist here, or should cost remain exclusively cumulative session state in `usage_update`? 6. **Naming** - Should field names use `Tokens` suffixes, a nested provider breakdown, or another structure that better matches future extensibility? ## Shiny future > How will things will play out once this feature exists? **For Users:** * Users can see how many tokens a completed turn consumed * Users can understand when expensive reasoning or cache behavior affected a turn * Users can compare turn behavior without confusing it with total context window utilization **For Client Implementations:** * Clients can show consistent post-turn usage summaries * Clients can distinguish context window state from turn-level token accounting * Clients can build analytics without depending on provider-specific response shapes **For Agent Implementations:** * Agents get a standard place to report final token accounting when providers expose it * Agents can omit categories they cannot calculate * Agents can avoid forcing provider-specific accounting into session context updates ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? 1. Resolve whether token counts are per-turn, cumulative, or represented as separate fields. 2. Decide which token categories are standardized and how provider-specific categories can be represented without losing information. 3. Decide whether streaming usage updates are part of this RFD or a separate extension. 4. Gate this Rust crate surface behind the `unstable_end_turn_token_usage` feature. 5. Update the prompt lifecycle docs with the final semantics. 6. Update the schema and SDK types after the semantics are stable. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why keep this as a separate RFD? The remaining questions are different from context window and cost reporting. Keeping this RFD separate lets context size and cost move to Preview without locking token accounting into a shape before the protocol has a clearer model for completed turns. ### Why keep token usage out of `usage_update`? `usage_update` reports session-level context size and cumulative cost. End-turn token accounting is tied to turn completion and may need different semantics, especially around per-turn and cumulative model usage. ### Why not move this to Preview with context size and cost? Context size and cost have a clear session-level contract. Token usage still needs agreement on accounting semantics, provider category mapping, and how it interacts with turn completion. ### What alternative approaches did you consider, and why did you settle on this one? **Everything in `usage_update`** - Rejected for now because turn-level token accounting should not be conflated with session context state. **Only cumulative totals** - Simple for dashboards, but less useful for understanding the cost of a specific completed prompt turn. **Only per-turn totals** - Useful for post-turn summaries, but may not satisfy clients that want cumulative session analytics. **Provider-specific blobs** - Preserves information, but makes client UI inconsistent and harder to standardize. ## Revision history * 2026-06-02: Split from the original combined session usage and context RFD for separate draft discussion. # Agent Authentication State Query Source: https://agentclientprotocol.com/rfds/get-auth-state * Author(s): [@xtmq](https://github.com/xtmq) * Champion: [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? Add an `auth/status` method, an `auth/status_update` notification, and a corresponding capability that let clients query and follow the agent's current authentication state. This lets clients determine whether the agent is already configured with credentials or requires authorization before creating a session, without relying on the ambiguous error behavior of `session/new`, and show which account or credentials the agent is using. ## Status quo > How do things work today and what problems does this cause? Why would we change things? Currently, there is no dedicated way for a client to determine whether an agent has valid authentication configured. The typical workaround is: 1. Call `initialize` 2. Call `session/new` 3. If the agent has no credentials, it *may* return an authorization error 4. The client handles the error and initiates an authorization flow This approach has significant problems: * **Unreliable detection**: The `session/new` method is not required by the specification to check authorization. Some agents validate credentials eagerly, others do so lazily (e.g., on the first LLM call). The client cannot rely on `session/new` to consistently surface auth issues. * **Wasted resources**: Creating a session only to discard it on auth failure is wasteful, especially if session creation has side effects (resource allocation, logging, history file creation, etc.). * **Poor user experience**: The client cannot proactively guide the user through authorization before session creation. Instead, users encounter errors mid-flow. ## Shiny future > How will things play out once this feature exists? Clients will be able to: 1. Discover whether an agent supports auth state queries via capabilities during initialization 2. Query the agent's current authentication state immediately after initialization 3. Make an informed decision about whether to proceed with session creation, initiate an authorization flow, or configure providers (e.g., through the providers API) 4. Provide clear, proactive UX — e.g., showing a "Sign in" prompt before any session is created 5. Completely skip authentication process if the agent is already authenticated 6. Show which credentials and accounts the agent is using, including agents that hold credentials for several providers, and keep that display current when the user signs in or out outside the client ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? ### Intended flow The client calls `initialize`, inspects capabilities to confirm `auth/status` support, then queries auth state before deciding how to proceed. ```mermaid theme={null} sequenceDiagram participant Client participant Agent Client->>Agent: initialize Note right of Agent: Agent reports capabilities,
including auth/status support Agent-->>Client: initialize response
(agentCapabilities.auth.status) Client->>Agent: auth/status Agent-->>Client: auth/status response
(state, accounts) alt state: authenticated or not_required Client->>Agent: session/new else state: unauthenticated Note over Client: Client initiates
authorization flow
(e.g., call authenticate,
configure providers) Client->>Agent: authenticate Client->>Agent: session/new end Note over Agent: User signs in or out
outside the client Agent-)Client: auth/status_update
(state, accounts) ``` 1. **Initialization**: The client calls `initialize`. The agent responds with capabilities, including `auth/status` support via `agentCapabilities.auth`. 2. **Auth state query**: The client calls `auth/status`. The agent inspects its local configuration, stored credentials, or environment to determine the current auth state. 3. **Client-side decision**: Based on the response, the client either proceeds to session creation or initiates an authorization flow first. 4. **Change notifications**: When the agent notices its authentication state changed, for example after `authenticate`, `logout`, or a sign-in in another terminal, it sends `auth/status_update` with the new state. ### Capability advertisement The agent advertises support for the `auth/status` method via the existing `auth` capability in `agentCapabilities`: ```typescript theme={null} interface AgentAuthCapabilities { // ... existing fields (e.g., logout) ... /** * Auth status query support. * Omitted or `null` means the agent does not advertise support. * Supplying `{}` means the agent supports the auth/status method * and may send auth/status_update notifications. */ status?: AuthStatusCapabilities | null; } interface AuthStatusCapabilities { /** Extension metadata */ _meta?: Record; } ``` **Initialize Response example:** ```json theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentInfo": { "name": "MyAgent", "version": "2.0.0" }, "agentCapabilities": { "auth": { "status": {} }, "sessionCapabilities": {} } } } ``` ### `auth/status` method A method that can be called after initialization to query the agent's current authentication status. ```typescript theme={null} interface AuthStatusRequest { /** Extension metadata */ _meta?: Record; } interface AuthStatusResponse { /** * Whether the agent can start sessions without the user signing in first. * Clients use this field to decide whether sign-in is needed. Clients MUST * treat values they do not recognize as "unknown". */ state: AuthState; /** * The accounts the agent has configured, for display. * Omitted and empty are equivalent. */ accounts?: AuthAccount[]; /** Extension metadata */ _meta?: Record; } /** * - "authenticated": credentials are configured (validity is not guaranteed) * - "unauthenticated": the user needs to sign in; includes missing, expired, * or known-invalid credentials * - "not_required": no authentication is needed, e.g. a local model * - "unknown": the agent cannot currently determine the state * Values beginning with `_` are reserved for implementation-specific * extensions. Other unknown values are reserved for future ACP variants. */ type AuthState = "authenticated" | "unauthenticated" | "not_required" | "unknown" | string; /** * An account or credential the agent has configured, such as a signed-in * user account or an API key. Display information only. */ interface AuthAccount { /** e.g. "Claude Max", "OpenAI API key", "Vertex AI" */ label: string; /** * Short text shown with the label, such as the credential source, * e.g. "API key helper". Never contains credentials. */ description?: string | null; /** * Whether the agent currently uses this account by default. * Several accounts may be active, for example one per provider. */ active?: boolean | null; /** Display name of the user, such as a username or full name */ name?: string | null; email?: string | null; /** Organization, team, or workspace the account is using */ organization?: string | null; _meta?: Record; } ``` Optional fields treat omitted and `null` the same way: the value is not reported. `state` is required and strict, because clients act on it. Everything in `accounts` is display information, so a receiver ignores a malformed value, or skips a malformed entry, instead of rejecting the message. ### `auth/status_update` notification A notification the agent sends when its authentication status changes. It carries the same fields as `AuthStatusResponse`, as a full snapshot rather than a diff. ```typescript theme={null} interface AuthStatusUpdateNotification { state: AuthState; accounts?: AuthAccount[]; _meta?: Record; } ``` #### Example Exchange **auth/status Request:** ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "auth/status", "params": {} } ``` **auth/status Response (single signed-in account):** ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "state": "authenticated", "accounts": [ { "label": "Claude Max", "active": true, "email": "user@example.com", "organization": "Example Inc." } ] } } ``` **auth/status Response (several providers):** ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "state": "authenticated", "accounts": [ { "label": "Anthropic API key", "description": "API key helper", "active": true }, { "label": "Vertex AI" }, { "label": "GitHub Copilot", "name": "octocat" } ] } } ``` **auth/status Response (unauthenticated):** ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "state": "unauthenticated" } } ``` **auth/status\_update Notification (switched to a gateway):** ```json theme={null} { "jsonrpc": "2.0", "method": "auth/status_update", "params": { "state": "authenticated", "accounts": [ { "label": "Custom model gateway", "active": true } ] } } ``` #### Behavior 1. **Capability advertisement**: The agent SHOULD include `auth.status` in `agentCapabilities` if it supports the `auth/status` method. Clients MUST check for this capability before calling the method. 2. **Timing**: The `auth/status` method MUST be callable after `initialize`. It MAY be called multiple times (e.g., after `authenticate`, to re-check state). 3. **Local checks preferred**: The agent MAY determine auth state from locally available information (config files, environment variables, stored tokens) or by making external API calls. Agents SHOULD keep `auth/status` fast; if a check would block, they SHOULD answer `unknown` and send `auth/status_update` once the check completes. `authenticated` means credentials are present, NOT that they are guaranteed to be valid. 4. **No side effects**: Calling `auth/status` MUST NOT modify any agent state. It is a pure query. Agents MUST NOT reject `auth/status` with `auth_required` (`-32000`), since it is how a Client learns that authentication is required. 5. **Overall state**: The top-level `state` describes whether the agent can start a session with its default configuration without the user signing in. Agents with several accounts report `authenticated` if the accounts in effect are usable, even if others are not. 6. **Unknown state**: Agents SHOULD return `unknown` rather than guessing when they cannot determine their state. Clients MUST treat unrecognized `state` values as `unknown`, and MAY proceed to `session/new` and handle an `auth_required` error as they do today. 7. **Accounts list**: `accounts` is for display only. Clients MUST NOT use it to decide whether to authenticate. Agents SHOULD list the accounts and credentials they have configured, including API keys, and SHOULD mark the ones in effect with `active: true`. Several accounts MAY be active, for example one per provider. Accounts that are missing or need sign-in are not listed; the top-level `state` reports whether the user needs to sign in. Agents MUST NOT include secrets. Clients MUST NOT use `accounts` entries or their fields, such as `email`, as stable account identifiers, because they can change or be missing. Clients SHOULD NOT log these fields or send them anywhere else, such as telemetry; they are sent only for display. 8. **Agent-owned credentials only**: `accounts` lists credentials the agent itself holds, not provider configuration the client supplied. How client-supplied providers affect the top-level `state` is left open; see the FAQ. 9. **Change notifications**: Agents that advertise `auth.status` MAY send `auth/status_update` at any time after `initialize`, and SHOULD send it when their status changes, including after `authenticate` or `logout`. Agents SHOULD only send it when the reported status differs from the last one sent on the connection. The notification is connection-scoped, never per session. 10. **Re-checking cached outcomes**: A Client MAY treat a change between two snapshots as a reason to re-check an outcome it cached for the earlier snapshot, such as an `auth_required` error. A change does not identify an account or prove that the credentials are valid. An unchanged snapshot does not prove that the credentials are unchanged. ## Frequently asked questions > What questions have arisen over the course of authoring this document? ### Why not rely on `session/new` errors? The `session/new` method is designed for session creation, not for auth validation. Per the specification, agents are not required to validate credentials during session creation — some agents defer validation to the first actual LLM call. This means a successful `session/new` does not guarantee the agent is authenticated, and a failed `session/new` may fail for reasons unrelated to authentication. A dedicated method provides a clear, unambiguous signal. ### Why not include auth state in the `initialize` response directly? The `initialize` response contains capabilities — what the agent *supports*. Auth state is runtime information — what the agent *currently has configured*. Mixing these concerns would make `initialize` less predictable. Additionally, auth state may change after initialization (e.g., after signing in or configuring providers), and a separate method allows re-querying. ### Why not just check for the presence of environment variables on the client side? Agents may obtain credentials from many sources: config files, keychains, OAuth tokens, environment variables, or even embedded keys. The client has no visibility into these mechanisms. Only the agent knows whether it has usable credentials configured. ### Why report accounts, after removing auth details earlier? An earlier version tried to report state per auth method, or which auth method was used. That mapping is ambiguous: one auth flow can produce several credential types (for example, a browser login that results in an API key). `accounts` describes what the agent has configured, without referring to `authMethods`, and is display information only. Clients decide whether sign-in is needed from `state`. Accounts have no state of their own: nothing links an account to an auth method, so a client could not act on a per-account state, and an empty list could not distinguish `not_required`, `unauthenticated`, and `unknown`. The shape is based on a survey of how agents and adjacent tools report auth status: * About half of the agents in the ACP registry hold credentials for several providers at once (for example opencode, goose, cline, Kimi, and pi), and some allow several accounts per provider with one active. A list with an `active` marker covers these as well as single-account agents. CLIs that started with a single account, such as `gh auth status`, later had to add a list. * Credential kinds, account plans, and credential sources also appear in most agents, but each defines them differently. `label` and the optional `description` carry this as display text, without standardizing those taxonomies. For example, the [Claude adapter](https://github.com/agentclientprotocol/claude-agent-acp/blob/3b22586cf63cef06f1029a8418a9abb3b2cc3236/src/auth-status.ts) reports an API key helper separately from the account label. `name` still means the user's name, not a credential source. * Each entry is called an account even when it is an API key, following VS Code's authentication API, `gcloud auth list`, `az account list`, and `gh auth status`, which all list non-person credentials such as service accounts and tokens as accounts. * Existing extensions already report similar data: Junie and the Claude and Codex adapters push an `_auth/status_update` notification, and mistral-vibe answers an `auth/status` extension request. * Fields that are vendor-specific, require network calls, or that no agent reliably exposes to clients are left out: quota and credits, expiry timestamps, and scopes. They can be carried in `_meta`. ### Why add a notification instead of only a query? Authentication can change without the client doing anything: the user can sign in or out in another terminal, or a token can expire. Without a notification, clients have to poll `auth/status` or show an out-of-date state. The notification reuses the response shape as a full snapshot, so clients can query once after `initialize` and then replace their state with each update. ### Why the name `description`? Other ACP types pair a short name with an optional `description`, such as auth methods, session config options, and available commands. The account field follows them. `detail` is what the Claude and Codex adapters use in their `_meta` extensions, but no ACP type uses it. `subtitle` and `hint` describe a presentation. `source` is too narrow: the Codex adapter uses the field for a gateway's provider name. ### Why not add a credentials revision? A Client that caches an outcome, such as an `auth_required` error, wants to know when the credentials change. An opaque revision would report changes that leave every displayed field identical, but each Agent would have to track that history, including across restarts. Comparing snapshots covers the common cases, such as signing in with another account or switching from a subscription to an API key. A revision can be added later as an optional field. ### Why not use a boolean for the state? A boolean can't express two cases agents report today. Agents that run local models need no authentication at all, so clients should hide sign-in rather than show "signed in". And an agent cannot always tell its state: a probe can time out or fail. `not_required` and `unknown` cover these. Expired or invalid credentials are reported as `unauthenticated`, since the client's response is the same: ask the user to sign in. ### How does this relate to the providers API? The two are complementary. `auth/status` reports credentials the agent owns, while the providers API lets the client supply its own routing and credentials. A client could show the agent's signed-in account and also offer to route through the user's own key or gateway. How they interact is left open while the providers API is being reworked. In particular, this proposal does not yet say whether client-supplied providers count toward the top-level `state`, or whether accounts should reference provider identifiers. Both can be specified once the providers API settles, without breaking this shape. ### Can auth state differ per session or working directory? Not in this proposal. Authentication in ACP is connection-wide: `authenticate` and `logout` take no session or working directory. Credentials that depend on the project, such as a project-level configuration, are resolved when the session is created and surface through `session/new`. For agents where the credential in use depends on the session's model or provider, `accounts` lists all of them and `active` marks the ones the agent uses by default, which may be one per provider. A per-session view, for example a `session/update` variant, could be added later if clients need it. An optional `cwd` parameter could be added to `auth/status` later without breaking existing implementations. ## Revision history * 2026-11-10: Add an optional account `description`, and let Clients re-check cached outcomes when the snapshot changes * 2026-10-29: Replace `authenticated` and `message` with `state` and a minimal `accounts` list (`label`, `active`, `name`, `email`, `organization`), based on a survey of agent auth models; add the `auth/status_update` notification * 2026-10-29: Advertise `auth.status` as a capability object (`{}`) instead of a boolean, matching other method capabilities * 2026-07-21: Accepted as a Draft RFD * 2026-03-15: Remove `authMethods` from the proposal and keep aggregate auth state only (`authenticated` + optional `message`) * 2026-03-10: Rename `getAuthState` to `auth/status`, nest capability under `agentCapabilities.auth` * 2026-03-07: Address review feedback on auth state structure * 2026-03-05: Initial draft — preliminary proposal to start discussion # Introduce RFD Process Source: https://agentclientprotocol.com/rfds/introduce-rfd-process Author(s): [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? Bullet points welcome. Introduce a "Request for Dialog" (RFD) process to replace ad-hoc design discussions with structured, community-friendly design documents that track features from conception to completion. ## Status quo > How do things work today and what problems does this cause? Why would we change things? Currently all development is being done primarily by the Zed team tracking requests and proposals from multiple teams. The goal is to create a process that helps to keep files organized and which can scale to participation by an emerging community. ## Shiny future > How will things will play out once this feature exists? ### Project licensing All code and RFDs are licensed under an Apache 2.0 license. The project is intended to remain open source and freely available in perpetuity. ### Decision making For the initial phase, the project shall have a "design team" that consists of the Zed team acting in "BDFL" capacity. The expectation is that the project will setup a more structure governance structure as it grows. The design team makes all decisions regarding RFDs and sets overall project direction. ### RFD lifecycle #### RFDs are proposed by opening a PR An RFD begins as a PR adding a new file into the "Draft" section. The RFD can start minimal - just an elevator pitch and status quo are enough to begin dialog. Pull requests become the discussion forum where ideas get refined through collaborative iteration. As discussion proceeds, the FAQ of the RFD should be extended. If discussion has been going long enough, the PR should be closed, feedback summarized, and then re-opened with a link to the original PR. #### The PR is merged into "draft" once a core team member decides to champion it RFD proposals are merged into the "draft" section if a core team member decides to champion them. The champion is then the point-of-contact for that proposal going forward and they will work with the proposal authors and others to make it reality. Core team members do not need to seek consensus to merge a proposal into the draft, but they should listen carefully to concerns from other core team members, as it will be difficult to move the RFD forward if those concerns are not ultimately addressed. Once a proposal is moved to draft, code and implementation may begin to land into the PR. This work needs to be properly feature gated and marked with the name of the RFD. Further discussion on the RFD can take place on [Zulip](https://agentclientprotocol.zulipchat.com/) if needed. #### Moving to the "active" section When core maintainers or a working group are actively spending bandwidth on an RFD, the champion can open a PR to move the file to the active section. Active RFDs are the proposals the project is currently trying to move forward. This is a visibility signal, not a stability commitment or final approval. Active RFDs should have a current owner, a plausible implementation or design plan, and should be updated as the work changes. If work pauses or the owner no longer has bandwidth, the RFD can move back to draft. #### Moving to the "preview" section Once the champion feels the RFD is ready for others to check it out, they can open a PR to move the file to the preview section. This is a signal to the community (and particularly other core team members) to check out the proposal and see what they think. The PR should stay open for "a few days" to give people an opportunity to leave feedback. The champion is empowered to decide whether to land the PR. As ever, all new feedback should be recorded in the FAQ section. #### Deciding to complete an RFD When they feel the RFD is ready to be completed, the champion requests review by the team. The team can raise concerns and notes during discussion. Final decision on an RFD is made by the core team lead. #### Implementation of an RFD Active RFDs are living documents that track implementation progress. Status badges in design documentation link back to the relevant RFD, creating a clear connection between "why we're building this" and "how it works." When building code with an agent, agents should read RFDs during implementation to understand design rationale and update them with implementation progress. ### Moderating and managing RFD discussions Moving RFDs between points in the cycle involve opening PRs. Those PRs will be places to hold dialog and discussion -- but not the only place, we expect more detailed discussions to take place on [Zulip](https://agentclientprotocol.zulipchat.com/) or other communication channels. RFD owners and champions should actively "curate" discussions by collecting questions that come up and ensuring they are covered in the FAQ. Duplicate questions can be directed to the FAQ. If the discussion on the PR gets to the point where Github begins to hide comments, the PR should typically be closed, feedback collected, and then re-opened. ## Implementation plan > What is your implementation plan? * ✅ Create RFD infrastructure (about, TEMPLATE, navigation setup) * ✅ Establish lifecycle: Draft → Active → Preview → Completed * ⏳ Write RFDs for major in-progress features ## Frequently asked questions ### Why "Request for Dialog" and not "Request for Comment"? Well, partly because "dialog" emphasizes conversation and exploration rather than just collecting feedback on a predetermined design. We also shamelessly stole this process from [Niko Matsakis and the Symposium project](https://symposium-dev.github.io/symposium/rfds/index.html) (with permission) so that we could benefit from their experience. ## Revision history * 2026-07-02: Added Active between Draft and Preview to show which RFDs have current maintainer or working-group bandwidth. * 2025-10-28: Initial version, created alongside RFD infrastructure # Logout Method Source: https://agentclientprotocol.com/rfds/logout-method * Author(s): [@anna239](https://github.com/anna239) ## Elevator pitch > What are you proposing to change? Add a `logout` method that allows clients to terminate an authenticated session with an agent. This is the counterpart to the existing `authenticate` method and enables proper session cleanup and credential invalidation. ## Status quo > How do things work today and what problems does this cause? Why would we change things? Currently, ACP provides an `authenticate` method for establishing authenticated sessions, but there is no standardized way to: * Log out of an authenticated session * Invalidate credentials or tokens * Signal to the agent that the user wants to end their authenticated state Users who want to switch accounts, revoke access, or simply log out must rely on: * Manually clearing credentials outside of ACP * Agent-specific workarounds This creates inconsistent user experiences and potential security concerns when credentials should be invalidated but aren't. ## Shiny future > How will things play out once this feature exists? Clients will be able to offer a proper "Log out" button that: 1. Cleanly terminates the authenticated session 2. Allows the agent to invalidate tokens/credentials as needed 3. Returns the connection to an unauthenticated state 4. Enables the user to re-authenticate with different credentials ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? ### New Method: `logout` A new method that terminates the current authenticated session. #### LogoutRequest ```typescript theme={null} interface LogoutRequest { /** Extension metadata */ _meta?: Record; } ``` #### LogoutResponse ```typescript theme={null} interface LogoutResponse { /** Extension metadata */ _meta?: Record; } ``` ### Capability Advertisement The `logout` capability is advertised within the `auth` object in `AgentCapabilities`: ```typescript theme={null} interface AgentCapabilities { // ... existing fields ... /** Authentication-related capabilities */ auth?: AgentAuthCapabilities; } interface AgentAuthCapabilities { /** Extension metadata */ _meta?: Record; /** Agent supports the logout method. Supply `{}` to indicate support. */ logout?: LogoutCapabilities; } interface LogoutCapabilities { /** Extension metadata */ _meta?: Record; } ``` ### JSON Schema Additions ```json theme={null} { "$defs": { "AgentAuthCapabilities": { "description": "Authentication-related capabilities supported by the agent.", "properties": { "_meta": { "additionalProperties": true, "type": ["object", "null"] }, "logout": { "allOf": [ { "$ref": "#/$defs/LogoutCapabilities" } ], "description": "Whether the agent supports the logout method. Supply `{}` to indicate support." } }, "type": "object" }, "LogoutCapabilities": { "description": "Logout capabilities supported by the agent. Supply `{}` to indicate support.", "properties": { "_meta": { "additionalProperties": true, "type": ["object", "null"] } }, "type": "object" }, "LogoutRequest": { "description": "Request to terminate the current authenticated session.", "properties": { "_meta": { "additionalProperties": true, "type": ["object", "null"] } }, "type": "object", "x-method": "logout", "x-side": "agent" }, "LogoutResponse": { "description": "Response to the logout method.", "properties": { "_meta": { "additionalProperties": true, "type": ["object", "null"] } }, "type": "object", "x-method": "logout", "x-side": "agent" } } } ``` ### Example Exchange **Request:** ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "logout", "params": {} } ``` **Response:** ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": {} } ``` ### Behavior 1. **Pre-condition**: The client should only call `logout` if: * The agent advertises `agentCapabilities.auth.logout: {}` 2. **Agent responsibilities**: * Invalidate any stored tokens or credentials as appropriate * Clean up any session state associated with the authenticated user * Return the connection to an unauthenticated state 3. **Post-condition**: After a successful `logout`: * Subsequent requests that require authentication should return `auth_required` error * The client can call `authenticate` again to establish a new authenticated session 4. **Active sessions**: If there are active sessions when `logout` is called, the agent should either: * Terminate them gracefully * Throw an `auth_required` error ## Frequently asked questions > What questions have arisen over the course of authoring this document? ### Should logout affect active sessions? This is left as implementation-defined. Some agents may want to: * Automatically terminate all sessions (strict security) * Keep sessions running The RFD intentionally does not mandate a specific behavior to allow flexibility. ## Revision history * 2026-05-21: RFD marked as Completed; `logout` is stabilized * 2026-05-17: Moved to Preview. * 2026-02-02: Initial draft # MCP-over-ACP: Stateless MCP Requests over ACP Source: https://agentclientprotocol.com/rfds/mcp-over-acp Author(s): [nikomatsakis](https://github.com/nikomatsakis) ## Elevator pitch Let an ACP client or proxy supply tools to an agent using the ACP connection it already has. Declare an MCP server with `"type": "acp"`, then send independent MCP requests to its `serverId`. Results, request-scoped notifications, and cancellation travel over ACP without a second process or network endpoint. This draft targets **MCP 2026-07-28 only**. It does not emulate older MCP revisions. ACP initialization and sessions remain unchanged, but there is no MCP initialization handshake, MCP connection object, or connect/disconnect exchange. ## Motivation ACP manages an agent's conversation while MCP provides tools behind it. A client often needs to do both: provide project-aware tools, ask the agent to use them, and execute them inside the client's process or sandbox. Requiring a separate HTTP listener or subprocess for those tools creates an extra communication path and makes isolation harder. Native MCP-over-ACP keeps the interaction on the authorized ACP channel. It works directly between a client and an agent; proxy chains are useful but not required. ## Protocol model There are three identities, with different purposes: * **`serverId`** names a server declared by its provider. It selects a tool/resource/prompt offering, not an MCP session. * **`requestId`** is a caller-generated opaque string identifying one logical MCP request. It is used as the inner MCP JSON-RPC ID and is preserved across ACP proxies. * **Outer JSON-RPC `id`** identifies the ACP request on one hop. A proxy may renumber it when forwarding. Every operation carries its own MCP version, client capabilities, and other request context. Nothing about a previous request establishes that context for the next one. A subscription may keep one request alive; that is not a session for unrelated calls. Stateless MCP does not require stateless application services. Providers may reuse tool implementations, database pools, caches, and authorization services. Execution and notification permissions belong to each operation, while application state may outlive it. Discovery, listing, and execution must use that operation's explicit caller context, not the identity or capabilities of an earlier request. The binding uses one method name, `mcp/message`, in two directions: * An **agent-to-provider request** invokes one MCP operation and eventually receives one result or error. * A **provider-to-agent notification** carries an MCP notification belonging to that active operation. `mcp/message` is this binding's ACP transport envelope, not an MCP-defined method. JSON-RPC distinguishes the two forms by the outer `id`: requests have one, notifications do not. The inner MCP method is preserved, such as `tools/call` for a request or `notifications/progress` for a notification. Implementations dispatch by JSON-RPC message kind and direction, not the outer method name alone. There are no provider-originated MCP requests. Interactive tools use MCP's multi round-trip request pattern (MRTR). ## Declaring a server The client checks the agent's ACP MCP capability, then includes a declaration in a session setup request. For example, `session/new` parameters can include: ```json theme={null} { "cwd": "/workspace/project", "mcpServers": [ { "type": "acp", "name": "project-tools", "serverId": "project-tools:7a72" } ] } ``` The provider generates the opaque `serverId`. A server ID identifies one registration for the lifetime of the ACP connection and must not be rebound to a different registration, including after removal. The same registration may be offered to multiple ACP sessions; distinct offerings use distinct server IDs rather than hidden per-MCP-connection catalogs. The provider must be ready to serve requests when it publishes the declaration. An agent may invoke tools or discover the server before returning the ACP session ID. Only the owning provider claims requests for its registered IDs. Intermediaries without a matching registration forward the request. If no provider can resolve the ID, the final recipient returns the binding's server-unavailable error. A declaration is a reference to a registration, not a remote allocation request. This RFD adds no server-update or unadvertisement method. The provider owns the registration's local lifetime: releasing it rejects future requests and cancels outstanding work. Closing the ACP connection releases all its registrations. Merely omitting a previously declared server from a later setup request does not revoke a registration used by another session. ### Capability advertising In **ACP v1**, the relevant `InitializeResponse` fragment is: ```json theme={null} { "agentCapabilities": { "mcpCapabilities": { "acp": true } } } ``` Omission is equivalent to `false`. In **draft ACP v2**, the fragment is: ```json theme={null} { "capabilities": { "session": { "mcp": { "acp": {} } } } } ``` The v2 field is an optional object: omission or `null` means support is not advertised, and `{}` advertises support. These are ACP capabilities, separate from the MCP client capabilities carried on each request. An intermediary only advertises support when its downstream chain can consume this transport. The conductor does not unconditionally add the capability. A proxy that provides no adaptation preserves its successor's capabilities. This capability advertises the MCP transport, not every optional MCP feature or a guarantee that every operation can be cancelled. MCP discovery and per-request capabilities describe the supported features. ## Requests and results The agent sends an ACP request with a server ID, a fresh logical MCP request ID, and flattened MCP method/parameters: ```json theme={null} { "jsonrpc": "2.0", "id": 20, "method": "mcp/message", "params": { "serverId": "project-tools:7a72", "requestId": "mcp-request:a11f", "method": "tools/call", "params": { "name": "echo", "arguments": { "message": "hello" }, "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {}, "io.modelcontextprotocol/clientInfo": { "name": "example-agent", "version": "1" }, "progressToken": "progress-1" } } } } ``` The provider executes the inner request using `"mcp-request:a11f"` as its MCP JSON-RPC ID. It does not use the outer ACP ID `20`, which may differ on another hop. The successful ACP response carries exactly one inner MCP outcome. A result is nested under `result`: ```json theme={null} { "jsonrpc": "2.0", "id": 20, "result": { "result": { "resultType": "complete", "content": [ { "type": "text", "text": "hello" } ], "isError": false } } } ``` An inner MCP protocol error is also a successful **outer ACP response**, using the carrier's `error` branch: ```json theme={null} { "jsonrpc": "2.0", "id": 20, "result": { "error": { "code": -32602, "message": "Unknown tool", "data": { "name": "echo" } } } } ``` This preserves error-domain provenance. An inner error code is an MCP code; it must not be interpreted as an ACP error, even if the numerical codes collide. For example, an inner `-32000` must not trigger ACP authentication. An MCP tool-execution error remains a result with `isError`, not either kind of protocol error. Senders MUST include exactly one of `result` or `error` in the carrier. `result` must be present on the result branch and accepts any JSON value, including explicit `null`. `error` is a non-null object with required integer `code` and string `message`; optional `data` distinguishes omission from explicit `null`. Receivers ignore unknown outer carrier fields and prefer `result` if both outcome keys are present, matching the existing JSON-RPC response handling. Unknown inner result and error fields remain opaque and are preserved. An optional carrier `_meta` contains ACP metadata and is separate from the inner outcome's metadata; omission, `null`, and invalid non-object values are all treated as absent. ### Binding failures Outer ACP errors are reserved for failures to admit, route, or execute the binding itself: | Code | Meaning | | - | - | | `-32602` | Malformed ACP envelope or duplicate active `(serverId, requestId)` | | `-32800` | ACP operation cancelled | | `-33000` | Binding resource limit exceeded | | `-33001` | Server registration unavailable | | `-33002` | Backend or transport failed without a valid MCP outcome | These binding-specific codes do not allocate new meanings in MCP's reserved `-32000` through `-32019` range. No implementation may report overload as ACP's authentication-required error. A malformed inner MCP request or an MCP error returned by a backend belongs in the outcome carrier instead. `server/discover` is an ordinary inner MCP request. It is supported but is not a prerequisite for calling a tool. The transport does not silently perform an MCP handshake or substitute ACP capability discovery for MCP server discovery. Discovery's `supportedVersions` describes the revisions available through this binding. The SDK restricts it to 2026-07-28, even when the hosted backend supports additional revisions on other transports; it does not invent support that the backend lacks. Other discovery capabilities and metadata are preserved. ### Fields and metadata `serverId`, `requestId`, and `method` are required non-null strings on both requests and notifications. A caller uses a fresh `requestId` for each operation, including an MRTR retry, and must not reuse an active ID for the same server on the same ACP connection. The inner `params` field accepts an object or `null` and is optional at the envelope level. Omission and `null` both mean no inner parameters; positional arrays are invalid. This does not relax MCP's requirements: a valid 2026-07-28 request must include its required metadata in `params._meta`. An optional outer `_meta` object alongside `serverId` is ACP envelope metadata. Omission and `null` are equivalent. It is distinct from MCP metadata inside the inner parameters or result, which must be preserved. Providers validate the per-request MCP version and capabilities. Missing or malformed required inner metadata is an MCP invalid-parameters outcome. An unsupported version is MCP's `UnsupportedProtocolVersion` error (`-32022`), with the supported and requested versions, inside the outcome carrier. This binding's supported set contains only 2026-07-28: a caller without a mutual version surfaces that error rather than falling back to `initialize` or an earlier revision. ## Request-scoped notifications While a request is active, its provider can send a notification with the same server and logical request IDs: ```json theme={null} { "jsonrpc": "2.0", "method": "mcp/message", "params": { "serverId": "project-tools:7a72", "requestId": "mcp-request:a11f", "method": "notifications/progress", "params": { "progressToken": "progress-1", "progress": 1, "total": 2 } } } ``` The outer notification has no JSON-RPC ID and receives no response. It belongs only to the identified request; a consumer must not deliver unknown or late notifications to a different operation. Progress tokens and other MCP metadata are preserved. Progress and any supported logging notifications belong to their original request, not an unrelated subscription. A provider stops forwarding notifications for a request once its final result or error has been sent. ### Subscriptions `subscriptions/listen` is a long-lived `mcp/message` request, not a new ACP connection. Its first associated MCP notification is `notifications/subscriptions/acknowledged`. Subsequent notifications obey the acknowledged filter. Each subscription notification carries `io.modelcontextprotocol/subscriptionId` in its inner `_meta`. That value is the logical `requestId` of the listen request, not the outer ACP JSON-RPC ID. A graceful completion result carries the same subscription metadata. Multiple subscriptions and ordinary requests may be active concurrently. ## Cancellation and lifetime Cancellation uses ACP's existing `$/cancel_request` for the **outer ACP request**; this binding adds no separate cancellation method or support requirement. A caller can request cancellation when it no longer needs an operation's result. For the example request above: ```json theme={null} { "jsonrpc": "2.0", "method": "$/cancel_request", "params": { "requestId": 20 } } ``` This cancellation ID is hop-local. When a proxy forwards cancellation, it uses its downstream ACP request ID; it does not rewrite the logical MCP `requestId` or tunnel an unrelated hop's cancellation ID. Cancellation is best effort. A provider may complete an operation normally if it cannot cancel it or completion wins the race. When it honors cancellation, it stops producing new notifications for that operation and answers the original ACP request with a cancellation error after cleanup. Cancelling one operation does not cancel sibling requests, subscriptions, the server registration, or the containing ACP connection. For long-lived operations such as `subscriptions/listen`, per-request cancellation is useful because it avoids closing the whole ACP connection to stop one stream. An HTTP adapter translates response-stream closure into a cancellation request upstream, following [MCP's transport-specific cancellation rules](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/cancellation). Honoring cancellation is not merely deletion of a routing entry. Execution and cleanup remain supervised; admission permits and the active logical ID stay owned until cleanup finishes. A reusable service remains available for sibling operations. Work reported as cancelled before execution does not start later. Cancellation cannot roll back already-performed external side effects. Releasing a provider registration or closing its ACP connection cancels all work owned by it. Transport EOF initiates cancellation; it must not wait indefinitely for an application future that is itself awaiting the disconnected peer. Unknown servers and invalid or duplicate active request IDs receive errors; malformed notifications do not receive synthetic replies. Bound notification buffering, frame sizes, and outstanding work. Retain resource accounting while messages are queued, deferred, serialized, or held in an unread response body, not only while backend execution is active. Keep shutdown and any supported cancellation responsive when data capacity is exhausted. If an implementation cannot continue a stream safely, fail or cancel that request explicitly instead of silently dropping subscription events or growing an unbounded queue. Do not block unrelated dispatch while waiting for a slow consumer. ## Interactive tools MCP 2026-07-28 replaces reverse JSON-RPC calls with MRTR. For `tools/call`, `resources/read`, or `prompts/get`, a provider may return `resultType: "input_required"` with input requests and/or opaque `requestState`. That completes the current ACP request. The agent obtains the requested input, then issues a fresh `mcp/message` request for the original operation with `inputResponses` and the exact opaque state. Each retry supplies its own MCP metadata and uses a fresh logical request ID. The transport must not parse retry state, automatically approve an elicitation, or replay side-effecting calls without the agent's policy. This flow needs neither a persistent MCP session nor a provider-originated ACP request. ## Proxying and HTTP adaptation Proxies preserve `serverId`, logical `requestId`, inner payloads, and metadata. Normal ACP forwarding handles outer responses and, where supported, hop-local cancellation. Providers claim requests for their declared servers; other components forward them normally. There is no conductor MCP connection table or special connect/disconnect routing. An optional adapter may expose a native server to a **modern MCP HTTP client**. HTTP capability alone does not prove that an agent supports this MCP revision. The adapter must not add a legacy fallback. The HTTP endpoint can be reused, but every POST represents its own request: * Accept a single JSON-RPC request per POST and return JSON or request-scoped SSE. Reject batches and client-sent responses. * Support subscriptions as long-lived POST response streams. Closing one response stream requests cancellation of only its mapped ACP request and stops delivery on that stream. * Return 405 for GET and DELETE. Do not issue session headers or implement SSE resumption. * Validate protocol-version, method, name, and applicable mirrored tool-parameter headers against the body, including required value decoding. * Validate supplied Origin headers, bind local listeners to loopback, and enforce access control. A random port is not authentication. * Allocate independent logical MCP IDs for overlapping HTTP request IDs. Translate MCP ID references at this transport boundary, including subscription IDs, while preserving progress tokens and opaque state. ACP proxies do not perform that translation. ### Native-tool re-export The Rust adapter exposes a **new local HTTP endpoint for native tools**, not a transparent tunnel for another HTTP endpoint's routing or authorization policy. It uses one loopback listener per ACP connection. A non-secret encoding of `serverId` identifies the route, and a connection-specific bearer credential is bound to that server. Credentials never appear in URLs. The provider still decides whether the registration exists and the caller is authorized; retaining an old URL does not resurrect a removed registration. This endpoint does not advertise tool-parameter header mirroring. It removes `x-mcp-header` only from actual schema annotation positions in returned tool descriptors, preserving validation keywords, argument names, and example/default data. It rejects supplied `Mcp-Param-*` headers rather than assigning them authority. Standard method/name/version header validation still applies. Each `tools/call` goes directly to its native provider without hidden `tools/list` requests. This avoids a descriptor lookup/execution race and does not introduce a discovery prerequisite. Native ACP passthrough preserves descriptors unchanged. A deployment requiring an existing HTTP gateway's parameter-header policy must implement that policy at the new endpoint or decline this re-export; native execution cannot inherit HTTP headers that were never transported. HTTP is an adapter, not a prerequisite for the native protocol. Its validation and security surface must be tested separately; working native tool calls do not establish HTTP conformance. ## Security Server IDs and request IDs are routing identifiers, not credentials. Providers bind server ownership and visibility to the supplying ACP component and authorized callers. Self-reported MCP `clientInfo` is not an authentication identity. Keep outer ACP metadata separate from inner MCP metadata. Do not persist runtime credentials from rewritten HTTP declarations in traces. Servers treat MRTR state as attacker-controlled input. Where it influences authorization or business logic, protect integrity and address principal binding, expiry, replay, and single-use requirements. Intermediaries keep it opaque. Tool lists vary by explicit server identity and authorization scope, not hidden connection state. Preserve required cache metadata and do not share private catalogs across callers. ## Implementation and validation The Rust implementation uses each ACP version's unstable `MessageMcpRequest`, `MessageMcpResponse`, `MessageMcpNotification`, `McpError`, and `McpRequestId` schema types. The v1 and v2 response and error types are defined independently so either version can evolve without changing the other. Their JSON representation is currently the same. The SDK's target API separates a reusable `McpService` from each owned operation. A `McpRequestContext` supplies logical/server identity, validated metadata and capabilities, cancellation, and request-scoped notifications. A backend factory is an explicit adapter for implementations that need per-operation construction, not a requirement imposed by stateless MCP. Integration adapters must supervise any tasks spawned by their underlying library, not assume dropping a wrapper joins detached handlers. Reference implementation tests cover: * Real discovery and tool calls without MCP initialization, directly and through a proxy. * Stable logical IDs when ACP outer IDs are renumbered. * Independent concurrent requests, request-specific metadata/errors, and rejection of duplicate active IDs. * Separation of inner MCP errors from outer ACP errors, including colliding codes, explicit null data, and unknown extension fields. * MRTR with nonempty input responses, opaque state, and fresh retry IDs. * Subscription acknowledgement ordering, filtered notifications, correlation, and graceful completion. * Cancellation of queued and running tools and subscriptions, including noncooperative user futures, registration removal, transport EOF, late-message rejection, and joined resource cleanup. * Slow readers, bounded pending work, control-plane liveness under saturation, and admission recovery after response-body release. * HTTP request isolation, header/Origin/access checks, direct annotated native-tool calls without preliminary requests, request-close cancellation, and rejection of removed transport behavior. These tests verify the binding, not every optional MCP feature. Tasks, Apps, and other extensions remain opt-in. The new design should not depend on deprecated Roots, Sampling, or Logging features. ### Stabilization gates The Rust reference implementation exercises the versioned response carriers, reusable services, bounded transport queues, and native-tool HTTP re-export together. Its cleanup regression deliberately pauses a tool runner while ACP continues dispatching: cancellation cannot settle or release the logical request ID until the runner drops the tool future. Both mutable and concurrent tools use this rule. Independent item-count limits are not evidence of complete memory bounds, and dropping a task handle is not evidence that its work stopped. Concrete buffer sizes and concurrency quotas are implementation policies, not wire-protocol constants. Their behavior must be configurable or documented, and quota failures must preserve the error-domain distinction above. Both ACP v1 and draft v2 must exercise the same binding semantics; this proposal does not otherwise stabilize ACP v2 or optional MCP extensions. The Rust reference implementation supervises cancellation and joins owned backend work before reporting it complete; it cannot forcibly terminate detached application work. These are implementation safeguards, not additional cancellation requirements for advertising the transport. The reference tests establish the covered binding behavior, not full conformance for every MCP feature or readiness to publish packages. The draft schema must be released and dependent SDK major versions coordinated before publication. ## References and revision history Normative MCP references: [2026-07-28 specification](https://modelcontextprotocol.io/specification/2026-07-28), [versioning](https://modelcontextprotocol.io/specification/2026-07-28/basic/lifecycle), [MRTR](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr), [subscriptions](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/subscriptions), [cancellation](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/cancellation), and [Streamable HTTP](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http). This proposal was split from the [proxy-chain RFD](./proxy-chains). Earlier drafts used server `id`/`acpId`, an MCP connection ID, connect/disconnect methods, and reverse requests. Those drafts and the stateful implementation checkpoint are not compatibility commitments. This revision replaces them with server-addressed requests and request-scoped notifications targeting MCP 2026-07-28 only. # Message ID Source: https://agentclientprotocol.com/rfds/message-id * Author(s): [@michelTho](https://github.com/michelTho), [@nemtecl](https://github.com/nemtecl) * Champion: [@benbrandt](https://github.com/benbrandt) ## Elevator pitch Add a `messageId` field to `agent_message_chunk`, `user_message_chunk`, `agent_thought_chunk` session updates to uniquely identify individual messages within a conversation. Only agents generate message IDs, and the IDs are opaque strings. This enables clients to distinguish between different messages beyond changes in update type and lays the groundwork for future capabilities like message editing and session deduplication. ## Status quo Currently, when an Agent sends message chunks via `session/update` notifications, there is no explicit identifier for the message being streamed: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "agent_message_chunk", "content": { "type": "text", "text": "Let me analyze your code..." } } } } ``` This creates several limitations: 1. **Ambiguous message boundaries** - When the Agent sends multiple messages in sequence (e.g., alternating between agent and user messages, or multiple agent messages), Clients can only infer message boundaries by detecting a change in the `sessionUpdate` type. If an Agent sends consecutive messages of the same type, Clients cannot distinguish where one message ends and another begins. 2. **Non-standard workarounds** - Currently, implementations rely on the `_meta` field to work around this limitation. While functional, this approach is not standardized and each implementation may use different conventions. 3. **Limited future capabilities** - Without stable message identifiers, it's difficult to build features like: * Message editing or updates * Message-specific metadata or annotations * Message threading or references * Undo/redo functionality As an example, consider this sequence where a Client cannot reliably determine message boundaries: ```json theme={null} // First agent message chunk { "sessionUpdate": "agent_message_chunk", "content": { "type": "text", "text": "Analyzing..." } } // More chunks... but is this still the same message or a new one? { "sessionUpdate": "agent_message_chunk", "content": { "type": "text", "text": "Found issues." } } // Tool call happens { "sessionUpdate": "tool_call", ... } // Another agent message - definitely a new message { "sessionUpdate": "agent_message_chunk", "content": { "type": "text", "text": "Fixed the issues." } } ``` ## What we propose to do about it Add a `messageId` field to `AgentMessageChunk`, `UserMessageChunk`, and `AgentThoughtChunk` session updates. This field would: 1. **Provide stable message identification** - Each message gets a unique identifier that remains constant across all chunks of that message. 2. **Enable reliable message boundary detection** - Clients can definitively determine when a new message starts by observing a change in `messageId`. 3. **Create an extension point for future features** - Message IDs can be referenced in future protocol enhancements. ### Proposed Structure This RFD does not add a message ID to the `session/prompt` request or response. Clients do not create protocol message IDs. If the Agent emits the accepted user message through `session/update`, it generates and attaches the appropriate message ID to that user message. The follow-up [v2 Prompt Lifecycle RFD](./v2/prompt.mdx#change-the-sessionprompt-response) explores returning that agent-generated `messageId` in the successful prompt response, while leaving the request unchanged. In that proposal, acceptance means insertion: the response acknowledges that the user message has been inserted, without waiting for turn completion. Session updates report the same insertion's content and placement. If the Agent sends `user_message_chunk` updates (e.g., during `session/load`), it uses the user message ID: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "user_message_chunk", "messageId": "msg_user_8f7a1", "content": { "type": "text", "text": "Can you analyze this code?" } } } } ``` For agent message chunks, the Agent also generates and includes a `messageId`: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "agent_message_chunk", "messageId": "msg_agent_c42b9", "content": { "type": "text", "text": "Let me analyze your code..." } } } } ``` The `messageId` field would be: * **Optional in v1** on `agent_message_chunk`, `user_message_chunk`, and `agent_thought_chunk` updates. An omitted `messageId` and an explicit `null` are equivalent and both mean the Agent did not provide a message ID for that chunk. * **Required in v2** on `agent_message_chunk`, `user_message_chunk`, and `agent_thought_chunk` updates. The field MUST be present and MUST be a non-null string. * **Agent-generated** - the Agent is the only participant that creates protocol message IDs * **Unique per message** within a session. In v2, uniqueness is per message type: a user message, an agent message, and an agent thought may share an ID, and Clients key messages by type and ID. * **Stable across chunks** - all chunks belonging to the same message share the same `messageId` * **Opaque** - Implementations treat it as an identifier without parsing its structure In v1, if an Agent supports message IDs and emits an accepted or replayed user message through `session/update`, it SHOULD include `messageId` on that user message update. In v2, every streamed user, agent, and thought message chunk MUST include a `messageId`. ## Shiny future Once this feature exists: 1. **Clear message boundaries** - Clients can reliably render distinct message bubbles in the UI, even when multiple messages of the same type are sent consecutively. 2. **Better streaming UX** - Clients know exactly which message element to append chunks to, enabling smoother visual updates. 3. **Foundation for editing** - With stable message identifiers, future protocol versions could add: * `message/edit` - Agent updates the content of a previously sent message * `message/delete` - Agent removes a message from the conversation * `message/replace` - Agent replaces an entire message with new content 4. **Message metadata** - Future capabilities could reference messages by ID: * Annotations or reactions to specific messages * Citation or cross-reference between messages * Tool calls that reference which message triggered them 5. **Enhanced debugging** - Implementations can trace message flow more easily with explicit IDs in logs and debugging tools. Example future editing capability: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "message_update", "messageId": "ea87d0e7-beb8-484a-a404-94a30b78a5a8", "updateType": "replace", "content": { "type": "text", "text": "Actually, let me correct that analysis..." } } } } ``` ## Implementation details and plan ### Phase 1: Core Protocol Changes 1. **Update schema** (`schema/schema.json`): * Add optional `messageId` field (type: `string`) to v1 `ContentChunk` (used by `AgentMessageChunk`, `UserMessageChunk`, `AgentThoughtChunk`) * Add required `messageId` field (type: `string`) to v2 `ContentChunk` 2. **Update Rust SDK** (`rust/client.rs` and `rust/agent.rs`): * Add a dedicated `MessageId` newtype * Add `message_id: Option` field to the v1 `ContentChunk` struct * Add `message_id: MessageId` field to the v2 `ContentChunk` struct * Update serialization to include `messageId` in JSON output when present for v1 and always for v2 3. **Update TypeScript SDK** (if applicable): * Add `messageId` field to corresponding session update types 4. **Update documentation** (`docs/protocol/prompt-turn.mdx`): * Document the `messageId` field and its semantics * Add examples showing message boundaries * Explain that `messageId` changes indicate new messages ### Phase 2: Reference Implementation 5. **Update example agents**: * Modify example agents to generate and include `messageId` in chunks * Demonstrate consistent IDs across chunks of the same message 6. **Update example clients**: * Update clients to consume `messageId` field * Use IDs to properly group chunks into messages * Demonstrate clear message boundary rendering ### Backward Compatibility The `messageId` field is **optional in v1** to ensure this is a non-breaking change. Agents SHOULD include the `messageId` field on message chunks they can identify, but it is not required for v1 compatibility. Features that rely on `messageId` (such as future message editing capabilities) will implicitly require the field to be present - Agents that don't provide it simply won't support those features. The field is **required in v2**, where breaking protocol changes are allowed. v2 agents MUST include `messageId` on every streamed message chunk, and v2 clients can reject chunks where the field is omitted or `null`. ## Frequently asked questions ### What alternative approaches did you consider, and why did you settle on this one? 1. **Continue using `_meta` field** - This is the current workaround but: * Not standardized across implementations * Doesn't signal semantic importance * Easy to overlook or implement inconsistently 2. **Detect message boundaries heuristically** - Clients could infer boundaries from timing, content types, or session state: * Unreliable and fragile * Doesn't work for all scenarios (e.g., consecutive same-type messages) * Creates inconsistent behavior across implementations 3. **Use explicit "message start/end" markers** - Wrap messages with begin/end notifications: * More complex protocol interaction * Requires additional notifications * More state to track on both sides 4. **Client-generated prompt IDs** - Let Clients generate IDs for `session/prompt` requests: * Creates two sources of truth for protocol IDs * Requires agreement on uniqueness across clients and agents * Conflicts with the Agent's role as owner of the session history This alternative concerned client-generated IDs being used as canonical message IDs. The [v2 Prompt Lifecycle RFD](./v2/prompt.mdx#correlate-prompts-with-accepted-user-messages) instead explores returning the agent-owned `messageId` for correlation. It retains a separate [client-generated correlation token](./v2/prompt.mdx#client-generated-correlation-token) as an alternative for recovering a submission's identity after a lost response, without letting the client choose canonical message IDs. The proposed approach with `messageId` is: * **Simple** - Just one new field with clear semantics * **Flexible** - Enables future capabilities without further protocol changes * **Practical** - IDs come from the same side that owns and emits session history * **Format-agnostic** - Agents can use identifiers that fit their own storage model ### Who generates message IDs? **Only the Agent generates protocol message IDs.** * **For user messages**: The Client sends a prompt without a message ID. If the Agent emits that accepted or replayed user message as a `session/update`, the Agent generates the message ID and includes it in that notification. * **For agent messages and thoughts**: The Agent generates the ID when creating the message or thought and includes it in session update chunks. This matches other protocol identifiers (`sessionId`, `terminalId`, `toolCallId`) which are agent-generated, and provides practical benefits: * **Single source of truth** - The Agent owns session persistence and message ordering * **No format coordination** - The protocol does not need to standardize UUIDs or another shared ID format * **Adapter-friendly** - Adapters for agents that don't support message IDs can simply omit them ### Should this field be required or optional? The field is **optional** for v1 to ensure backward compatibility. Agents SHOULD include `messageId`, but it is not required. In v1, omitting `messageId` and sending `null` are equivalent and both mean no message ID was provided. The field is **required** for v2. The key MUST be present and its value MUST be a non-null string. ### What format should message IDs use? Message IDs are opaque strings generated by the Agent. Clients MUST compare message IDs as opaque strings and MUST NOT parse or infer meaning from their structure. Because IDs only come from the Agent, collision avoidance is the Agent's responsibility within the session. ### What about message IDs across session loads? When a session is loaded via `session/load`, the Agent may: * Preserve original message IDs if replaying the conversation history * Generate new message IDs if only exposing current state The protocol doesn't require message IDs to be stable across session loads, though Agents MAY choose to make them stable if their implementation supports it. The follow-up [v2 Prompt Lifecycle RFD](./v2/prompt.mdx#correlation-and-replay) proposes matching IDs on the prompt response and live user-message updates, without requiring the Agent to persist the message or retain it for any minimum period. If the Agent retains and replays that message within the session, it must use the returned ID so the client can recognize it, including after reconnecting or restarting. Live-only or discarded messages need not appear in later replay. That proposal does not change v1's replay rules. ### Does this apply to other session updates like tool calls or plan updates? This RFD addresses `agent_message_chunk`, `user_message_chunk`, and `agent_thought_chunk` updates. Other session update types (like `tool_call`, `plan`) already have their own identification mechanisms: * Tool calls use `toolCallId` * Plan entries can be tracked by their position in the `entries` array Future RFDs may propose extending `messageId` to other update types if use cases emerge. ## Revision history * **2026-10-29**: Recorded that v2 message IDs are unique per message type, not across all messages in a session. * **2026-06-05**: Moved to Completed and stabilized optional v1 `messageId` in the stable protocol artifacts * **2026-06-03**: Moved the v1 portion of the RFD to Preview while v2-specific behavior remains part of the v2 draft work * **2026-06-03**: Moved the RFD out of the v2 Draft group while keeping v2-specific behavior; added a dedicated `MessageId` type, and made v2 require message IDs on streamed message chunks while v1 keeps optional message IDs for compatibility * **2026-06-02**: Updated the proposal so message IDs are Agent-generated only, removed client-provided prompt IDs and prompt response acknowledgments, and removed the UUID requirement in favor of opaque strings * **2026-02-17**: Added "Message ID Acknowledgment" section to clarify that presence/absence of `userMessageId` in response indicates whether the Agent recorded the ID; clarified that UUID format is MUST (not SHOULD) since both sides generate IDs; renamed response field to `userMessageId` for clarity (request keeps `messageId`) * **2026-01-29**: Updated to allow both clients and agents to generate message IDs using UUID format * **2025-11-09**: Initial draft # Meta Field Propagation Conventions Source: https://agentclientprotocol.com/rfds/meta-propagation * Author(s): [Adrian Cole](https://github.com/codefromthecrypt) * Champion: [@benbrandt](https://github.com/benbrandt) ## Elevator pitch Document `params._meta` as the convention for propagating metadata from clients to agents, such as trace identifiers or correlation IDs. This aligns with [MCP](https://modelcontextprotocol.io/), enabling shared instrumentation since both protocols use stdio JSON-RPC transports. ## Status quo ACP clients already propagate context to agents via `_meta`. For example, `requestId` is used for request correlation in [AionUi](https://github.com/iOfficeAI/AionUi/blob/main/src/common/codex/types/eventData.ts#L12-L16). However, the [extensibility](/protocol/v1/extensibility) documentation does not specify the `_meta` type or document its use for propagation. Without documentation, parties must coordinate ad hoc, which can lead to portability accidents (such as one side using `_meta.traceparent` and the other `_meta.otel.traceparent`). Documenting that propagated fields are root keys in `_meta` prevents this. ## What we propose to do about it Update the [extensibility](/protocol/v1/extensibility#the-_meta-field) documentation with two changes: 1. Add the type `{ [key: string]: unknown }` to the existing summary sentence. This type is compatible with MCP SDKs. 2. Add a new paragraph after the JSON example about propagation conventions. ## Shiny future * Same instrumentation (OpenInference, etc.) works for both ACP and MCP. * Observability tools can correlate traces across protocols. ## Implementation details **Change 1**: Update the existing summary sentence in [extensibility](/protocol/v1/extensibility#the-_meta-field): ```diff theme={null} -All types in the protocol include a `_meta` field that implementations can use to attach custom information. +All types in the protocol include a `_meta` field with type `{ [key: string]: unknown }` that implementations can use to attach custom information. ``` **Change 2**: After the JSON example, before "Implementations **MUST NOT**", add: > Clients may propagate fields to the agent for correlation purposes, such as `requestId`. The following root-level keys in `_meta` **SHOULD** be reserved for [W3C trace context](https://www.w3.org/TR/trace-context/) to guarantee interop with existing MCP implementations and OpenTelemetry tooling: > > * `traceparent` > * `tracestate` > * `baggage` ## FAQ ### Why document this now? Clients already propagate context via `_meta`. Documenting prevents incompatible drift and enables shared tooling with MCP. ### Why reference MCP? ACP and MCP are the two core agentic protocols, both using stdio JSON-RPC. Where `_meta` types are compatible, instrumentation code can be abstracted and reused for both: Here are several MCP SDKs that propagate W3C trace-context in `_meta`: * [MCP C# SDK](https://github.com/modelcontextprotocol/csharp-sdk) - native W3C trace-context propagation * [OpenInference](https://github.com/Arize-ai/openinference) - Python and TypeScript MCP instrumentation (collaboration between Arize and Elastic) * [curioswitch/mcp-go-sdk-otel](https://github.com/curioswitch/mcp-go-sdk-otel) - Go MCP instrumentation ## Revision history * 2026-06-03: Moved to Completed. * 2025-12-04: Implementation in extensibility docs * 2025-11-28: Initial draft # Model Config Option Category Source: https://agentclientprotocol.com/rfds/model-config-category * Author(s): [anna239](https://github.com/anna239) ## Elevator pitch Add a new `model_config` category to session configuration options, so that agents can expose model-related parameters (context size, speed/quality trade-offs, etc) and clients can group them alongside the main model selector in the UI. ## Status quo The `category` field on `SessionConfigOption` currently supports three values: `mode`, `model`, and `thought_level`. This works well when the model is a single selector, but some agents expose many model configurations — context window size, speed tier, and similar settings that logically belong next to the model picker. ## What we propose to do about it Add a `model_config` variant to `SessionConfigOptionCategory`. Agents tag any model-related parameters with `"category": "model_config"`, and clients render them near the primary `model` selector — for example as secondary controls within a model-picker popover or panel. ### Relationship to `thought_level` Once `model_config` exists, `thought_level` is semantically a special case of a model configuration parameter. We keep `thought_level` as-is for backward compatibility — existing clients already handle it — but new model-related options should use `model_config`. ## Shiny future Agents expose rich, parameterized model configurations over ACP. ## Implementation details and plan ### JSON format An agent declares model-config options in `configOptions`: ```json theme={null} { "configOptions": [ { "id": "model", "name": "Model", "category": "model", "type": "select", "currentValue": "sonnet-4.5", "options": [ { "value": "sonnet-4.5", "name": "Sonnet 4.5" }, { "value": "opus-4.6", "name": "Opus 4.6" } ] }, { "id": "context_size", "name": "Context Size", "category": "model_config", "type": "select", "currentValue": "200k", "options": [ { "value": "200k", "name": "200K" }, { "value": "1m", "name": "1M" } ] }, { "id": "fast_mode", "name": "Fast Mode", "category": "model_config", "type": "boolean", "currentValue": false } ] } ``` ### Client behavior * Clients SHOULD render `model_config` options near the `model` selector (e.g., in the same popover or panel). * Clients that do not recognize the category MUST handle it gracefully per the existing spec — the option still renders, just without special placement. * No new client capability negotiation is needed. ### Should `thought_level` move under `model_config`? Not now. Existing clients already handle `thought_level`, so changing its semantics would be a breaking change. New model-related parameters should use `model_config`; `thought_level` remains for backward compatibility. ## Revision history * 2026-06-24: Moved to Completed and stabilized `model_config` in the protocol artifacts * 2026-06-22: Move to preview * 2026-04-08: Initial proposal # Plan Operations Support Source: https://agentclientprotocol.com/rfds/plan-operations Author(s): [anna239](https://github.com/anna239) ## Elevator pitch > What are you proposing to change? Introduce a new `plan_update` session update type that supports multiple plan formats (item-based, file-based, markdown text), multiple concurrent plans via IDs, and plan removal. The existing `plan` session update type remains unchanged for backward compatibility. ## Status quo > How do things work today and what problems does this cause? Why would we change things? * The `plan` session update contains `entries: Vec` — a flat list of items with priority/status * Plans are one-way notifications (agent → client) via `session/update` * No plan identity — each update replaces the previous plan entirely * No way to remove/dismiss a plan once sent * Only one plan representation (structured items) — no support for free-form markdown or file-based plans ## What we propose to do about it > What are you proposing to improve the situation? Add a new `SessionUpdate` variant — `plan_update` — that carries a `plan` field. The `plan` field is a tagged union (discriminated by `type`) with the following variants: | Type | Description | Specific fields | | - | - | - | | `items` | Structured entries (same semantics as today's `plan`) | `entries: PlanEntry[]` | | `file` | Agent provides a file URI containing the plan | `uri: string` | | `markdown` | Agent provides raw markdown text | `content: string` | All variants carry a required `planId: string` that identifies the plan, and an optional `_meta` for extensibility. Additionally, introduce a `plan_removed` session update type that carries only a `planId` to signal dismissal. This keeps `plan_update` focused purely on content updates and makes removal a distinct, self-describing event. The existing `plan` session update type is **not modified** and continues to work as before. Agents that want multi-plan support, new plan formats, or removal capabilities use `plan_update` and `plan_removed` only when the client advertises `plan`; otherwise they fall back to the existing `plan` session update type. ### Client capabilities Add to `ClientCapabilities`: ``` plan?: PlanCapabilities ``` This field is optional. When present as `{}`, it signals the client supports the `plan_update` and `plan_removed` session update types. When omitted, the client does not advertise support, and the agent must fall back to the existing `plan` session update type. When the Client advertised `plan`, Agents **SHOULD** send their plans with `plan_update` instead of `plan`. ### Multiple plans The `planId` field on every plan variant identifies a specific plan. * Each `plan_update` replaces the whole plan with that `planId`, whatever its `type`, including when the type differs from the previous update. * Clients track plans by ID. Different plans may use different types (for example, one `items` plan and one `markdown` plan). * For `items` plans, the Agent sends the complete list of entries in each update. An empty `entries` array empties the plan. Clients **MAY** hide an empty plan. ### File plans Plan file URIs **MUST** be absolute. ### Plan removal The Agent sends a `plan_removed` session update with the plan's `planId` to remove it. This is a separate session update type from `plan_update`, so content updates and lifecycle events stay distinct. * Agents **SHOULD** send `plan_removed` when a plan is cancelled, for example when the user rejects it or the Agent abandons it. A finished plan doesn't need to be removed. * Clients **MUST** ignore `plan_removed` for a `planId` they don't know. ### Protocol versions In ACP v1, `plan_update` and `plan_removed` require the Client's `plan` capability, as described above. The v1 `PlanUpdateContent` has no fallback for unknown `type` values, so a v1 Client that receives an unknown plan type fails to parse the notification. A new v1 plan type would need its own capability. In ACP v2, the [v2 Plan Variants RFD](/rfds/v2/plan-variants) makes `plan_update` with `type: "items"` the only plan update and removes the `plan` capability. `markdown`, `file`, and `plan_removed` remain unstable in v2 and need no capability. v2 Clients that don't know a plan type treat it as replacing the plan with that `planId` through the unknown plan-content fallback. ## Shiny future > How will things will play out once this feature exists? Agents will be able to present plans in the format most natural to them — structured checklists for step-by-step execution, markdown for free-form design docs, or file URIs for large plans generated externally. Clients that support `plan_update` can show multiple concurrent plans (e.g., a high-level strategy and a detailed implementation checklist), and dismiss plans that are no longer relevant. Clients that don't advertise `plan` continue to receive the existing `plan` updates with no changes. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? ### Protocol implementation The schema is implemented behind the `unstable_plan_operations` Cargo feature: * ACP v1 defines `PlanUpdate`, `PlanUpdateContent`, `PlanItems`, `PlanFile`, `PlanMarkdown`, `PlanRemoved`, `PlanId`, and `PlanCapabilities`, and adds `plan` to `ClientCapabilities`. * ACP v2 defines `markdown`, `file`, and `plan_removed` on top of the stable `items` plan update. * The draft protocol guides describe both versions. See the [v1 guide](/protocol/v1/draft/agent-plan#plan-operations) and [v2 guide](/protocol/v2/draft/agent-plan#unstable-plan-operations). The feature remains behind `unstable_plan_operations` and is not included in the stable schemas. ### Agent and Client implementations | Implementation | Reference | Behavior | | - | - | - | | Zed | [PR #66345](https://github.com/zed-industries/zed/pull/66345) | Client. Advertises `plan` on v1 behind its `acp-beta` feature flag. Handles `items`, `markdown`, `file`, and `plan_removed` on v1 and v2. Keeps every plan by `planId` and shows the most recently changed one. Shows a `file` plan as a link to the file. | | Claude Agent adapter | [PR #1554](https://github.com/agentclientprotocol/claude-agent-acp/pull/1554), included in [v0.102.0](https://github.com/agentclientprotocol/claude-agent-acp/releases/tag/v0.102.0) | Agent. Sends the TodoWrite checklist as an `items` plan and an approved plan-mode plan as a `markdown` plan. Sends `plan_removed` for an emptied checklist and on `/clear`. Falls back to `plan` when a v1 Client doesn't advertise `plan`. Doesn't send `file` plans, because a `file://` URI only resolves on the Agent's machine. | | Codex adapter | [PR #351](https://github.com/agentclientprotocol/codex-acp/pull/351) and [PR #752](https://github.com/agentclientprotocol/codex-acp/pull/752) (`items` plans on v1, not yet released) | Agent. Sends `update_plan` checklists as an `items` plan and plan-mode plans as `markdown` plans, one `planId` per plan. Falls back to `plan` for checklists and to Agent messages for plan-mode plans when a v1 Client doesn't advertise `plan`. Doesn't send `file` plans or `plan_removed`. | ### Json format examples Existing `plan` (unchanged): ```json theme={null} { "sessionUpdate": "plan", "entries": [{ "content": "Step 1", "priority": "high", "status": "pending" }] } ``` Item-based (`plan_update`): ```json theme={null} { "sessionUpdate": "plan_update", "plan": { "type": "items", "planId": "plan-1", "entries": [ { "content": "Step 1", "priority": "high", "status": "pending" } ] } } ``` Markdown: ```json theme={null} { "sessionUpdate": "plan_update", "plan": { "type": "markdown", "planId": "plan-1", "content": "## Steps\n- [ ] Refactor module\n- [ ] Add tests" } } ``` File-based: ```json theme={null} { "sessionUpdate": "plan_update", "plan": { "type": "file", "planId": "design-doc", "uri": "file:///tmp/plan.md" } } ``` Removal: ```json theme={null} { "sessionUpdate": "plan_removed", "planId": "plan-1" } ``` ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why a new session update type instead of extending the existing `plan`? The existing `plan` variant flattens `Plan`'s `entries` field directly into the `SessionUpdate` discriminated union object. Adding a nested `plan` field, optional `planId`, and polymorphic types to the same variant would require breaking the existing format or complex dual-deserialization logic. A new `plan_update` variant avoids this, but agents must only send it to clients that advertised `plan`; clients that do not advertise support can continue to receive the existing `plan` update. ### Why a separate `plan_removed` session update type instead of a removal variant inside `plan_update`? Keeping removal as a separate session update type means `plan_update`'s `type` discriminator only covers content variants (`items`, `file`, `markdown`), making the schema cleaner. ### Why plan-specific markdown and not a generic markdown content API? A generic "agent shares markdown document" API would be simpler and more reusable. However, keeping it plan-typed enables clients to build plan-aware UX: selecting plan steps for partial execution, tracking plan progress, showing plan history. A generic markdown block wouldn't carry this semantic meaning. If future use cases need generic markdown sharing, that can be a separate feature. ### When should an Agent remove a plan? When the plan is cancelled, for example when the user rejects it or the Agent abandons it. A finished plan still shows what the Agent did, so the Agent doesn't need to remove it. Clients can hide or collapse finished plans themselves. ### What alternative approaches did you consider, and why did you settle on this one? 1. **Extending the existing `plan` variant**: Would break backward compatibility or require complex dual-format deserialization. 2. **`"type": "removed"` variant inside `plan_update`**: Instead of a separate `plan_removed` session update type, removal could be a variant in the `plan_update` tagged union (e.g., `"type": "removed"`). This keeps the entire plan lifecycle within a single update type. The tradeoff is that the `type` discriminator mixes content variants with a lifecycle event, making the schema less clean. ## Revision history * 2026-04-02: Initial draft * 2026-11-09: Defined replacement across types, empty `items` plans, absolute file URIs, when Agents remove plans, and removal of unknown plan IDs. Described the v1 and v2 differences and added the Zed, Claude Agent, and Codex implementations # Agent Extensions via ACP Proxies Source: https://agentclientprotocol.com/rfds/proxy-chains Author(s): [nikomatsakis](https://github.com/nikomatsakis) ## Elevator pitch > What are you proposing to change? Enable a universal agent extension mechanism via ACP proxies, components that sit between a client and an agent. Proxies can intercept and transform messages, enabling composable architectures where techniques like context injection, tool coordination, and response filtering can be extracted into reusable components. ## Status quo > How do things work today and what problems does this cause? Why would we change things? The AI agent ecosystem has developed many extension mechanisms: AGENTS.md files, Claude Code plugins, rules files, hooks, MCP servers, etc. Of these, only MCP servers have achieved real standardization across the ecosystem. However, MCP servers are fundamentally limited because they sit "behind" the agent. They can provide tools and respond to function calls, but they cannot: * **Inject or modify prompts** before they reach the agent * **Add global context** that persists across conversations * **Transform responses** before they reach the user * **Coordinate between multiple agents** or manage conversation flow As a result, valuable techniques like context management and response processing remain locked within individual agent implementations, with no way to extract and reuse them across different agents. ## What we propose to do about it > What are you proposing to improve the situation? We propose implementing *agent extensions* via ACP *proxies*, a new kind of component that sits between the client and the agent, forwarding (and potentially altering or introducing) messages. Because proxies can do anything a client could do, they serve as a universal extension mechanism that can subsume AGENTS.md, hooks, MCP servers, etc. Proxies are limited to the customizations exposed by ACP itself, so they would benefit from future ACP extensions like mechanisms to customize system prompts. However, they can already handle the majority of common extension use cases through message interception and transformation. ### Proxying in theory Conceptually, proxies work like a chain where messages flow through each component: ```mermaid theme={null} flowchart LR Client[ACP Client] -->|messages| P1[Context Proxy] P1 -->|enhanced| P2[Tool Filter Proxy] P2 -->|filtered| A[Base Agent] A -->|responses| P2 P2 -->|processed| P1 P1 -->|final| Client ``` ### Proxying in practice: the role of the conductor To allow for proxy isolation, our design does not have proxies communicate directly with their successor in the chain. Instead, there is a central *conductor* component that orchestrates messages moving between components. ```mermaid theme={null} flowchart TB Client[Client] C[Conductor] P1[Context Proxy] P2[Tool Filter Proxy] A[Agent] Client <-->|ACP| C C <-->|ACP| P1 C <-->|ACP| P2 C <-->|ACP| A ``` We add one ACP method for proxy communication: * **`proxy/successor`**: Used bidirectionally - proxies send it to forward messages to their successor, and the conductor sends it to deliver messages from the successor back to the proxy Here's how a single message flows through the system: ```mermaid theme={null} sequenceDiagram participant Client participant Conductor participant P1 as Context Proxy participant P2 as Tool Filter Proxy participant Agent Client->>Conductor: prompt request Conductor->>P1: prompt request P1->>Conductor: proxy/successor (enhanced prompt) Conductor->>P2: enhanced prompt P2->>Conductor: proxy/successor (filtered prompt) Conductor->>Agent: filtered prompt Agent-->>Conductor: response Conductor-->>P2: response P2-->>Conductor: processed response Conductor-->>P1: processed response P1-->>Conductor: final response Conductor-->>Client: final response ``` ## Shiny future > How will things play out once this feature exists? ### User experience and editor integration We expect editors to expose the ability to install proxies in the same way they currently support adding MCP servers - in fact, the distinction probably doesn't matter to users. Both are "extensions" that add capabilities to their AI workflow. When proxies are installed, editors would not start the agent directly, but instead invoke the conductor with the configured proxy chain. From the user's perspective, they're just getting enhanced agent capabilities - the proxy chain architecture remains transparent. ### Language-specific proxy ecosystems The monolithic nature of agent development has meant that most of the "action" happens within agents. We wish to invert this, with agents trending towards simple agentic loops, and the creativity being pushed outwards into the broader ecosystem. The Symposium project is one example exploring this concept, with a focus on Rust. The idea is to give Rust users an automatic set of extensions based on the dependencies they are using. These extensions would be packaged up as ACP proxies using WebAssembly for portability and sandboxing. Symposium aims to become the standard "Rust ACP experience" by providing both core Rust tooling and a framework for Rust libraries to contribute their own proxy components. ```mermaid theme={null} flowchart LR Client[Client] Conductor[Conductor] Agent[Agent] subgraph Symposium["symposium-acp proxy"] RustTools[Rust Language Tools] CrateA[tokio-acp proxy] CrateB[serde-acp proxy] CrateC[bevy-acp proxy] RustTools --> CrateA CrateA --> CrateB CrateB --> CrateC end Client --> Conductor Conductor --> Symposium Symposium --> Agent ``` ### Standardized IDE capabilities Proxy infrastructure could also enable editors to expose standardized IDE capabilities (diagnostics, file system access, terminal APIs) to agents via MCP servers provided by proxies. This keeps the core ACP protocol focused on agent communication while allowing rich IDE integration through the proxy layer. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? ### Component roles Each ACP proxy chain forms a sequence of components: ```mermaid theme={null} flowchart LR Client --> Proxy0 --> Proxy1 --> ... --> ProxyN --> Agent ``` The **client** and **agent** are *terminal* roles - the client has only a successor (no predecessor), and the agent has only a predecessor (no successor). Proxies are *non-terminal* - they have both a predecessor and a successor, forwarding messages between them. The **conductor** is a special component that orchestrates proxy chains. It spawns and manages proxy components, routes messages between them, and handles initialization. From the client's perspective, the conductor appears to be an ordinary agent: ```mermaid theme={null} flowchart LR Client -->|ACP| Conductor subgraph Managed["Managed by Conductor"] Proxy0 --> Proxy1 --> ... --> Agent end Conductor -.->|spawns & routes| Managed ``` We provide a canonical conductor implementation in Rust (`agent-client-protocol-conductor`). Most editors would use this conductor directly to host proxies and agents, though they could also reimplement conductor functionality if needed. ACP defines client and agent as superroles, each with two specializations: ```mermaid theme={null} classDiagram class Client { <> +sends prompts } class Agent { <> +responds to prompts } class TerminalClient { +receives direction from user +connects to terminal agent } class Conductor { +manages proxy chain +sends successor messages } class TerminalAgent { +embodies the LLM +final destination +no successor } class Proxy { +forwards to successor +sends successor messages } Client <|-- TerminalClient Client <|-- Conductor Agent <|-- TerminalAgent Agent <|-- Proxy ``` **Example Architecture:** ```mermaid theme={null} flowchart TB TC[Terminal Client] C[Conductor] P1[Context Proxy] P2[Tool Filter Proxy] TA[Terminal Agent] TC -->|terminal client| C C -->|terminal agent| TC C -->|conductor| P1 P1 -->|proxy| C C -->|conductor| P2 P2 -->|proxy| C C -->|terminal client| TA TA -->|terminal agent| C ``` ### Proxy initialization protocol Components discover their role from the initialization method they receive: * **Proxies** receive `proxy/initialize`. They have a successor and forward messages to it. * **Agents** receive `initialize`. They are terminal (no successor) and process messages directly. `proxy/initialize` takes the same params and returns the same result as `initialize` for the chain's protocol version. In the schema these are `InitializeProxyRequest` and `InitializeProxyResponse`, which have the version's `InitializeRequest` and `InitializeResponse` shapes. Only the method name differs, and it tells the component to run as a proxy. **Conductor behavior:** * The conductor MUST send `proxy/initialize` to all proxy components * The conductor MUST send `initialize` to the final agent component (if any) * The conductor sends the client's `initialize` request to the first proxy as `proxy/initialize`. When a proxy forwards an `initialize` via `proxy/successor`, the conductor determines whether the successor is another proxy or the agent, and sends `proxy/initialize` or `initialize` respectively. **Proxy behavior:** * A proxy that receives `proxy/initialize` knows it has a successor * Before it answers `proxy/initialize` successfully, the proxy MUST forward an `initialize` request to its successor through `proxy/successor`, so that the rest of the chain is initialized. It MAY answer with an error without forwarding. * The proxy builds its `proxy/initialize` result from its successor's `initialize` result. It MAY change the capabilities and other fields so that the result describes the chain from the proxy onward, for example to add a capability it implements or remove one it blocks. It MUST NOT change `protocolVersion`. * The proxy SHOULD forward requests and notifications it does not understand. See [Forwarding](#forwarding). * The proxy SHOULD preserve metadata fields when forwarding messages **Repeated initialization:** A client may repeat `initialize` when the chain's protocol version allows it (see [Repeating initialization](/protocol/v2/initialization#repeating-initialization) in v2). The conductor forwards a repeated `initialize` through the chain like the first one, without starting the chain again: the first proxy receives it as `proxy/initialize`. A proxy handles a repeated `proxy/initialize` the way an Agent handles a repeated `initialize`, and forwards `initialize` to its successor again under the same rules as the first time. A conductor in proxy mode does the same with a repeated `proxy/initialize` from its own conductor. Note: A conductor can be configured to run in either terminal mode (expecting `initialize`) or proxy mode (expecting `proxy/initialize`), enabling nested proxy chains. ### Protocol versions A chain speaks one ACP protocol version. Each component selects it the way an Agent does during version negotiation ([v1](/protocol/v1/initialization#version-negotiation), [v2](/protocol/v2/initialization#version-negotiation)), so the version can only go down along the chain: * `proxy/initialize` carries the `initialize` params at the version the conductor selected, which is the client's requested version unless the conductor supports only a lower one. The conductor sets `protocolVersion` to that version, and if it selected the requested version it forwards the client's params unchanged. A chain without proxies receives `initialize` the same way. * A proxy negotiates `proxy/initialize` the same way. If it does not support the version it received, it forwards `initialize` to its successor with a lower version it supports. * The version in the agent's `initialize` response applies to every component in the chain. Each proxy returns it unchanged in its `proxy/initialize` response, so the response the client receives carries the version the whole chain accepted. On an ACP v2 chain, the rules of that version apply to every hop, including the wrapped messages: request IDs are never `null`, and JSON-RPC batches are not used. ### Forwarding * Proxies and the conductor forward messages without parsing and re-serializing them where they don't need to, so unknown fields and `_meta` survive every hop. * A proxy SHOULD forward requests and notifications it does not handle, in both directions, without changing them. This includes methods it does not recognize, such as extension methods. * A request that no component handles reaches the end of the chain. There the agent (or the client, for a request from the agent) answers it with `-32601` (Method not found), and that error passes back to the sender unchanged like any other result. A proxy answers `-32601` itself only for a request it decides not to forward. * A notification that no component handles is dropped at the end of the chain. Notifications get no response. * `$/cancel_request` is never forwarded. See [Cancellation](#cancellation). ### Cancellation Cancellation is hop-local, as described in [Request cancellation](./request-cancellation): * The `requestId` in `$/cancel_request` is the ID of a request on the connection the notification arrives on. It means nothing on any other connection, so proxies and the conductor MUST NOT forward a `$/cancel_request` to another hop, whether it arrived plain or wrapped in `proxy/successor`. * To cancel a `proxy/successor` request, the sender sends `$/cancel_request` on the same connection with the ID of that `proxy/successor` request. It SHOULD send it plain. A receiver MUST treat a `$/cancel_request` wrapped in `proxy/successor` the same as a plain one: its `requestId` still names the `proxy/successor` request on that connection. * A component that forwarded a request and then sees that request cancelled sends its own `$/cancel_request` for the request it forwarded, with that hop's ID. Cancellation reaches the end of the chain one hop at a time. ```text theme={null} Client -> Conductor: session/prompt (id 1) Conductor -> Proxy: session/prompt (id 10) Proxy -> Conductor: proxy/successor {method: "session/prompt"} (id 20) Conductor -> Agent: session/prompt (id 30) Client -> Conductor: $/cancel_request {requestId: 1} Conductor -> Proxy: $/cancel_request {requestId: 10} Proxy -> Conductor: $/cancel_request {requestId: 20} Conductor -> Agent: $/cancel_request {requestId: 30} ``` ### Errors the conductor returns The pass-through rule in the [message reference](#message-reference) covers the result or error of a wrapped request. The conductor also answers some requests itself. These errors come from the conductor, not from a successor: * Before the chain is initialized, the conductor answers any request other than `initialize` (`proxy/initialize` for a conductor in proxy mode) with `-32600` (Invalid request), and drops notifications. It answers an initialization request without a valid `protocolVersion` with `-32602` (Invalid params). After either error the conductor is still uninitialized, and the client may retry. * If the conductor cannot start the chain, it answers the initialization request with an error and answers every later request with the same error. * Only the conductor sends `proxy/initialize`. It answers a `proxy/initialize` request from any other component, including one a proxy wraps in `proxy/successor`, with `-32600`. A conductor in proxy mode answers a plain `initialize` request with `-32600`. * `proxy/successor` is exchanged only between the conductor and the proxies it initialized, and between a conductor in proxy mode and its own conductor. The conductor answers a `proxy/successor` request from the agent, or from the client of a conductor in terminal mode, with `-32600`, and drops such a notification. It does not forward either. * A `proxy/successor` request without a string `method`, or whose `params` is not an object, an array, or `null`, gets `-32602`. * If a component has exited, or exits before it answers, the conductor answers each request that it could not deliver or that is still waiting for that component with `-32603` (Internal error). The same applies when the conductor cannot route a message for another reason. A conductor MAY instead close its connection to the client when a component fails. ### MCP-over-ACP support The [MCP-over-ACP transport](./mcp-over-acp) targets stateless MCP 2026-07-28 only. Requests target a declared `serverId`; a separate logical MCP `requestId` correlates request-scoped notifications and remains unchanged when proxies renumber the outer ACP JSON-RPC ID. There is no MCP connect/disconnect lifecycle. Proxies that provide MCP servers use the [MCP-over-ACP transport](./mcp-over-acp) mechanism. Capability advertising reflects what the downstream chain can consume; the conductor does not unconditionally add MCP-over-ACP support. In the Rust SDK, an explicit `McpOverAcpPolyfill` proxy can be placed immediately before an HTTP-capable agent that lacks native ACP MCP support. A forwarding proxy preserves downstream MCP capabilities. A bridging proxy may advertise ACP MCP support only when its successor can consume the target MCP revision over the adapted transport. Proxies that publish MCP servers handle `mcp/message` requests as soon as their declarations are forwarded, including while session setup is still in progress. Ordinary ACP response forwarding and hop-local cancellation apply; logical MCP IDs and payloads are preserved. See the transport RFD for the v1 and draft-v2 capability shapes. ### Message reference **Initialization:** ```json theme={null} // Conductor initializes a proxy (proxy knows it has a successor) {"method": "proxy/initialize", "params": } // Conductor initializes the agent (standard ACP) {"method": "initialize", "params": } ``` Both methods take the params of the version's `InitializeRequest` and return its `InitializeResponse`. A proxy's response describes the chain from that proxy onward. **Proxy messages:** ```json theme={null} // Proxy sends message to successor, or conductor delivers message from successor // (same method, direction determined by sender) { "method": "proxy/successor", "params": { "method": "", "params": , "_meta": { ... } // optional metadata } } ``` The inner message fields (`method`, `params`) are flattened into the params object. The optional `_meta` belongs to the `proxy/successor` envelope and is hop-local: it describes the envelope on this connection. The conductor does not copy it into the message it unwraps, and it MAY set its own envelope `_meta` when it wraps a message. The wrapped message's own metadata stays in its `params` and is forwarded with them. Whether the wrapped message is a request or notification is determined by the presence of an `id` field in the outer JSON-RPC envelope, following JSON-RPC conventions. `params` is optional, and omitting it is equivalent to `null`: the wrapped message has no params, and the receiver unwraps it to a message without `params`. When present, it MUST be an object or an array, as JSON-RPC requires for params. ACP methods use objects. The result or error of a wrapped request **MUST** be returned unchanged, as the same JSON value, as the result or error of the `proxy/successor` request. The same JSON value need not be the same bytes, because implementations that parse JSON may write numbers differently, for example `1E2` as `100.0`, or may not keep integers beyond 64 bits exactly. An error keeps its `code`, `message`, and `data`. JSON-RPC defines no other members of the error object, and implementations may drop them. ### Schema Both methods are in the v1 and draft v2 schemas behind the `unstable_proxy_chains` feature. Because only conductors and proxies exchange them, they form their own `proxy` side, separate from the agent and client methods, with their own `ProxyRequest`, `ProxyResponse`, and `ProxyNotification` unions and a `proxyMethods` entry in `meta.json`. | Type | Shape | | - | - | | `InitializeProxyRequest` | The version's `InitializeRequest`, unchanged. | | `InitializeProxyResponse` | The version's `InitializeResponse`, unchanged. | | `ProxySuccessorRequest` | `method` (required string), `params` (optional: a JSON object or array, or `null`), `_meta`. | | `ProxySuccessorNotification` | Same as `ProxySuccessorRequest`. | | `ProxySuccessorResponse` | The wrapped request's result, unchanged. | ### Examples (non-normative) The following sequence diagrams illustrate common proxy chain scenarios for implementers. #### Initialization of a 4-component proxy chain This shows the initialization flow for: Terminal Client → Conductor → Context Proxy → Tool Filter Proxy → Terminal Agent ```mermaid theme={null} sequenceDiagram participant TC as Terminal Client participant C as Conductor participant P1 as Context Proxy participant P2 as Tool Filter Proxy participant TA as Terminal Agent Note over TC,TA: === Initialization Phase === TC->>C: initialize Note over C: Conductor spawns proxy components C->>P1: proxy/initialize Note over P1: Proxy forwards to successor P1->>C: proxy/successor (initialize) Note over C: Conductor sends proxy/initialize to next proxy C->>P2: proxy/initialize Note over P2: Proxy forwards to successor P2->>C: proxy/successor (initialize) Note over C: Conductor sends initialize to final agent C->>TA: initialize TA-->>C: InitializeResponse (mcpCapabilities.acp: true/false) C-->>P2: proxy/successor (InitializeResponse) P2-->>C: InitializeResponse C-->>P1: proxy/successor (InitializeResponse) P1-->>C: InitializeResponse Note over C: Conductor acts as terminal agent to client C-->>TC: InitializeResponse Note over TC,TA: Proxy chain initialized and ready ``` #### Context-providing proxy with session notifications This example shows how a proxy can handle initialization and forward session notifications. Sparkle (a collaborative AI framework) runs an embodiment sequence during session creation. ```mermaid theme={null} sequenceDiagram participant Client participant Sparkle as Sparkle Proxy participant Agent Note over Client: Client creates new session Client->>Sparkle: session/new Note over Sparkle: Adds Sparkle MCP server Sparkle->>Agent: session/new + sparkle tools Agent-->>Sparkle: session created (sessionId: S1) Sparkle-->>Client: session/new response (sessionId: S1) Note over Client: Client sends first prompt (during embodiment) Client->>Sparkle: prompt ('Hello, can you help me?') activate Sparkle Note over Sparkle: Delays client prompt, runs embodiment first Sparkle->>Agent: prompt ('you are sparkle...') Note over Agent: Processes embodiment, sends notifications Agent->>Sparkle: session/update (S1: thinking...) Sparkle->>Client: session/update (S1: thinking...) Agent->>Sparkle: session/update (S1: embodiment complete) Sparkle->>Client: session/update (S1: embodiment complete) Agent-->>Sparkle: embodiment response Note over Sparkle: Discards embodiment response, now processes delayed prompt Sparkle->>Agent: prompt ('Hello, can you help me?') deactivate Sparkle Agent-->>Sparkle: response to client Sparkle-->>Client: response to client Note over Client,Agent: Session ready with Sparkle patterns active ``` This demonstrates how proxies can run initialization sequences during session creation while transparently forwarding all session notifications back to the client. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why use a separate `proxy/initialize` method instead of a capability? Earlier designs used a `"proxy": true` capability in the `InitializeRequest` and required proxies to echo it back in the response. This felt awkward because it wasn't really a capability negotiation - it was more of a "you must operate as a proxy" directive. Using a distinct method makes the contract clearer: if you receive `proxy/initialize`, you're a proxy with a successor; if you receive `initialize`, you're the terminal agent. There's no capability dance, no risk of misconfiguration, and components know their role immediately from the method name. ### How do proxies subsume existing agent extension mechanisms? Because proxies sit between the client and agent, they can replicate the functionality of existing extension mechanisms: * **AGENTS.md files**: Proxies can inject context and instructions into prompts before they reach the agent * **Claude Code plugins/skills**: Proxies can add contextual data for available skills and provide MCP resources with detailed skill instructions that are provided on-demand when requested by the agent * **MCP servers**: Proxies can provide tools via [MCP-over-ACP](./mcp-over-acp) and handle tool callbacks * **Subagents**: Proxies can create "subagents" by initiating new sessions and coordinating between multiple agent instances * **Hooks and steering files**: Proxies can modify conversation flow by intercepting requests and responses * **System prompt customization**: Proxies can switch between predefined session modes or prepend system messages to prompts The key advantage is that proxy-based extensions work with any ACP-compatible agent without requiring agent-specific integration or modification. ### How do proxies work with MCP servers? Proxies can provide MCP servers via [MCP-over-ACP transport](./mcp-over-acp), enabling a single proxy to add context, provide tools, and handle callbacks with full awareness of the conversation state. When the agent supports native ACP MCP transport, no adapter is needed. Otherwise, the chain can include an explicit adapter for a modern MCP HTTP client. The Rust SDK's HTTP polyfill rewrites MCP declarations to local HTTP endpoints and relays requests and request-scoped notifications to and from the providing proxy's ACP channel. Requests may share a listening endpoint without sharing MCP session state. Tool-providing proxies implement MCP-over-ACP without managing those alternative transports themselves. The chain's owner chooses an appropriate adapter, and the resulting advertised capability tells providers whether ACP MCP servers can be consumed. ```mermaid theme={null} sequenceDiagram participant Client participant P1 as Context Proxy participant P2 as Filter Proxy participant Agent Note over Client: User asks about project structure Client->>P1: prompt request Note over P1: Analyzes project, adds context + filesystem MCP server P1->>P2: enhanced prompt + filesystem MCP server Note over P2: Forwards enhanced prompt P2->>Agent: prompt with context + tools available Note over Agent: Decides to explore project structure Agent->>P2: mcp/message (list files) Note over P2: Forwards tool call back to Context Proxy P2->>P1: mcp/message (list files) Note over P1: Handles tool call with full project context P1-->>P2: file listing with relevant details P2-->>Agent: file listing with relevant details Agent-->>P2: response using both context and tool results P2-->>P1: response (potentially filtered) P1-->>Client: final response ``` ### Are there any limitations to what proxies can do? Yes, proxies are limited to what is available through the ACP protocol itself. They can intercept and transform any ACP message, but they cannot access capabilities that ACP doesn't expose. For example, proxies cannot directly modify an agent's system prompt or context window - they can only switch between predefined session modes (which may affect system prompts) or prepend additional messages to prompts. Similarly, proxies cannot access internal agent state, model parameters, or other implementation details that aren't exposed through ACP messages. This is actually a feature - it ensures that proxy-based extensions remain portable across different agent implementations and don't rely on agent-specific internals. ### Why not just cascade ACP commands without protocol changes? One alternative is to make proxies be ordinary agents that internally create and manage their successors. This works (HTTP proxies operate this way) but requires each proxy to understand the full chain and know how to start its successors. This couples proxies to transport mechanisms, process management, and chain configuration. Changing transports, reordering the chain, or inserting a new proxy requires modifying predecessor configurations. The conductor design decouples proxies from their successors. Proxies send messages "to successor" and receive messages "from successor" without knowing who that successor is, how it's started, or what transport it uses. This enables: * Changing transport protocols or process management without recompiling proxies * Shipping proxies as low-capability WASM containers that need only a single communication channel * Reordering, adding, or removing proxies through configuration rather than code changes The tradeoff is protocol complexity, but this complexity lives in the conductor (implemented once) rather than being duplicated across proxy implementations. ### Why do all messages go through the conductor instead of direct proxy-to-proxy communication? Even with a conductor, proxies could communicate directly with their successors after the conductor sets up connections. Routing all messages through the conductor further minimizes proxy responsibilities to a single communication channel. This supports running proxies as isolated WebAssembly components with minimal capabilities. It also removes redundant logic: without the conductor routing messages, each proxy would need to manage connections to its successor. The conductor handles process management, capability negotiation, and message routing, allowing proxies to focus on transformation logic. ### How does the standard conductor implementation work? The `agent-client-protocol-conductor` reference implementation can form trees of proxy chains. It can be configured to run in proxy mode (expecting `proxy/initialize`) or terminal mode (expecting `initialize`). When the last proxy in its managed chain sends a message to its successor, the conductor forwards that message to its own parent conductor (if in proxy mode) or to the final agent (if in terminal mode). This enables hierarchical structures like: ``` client → conductor1 → final-agent ↓ manages proxy-a → conductor2 → proxy-d ↓ manages proxy-b → proxy-c ``` The conductor handles process management, capability negotiation, and message routing, but these are implementation details - the protocol only specifies the message formats and capability requirements. ### What about security concerns with proxy chains? Proxy components can intercept and modify all communication, so trust is essential - similar to installing any software. Users are responsible for the components they choose to run. We plan to explore WebAssembly-based proxies which will offer some measure of sandboxing but such components could still modify prompts in unknown or malicious ways. ### What about performance implications of the proxy chain? Our architecture does introduce additional message passing - each proxy in the chain adds extra hops as messages flow through the conductor. However, these messages are typically small and inexpensive, particularly when compared to the latency of actual LLM inference. For messages that contain significant quantities of data (large file contents, extensive context), we may wish to have the conductor store that data centrally and introduce a "reference" mechanism so that most proxies don't have to inspect or copy large payloads unless they specifically need to transform them. The benefits of composability typically outweigh the minimal latency costs for human-paced development interactions. ### What happens when proxy components crash or misbehave? The conductor answers requests that a failed component can no longer answer with `-32603`, or closes its connection to the client. See [Errors the conductor returns](#errors-the-conductor-returns). Whether a conductor restarts or bypasses a failed component is conductor behavior, not part of the protocol. ### Can proxy chains be nested or form trees? Yes! The conductor can itself run in proxy mode, enabling hierarchical structures: ``` client → proxy1 → conductor (proxy mode) → final-agent ↓ manages p1 → p2 → p3 ``` This enables complex compositions while maintaining clean interfaces. ### How could proxy chains support multi-agent scenarios in the future? The current design assumes a linear chain where each proxy has a single successor. To support M:N topologies where a proxy communicates with multiple peers (e.g., a research coordinator dispatching to multiple specialized agents), we could extend `proxy/successor` with an optional `peer` field: ```json theme={null} { "method": "proxy/successor", "params": { "method": "prompt", "params": { ... }, "peer": "research-agent" } } ``` When `peer` is omitted, the message goes to the default successor (backwards compatible with the current linear chain model). When present, it specifies which peer the message is intended for. The `proxy/initialize` response could be extended to enumerate available peers, enabling proxies to discover and coordinate between multiple downstream components. ### What's the current implementation status? This proposal is implemented in the [Rust SDK](https://github.com/agentclientprotocol/rust-sdk), for both ACP v1 and the draft v2 protocol: * `agent-client-protocol` -- proxy roles and the `proxy/initialize` and `proxy/successor` messages * `agent-client-protocol-conductor` -- reference conductor implementation * `agent-client-protocol-rmcp` -- bridging proxies to the `rmcp` crate * `agent-client-protocol-polyfill` -- compatibility proxies, such as MCP-over-ACP for agents without native support Earlier releases of the Rust SDK used the `_proxy/initialize` and `_proxy/successor` method names. ## Revision history * Initial draft based on working implementation in symposium-acp repository. * Split MCP-over-ACP transport into [separate RFD](./mcp-over-acp) to enable independent use by any ACP component. * **2026-10-30**: Added schema support behind `unstable_proxy_chains` as a separate `proxy` side, required wrapped request results and errors to pass through unchanged, and marked the crash-handling FAQ as conductor behavior. * **2026-10-30**: Named the `proxy/successor` metadata field `_meta`, defined how a chain carries one protocol version (including draft v2), and updated the implementation status to the Rust SDK crates. * **2026-11-01**: Matched the rules to the reference conductor. Defined how each proxy negotiates the protocol version and builds its `proxy/initialize` response, how unknown requests and notifications are forwarded, hop-local cancellation and envelope `_meta`, and the errors the conductor returns. Required wrapped `params` to be an object, an array, or `null`, and defined "unchanged" for wrapped results and errors as the same JSON value. Defined repeated `proxy/initialize`. Linked version negotiation for both v1 and v2, replaced the old `sacp-conductor` name, and removed crash-handling claims the reference conductor does not implement. # Request Cancellation Mechanism Source: https://agentclientprotocol.com/rfds/request-cancellation * Author(s): [Artem Bukhonov](https://github.com/nerzhulart) * Champion: [@benbrandt](https://github.com/benbrandt) ## Elevator pitch Introduce a standardized per-request cancellation mechanism for the Agent Client Protocol, inspired by the [Language Server Protocol (LSP)](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#cancelRequest), to enable a more granular cancellation of requests where individual JSON-RPC requests can be cancelled one by one. ## Status quo The JSON-RPC specification doesn't define any standard mechanism for request cancellation and leaves it up to the implementation. Currently, ACP has some ad-hoc cancellation mechanisms for specific features (like prompt turn cancellation via `session/cancel`), but lacks a general-purpose, per-request cancellation mechanism. This creates the following inconveniences: * cancellation should be handled for each feature separately * some languages that support handy cancellation mechanisms (C#, Kotlin, etc.) can't implement general-purpose request cancellation using ACP low-level machinery, and rather developers should manually call per-feature cancellation methods ## What we propose to do about it Implement an **optional** `$/cancel_request` notification method (inspired by the Language Server Protocol) to both Agent and Client that uses JSON-RPC 2.0 notification format, allowing either party (client or agent) to cancel any outstanding request by its ID. The mechanism will be: * **Optional**: Not all implementations may support this feature, but it is recommended for those that do. * **Flexible**: Provides two response options when cancellation is received: 1. An error response with the standard cancellation error code (-32800) 2. A valid response with partial or cancelled data (when meaningful partial results exist) This approach balances flexibility with standardization, allowing implementations to opt-in to cancellation support while providing predictable behavior when enabled. ## Shiny future Once implemented, this enables: * **SDK integration layer**: Default mechanism that ACP SDKs can automatically wire to native language cancellation (C# CancellationToken, Kotlin Job, Go context.Context, JavaScript AbortController, etc.) * Individual JSON-RPC request cancellation without affecting other concurrent requests * Universal fallback for any request when feature-specific cancellation methods don't exist * Consistent cancellation behavior from both external `$/cancel_request` and internal cancellation triggers * Standard error response (`-32800`) or partial results when requests are cancelled regardless of cancellation source In a future version, we could potentially deprecate the `session/cancel` notification in favor of the more general approach, as it would still provide the same functionality but with more flexibility and consistency. ## Implementation details and plan ### Protocol Changes #### Cancellation Method Add the `$/cancel_request` notification method to the JSON-RPC protocol: ```typescript theme={null} interface CancelNotification { method: "$/cancel_request"; params: { requestId: string | number; // ID of request to cancel }; } ``` ### Cancellation Behavior Either party can send `$/cancel_request` to cancel requests. Notifications whose methods start with '$/' are messages which are protocol implementation dependent and might not be implementable in all clients or agents. For example if the implementation uses a single threaded synchronous programming language then there is little it can do to react to a `$/cancel\_request\` notification. If an agent or client receives notifications starting with '\$/' it is free to ignore the notification. The **receiving party** is **NOT** required to: * Perform special handling for unsupported cancellation requests * Return custom errors for unsupported `$/cancel_request` notifications #### Cancellation Processing When a `$/cancel_request` notification is received by a supporting implementation, it: * **MAY** cancel the corresponding request activity and all nested activities related to that request * **MAY** finish sending any pending notifications before responding * **MUST** send one of these responses for the original request: * A valid response with appropriate data (such as partial results or cancellation marker) * An error response with code [`-32800` (Request Cancelled)](/protocol/v1/draft/schema#errorcode) Sending `$/cancel_request` does not guarantee that the receiver stops the request or its nested activities. It also does not automatically withdraw requests that the receiver has sent to the other party; propagating cancellation to those requests requires explicit implementation support. #### Internal Cancellation Requests can also be cancelled internally by the executing party without receiving `$/cancel_request`: * **Client-side examples**: User closes IDE, switches to different project, file becomes unavailable * **Agent-side examples**: LLM context limit reached, internal timeout, resource constraints When internal cancellation occurs, the executing party **SHOULD**: 1. Send the same `-32800` (Cancelled) error response as if `$/cancel_request` was received 2. Ensure consistent behavior regardless of cancellation source ### Error Code Add standard JSON-RPC error code `-32800` for cancelled requests: * Code: `-32800` * Message: "Request cancelled" * Meaning: Execution of the method was aborted either due to a cancellation request from the caller or because of resource constraints or shutdown. ## Implementations | Repository | Pull request / commit | Status | | - | - | - | | `zed-industries/zed` | [zed-industries/zed#59593](https://github.com/zed-industries/zed/pull/59593) | Merged | | `agentclientprotocol/rust-sdk` | [agentclientprotocol/rust-sdk#179](https://github.com/agentclientprotocol/rust-sdk/pull/179) | Merged | | `agentclientprotocol/typescript-sdk` | [agentclientprotocol/typescript-sdk#195](https://github.com/agentclientprotocol/typescript-sdk/pull/195) | Merged | | `agentclientprotocol/claude-agent-acp` | [agentclientprotocol/claude-agent-acp#801](https://github.com/agentclientprotocol/claude-agent-acp/pull/801) | Merged | | `agentclientprotocol/codex-acp` | [agentclientprotocol/codex-acp#221](https://github.com/agentclientprotocol/codex-acp/pull/221) | Merged | | `agentclientprotocol/kotlin-sdk` | [agentclientprotocol/kotlin-sdk@f345883](https://github.com/agentclientprotocol/kotlin-sdk/commit/f3458831da628e26ee29c4a5834d55b443bf5a31) | Needs method name update | ## Frequently asked questions ### What alternative approaches did you consider, and why did you settle on this one? The core need is to add **granular cancellation** as a general mechanism for individual JSON-RPC requests, while **feature-specific cancellation methods** (like `session/cancel`) remain useful for cases requiring additional domain semantics. We selected the **LSP-style `$/cancel_request`** approach because: * Serves as a **default cancellation layer** that SDK implementations can easily map to native language cancellation mechanisms * Proven pattern familiar to developers from LSP ecosystem * Works across all JSON-RPC transports (HTTP, WebSocket, stdio, pipes) * Provides universal fallback when feature-specific cancellation doesn't exist * Complements existing feature-specific methods rather than replacing them ### How does this relate to existing cancellation mechanisms like `session/cancel`? The `$/cancel_request` mechanism is complementary to feature-specific cancellation: * `$/cancel_request`: Generic cancellation for any JSON-RPC request by ID * `session/cancel`: Feature-specific cancellation with additional semantics (e.g., cancels entire prompt turn context, triggers specific cleanup logic) Both mechanisms serve different purposes: **Feature-specific methods** like `session/cancel` provide: * Domain-specific semantics and behavior * Structured cleanup for complex operations * Context-aware cancellation logic **Generic `$/cancel_request`** provides: * Default cancellation layer that bridges programming language cancellation mechanisms (C# CancellationToken, Kotlin Job, Go context.Context, etc.) with ACP * Universal fallback for any request when no feature-specific method exists * Simple ID-based targeting for SDK convenience * Standardized error responses Implementations can use both: feature-specific methods for rich semantics, and `$/cancel_request` for simple per-request cancellation. Note: it is possible that `session/cancel` could be replaced by the more generic `$/cancel_request` in future versions of the protocol. #### Example: Cascading Cancellation Flow This v1 example shows an Agent explicitly propagating cancellation to an outstanding terminal request. That propagation is optional, not an automatic protocol guarantee. Independently, the Client **MUST** answer pending permission requests with the `cancelled` outcome when it sends `session/cancel`, as specified in [prompt turn cancellation](/protocol/v1/prompt-turn#cancellation); it does not wait for `$/cancel_request`. ```mermaid theme={null} sequenceDiagram participant Client participant Agent Note over Client,Agent: 1. Session prompt in progress Client->>Agent: session/prompt (id=1, "Analyze file X") Agent-->>Client: session/update (agent started processing) Note over Client,Agent: 2. Agent makes concurrent requests Agent->>Client: terminal/create (id=2, "grep pattern file.txt") Agent->>Client: session/request_permission (id=3, "read sensitive file") Note over Client,Agent: 3. Client cancels the prompt turn Client->>Agent: session/cancel (sessionId) Client->>Agent: response to id=3 (outcome: cancelled) opt 4. Agent propagates cancellation to the terminal request Agent->>Client: $/cancel_request (requestId=2) end Note over Client,Agent: 5. Terminal request is cancelled in this example Client->>Agent: response to id=2 (error -32800 "Cancelled") Note over Client,Agent: 6. Agent completes prompt cancellation Agent->>Client: response to id=1 (stopReason: "cancelled") ``` ### What happens if a request completes before the cancellation is processed? If a request completes normally before the cancellation notification is processed, the implementation should: 1. Send the normal response (not a cancellation error) 2. Ignore the subsequent cancellation notification for that request ID This ensures clients always receive meaningful responses and prevents race conditions. ### How should implementations handle cascading cancellation? Implementations can propagate cancellation to nested activities and outstanding child requests, and clean up resources associated with cancelled work. For requests sent to the other party, they can send `$/cancel_request` using each child request's ID. This is explicit implementation behavior, not an automatic or mandatory cascade, and the receiving party may still complete a request normally. Each outstanding request still requires a response. Where a feature defines its own cancellation semantics, those semantics apply: for example, `session/cancel` requires the Client to answer pending `session/request_permission` requests with the `cancelled` outcome, regardless of whether the Agent sends `$/cancel_request`. See the protocol's [v1 prompt turn cancellation](/protocol/v1/prompt-turn#cancellation) and [v2 active session work cancellation](/protocol/v2/prompt-lifecycle#cancellation) rules for the Agent's cleanup and completion obligations. ## Revision history * 2026-06-29: Moved to Completed and stabilized request cancellation in the protocol artifacts. * 2026-06-24: Move to Preview stage * 2025-12-09: Mirror LSP behavior. * 2025-12-05: Updated with current implementation. * 2025-11-13: Initial version converted from PR #183 # Rust SDK based on SACP Source: https://agentclientprotocol.com/rfds/rust-sdk-v1 Author(s): [nikomatsakis](https://github.com/nikomatsakis) ## Elevator pitch > What are you proposing to change? Replace the current ACP Rust SDK with a new implementation based on SACP (Symposium ACP). The new SDK provides a component-based architecture with builder patterns, explicit message ordering guarantees, and first-class support for [Proxy Chains](./proxy-chains) and [MCP-over-ACP](./mcp-over-acp). ## Status quo > How do things work today and what problems does this cause? Why would we change things? The current `agent-client-protocol` crate has a straightforward design with trait-based callbacks for common ACP methods and well-typed requests and responses. It's convenient for simple purposes but quickly becomes awkward when attempting more complex designs. Two examples that we found pushed the limits of the design are the *conductor* (from the [proxy chains](./proxy-chains) RFD) and the [patchwork-rs](https://patchwork-lang.github.io/patchwork-rs/) project: The Conductor is an orchestrator that routes messages between proxies, agents, and MCP servers. It must adapt messages as they flow through the system and maintain the correct ordering. Patchwork is a programmatic interface for working with agents. It allows Rust programs to run prompts that provide custom tools (implemented using [MCP-over-ACP](./mcp-over-acp)) and messages: ```rust theme={null} let mut results = Vec::new(); let _: () = patchwork.think() .text("Process each item and record it using the `record` tool") .tool( "record", "Record a processed item", async |input: RecordInput, _cx| { results.push(input.item); Ok(RecordOutput { success: true }) }, acp::tool_fn_mut!(), ) .await?; // After the think block, `results` contains all recorded items println!("Recorded: {:?}", results); ``` ### Limitation: Handlers can't send messages The current SDK uses traits like `Agent` where handler methods receive only the request and return only the response: ```rust theme={null} #[async_trait] pub trait Agent { async fn prompt(&self, args: PromptRequest) -> Result; // ... } ``` There's no (easy) way to send messages back to the client from within a handler. If you want to send a `SessionNotification` while processing a prompt, you need to obtain an `AgentSideConnection` through some other means and coordinate access yourself. This is awkward for agents (which want to stream progress during prompt processing) and prohibitive for proxies (which need to forward messages to their successor while handling a request from their predecessor). **Goal:** Handlers should receive a context parameter that provides methods to send requests and notifications back through the connection. ### Limitation: Fixed set of handlers ACP is an extensible protocol where users can add their own method names beginning with `_`. The current SDK uses a trait which means that it cannot offer "first-class" support for user-defined requests/notifications. Instead, these are handled using extension methods (`ext_method`, `ext_notification`). These methods have no static typing and require the user to work with raw JSON. **Goal:** Allow SDK users to define their own request/notification types that are handled in the same fashion as built-in types. ### Limitation: Message handlers must be the same across all session The current API always executes the same handler code for a particular method (e.g., a session/update). If different handling is required for a particular session, that handler must maintain some kind of map from session-id to identify what handling is required, which is non-trivial bookkeeping that can become awkward. As an example of how complex this can get, consider the [elaborate message forwarding scheme](https://nikomatsakis.github.io/threadbare/agent.html#full-trace-nested-think) used by older versions of patchwork. **Goal:** Allow SDK users to add/remove "dynamic" handlers that are specific to a particular session or other part of the protocol. These handlers should be closures so they can capture state. ### Limitation: No ordering guarantees In the current SDK, every incoming request or notification results is handled in a freshly spawned task. This means that it is not possible to guarantee that requests or notifications are handled in the order they arrive. It is also not possible to be sure that a notification is fully handled before the response to another request; this makes it difficult to, for example, be sure that a `session/update` notification is handled before the turn is ended (which is sent as the response to the `prompt` request). This is essential for an application like patchwork, which wishes to fully capture the updates before returning. **Goal:** Handlers should block message processing to allow them to ensure that they fully process a message before other messages are processed. ### Limitation: Confusing naming and 1:1 assumption `AgentSideConnection` is ambiguous - does this represent the agent, or the connection *to* an agent? What's more, the SDK currently assumes that each connection has a single peer, but [proxies](./proxy-chains) may wish to send/receive messages from multiple peers (client or agent). This was a constant source of confusion in early versions of the conductor and frequently required the author to get out a pencil and paper and work things out very carefully. **Goal:** Use directional naming like `ClientToAgent` that makes relationships explicit: "I am the client, the remote peer is an agent." Enable multiple peers. ### Limitation: Awkward to connect components When building tests and other applications, it's convenient to be able to create a client and connect it directly to an agent, leaving the plumbing to the framework. The current SDK only accepts channels and byte-streams which creates unnecessary boilerplate. **Goal:** Provide a `Component` trait that abstracts over anything that can connect to an ACP transport, enabling uniform handling in orchestration scenarios. ### Challenge: Executor independence and starvation freedom This isn't a limitation of the current SDK per se, but a common pitfall in async Rust designs that we want to address. We want the SDK to be independent from specific executors (not tied to tokio) while still supporting richer patterns like spawning background tasks. One specific common issue with Rust async APIs is *starvation*, which can occur with stream-like APIs where it is important to keep awaiting the stream so that items make progress. For example, in a setup like this one, the "connection" is not being "awaited" while each message is handled: ```rust theme={null} // PROBLEMATIC: message handling starves while processing while let Some(message) = connection.next().await { process(message).await; // connection is quiescent during this await! } ``` With careful design, it is possible to avoid these hazards. The most common way is either to spawn tasks (which then ties one to a specific executor) or to use "interior iteration" style APIs like `for_each` or `run_until`: ```rust theme={null} // CORRECT: message handling continues concurrently connection.run_until(async |cx| { // The connection processes messages while this code runs let response = cx.send_request(request).block_task().await?; process(response).await }).await ``` **Goal:** Provide APIs that are starvation-free by design, making it difficult to accidentally block message processing. ## What we propose to do about it > What are you proposing to improve the situation? We propose to adopt the design and implementation from [`sacp`](https://github.com/symposium-dev/symposium-acp/) (developed as part of the [Symposium project](https://symposium.dev)) as the foundation for `agent-client-protocol` v1.0. The `sacp` crates will be imported into this repository and renamed: | Current | New name | | - | - | | `sacp` | `agent-client-protocol` (v1.0) | | `sacp-derive` | `agent-client-protocol-derive` | | `sacp-tokio` | `agent-client-protocol-tokio` | | `sacp-rmcp` | `agent-client-protocol-rmcp` | | `sacp-conductor` | `agent-client-protocol-conductor` | | `sacp-test` | `agent-client-protocol-test` | | `sacp-tee` | `agent-client-protocol-tee` | | `sacp-trace-viewer` | `agent-client-protocol-trace-viewer` | The `sacp` crates will then be deprecated in favor of the `agent-client-protocol` family. The new SDK addresses the limitations above through a builder-based API with explicit connection semantics. The following table summarizes the key API concepts and which goals they address: | API Concept | Goals Addressed | | - | - | | [Link types](#link-types-and-directional-naming) (`ClientToAgent`, `AgentToClient`) | Confusing naming, 1:1 assumption | | [`Component` trait + `connect_to`](#the-component-trait-and-connect_to) | Awkward to connect components | | [Connection context (`cx`)](#sending-messages) | Handlers can't send messages | | [`on_receive_*` handlers](#handling-messages) with closure types | Fixed set of handlers | | [`serve` / `run_until`](#running-connections-serve-and-run_until) | Executor independence, starvation freedom | | [Session builders + dynamic handlers](#session-builders-and-mcp-servers) | Handlers must be same across sessions | | [Ordering guarantees + `spawn`](#controlling-ordering) | No ordering guarantees | We have validated the design by implementing a number of use cases: * **sacp-conductor** (to be renamed **agent-client-protocol-conductor**) - implementation of the conductor from the [proxy chains](./proxy-chains) RFD * [Patchwork](https://patchwork-lang.github.io/patchwork-rs/) - programmatic agent orchestration * **elizacp** - agent implementing the classic ELIZA program * **agent-client-protocol-tee** - proxy that logs messages before forwarding * **yopo** ("You Only Prompt Once") - CLI tool for single prompts The [Deep dive](#deep-dive) section below walks through each concept in detail. ## Deep dive This section walks through the SDK concepts in detail, organized by what you're trying to do. ### Getting up and going #### Link types and directional naming The SDK is organized around *link types* that describe who you are and who you're talking to. The two most common examples are: * `ClientToAgent` - "I am a client, connecting to an agent" * `AgentToClient` - "I am an agent, serving a client" To build a connection, start with the link type and invoke the `builder` method. Builders use the typical "fluent" style: ```rust theme={null} // As a client connecting to an agent ClientToAgent::builder() .name("my-client") // optional, useful for tracing ``` ```rust theme={null} // As an agent serving clients AgentToClient::builder() .name("my-agent") // optional, useful for tracing ``` Most types in the SDK are parameterized by the link type. This helps document the intent of the connection and also determines default method handling when no event handler is registered. (Both `ClientToAgent` and `AgentToClient` generally error on unhandled messages, but proxies default to forwarding.) #### The `Component` trait and `connect_to` The `connect_to` method connects your builder to the other side. The argument can be anything that implements the `Component` trait, which abstracts over anything that can communicate via JSON-RPC: ```rust theme={null} // Connect to an agent over stdio ClientToAgent::builder() .connect_to(acp::stdio()) ``` The `AcpAgent` type allows connecting to an external ACP agent or agent extension: ```rust theme={null} // Connect to a specific agent by command ClientToAgent::builder() .connect_to(AcpAgent::from_str("some-command --acp")) // Connect to Zed's Claude Code integration ClientToAgent::builder() .connect_to(AcpAgent::zed_claude_code()) ``` For testing, you can connect builders directly to each other - no transport setup required: ```rust theme={null} ClientToAgent::builder() .connect_to(AgentToClient::builder()) ``` Or connect to a struct that implements `Component`: ```rust theme={null} impl Component for MyAgent { async fn serve(self, client: impl Component) -> Result<(), acp::Error> { AgentToClient::builder() .on_receive_request(/* ... */) .serve(client) .await } } // Connect client directly to agent - useful for testing ClientToAgent::builder() .connect_to(MyAgent::new()) ``` #### Running connections: `serve` and `run_until` The `connect_to` method returns a `JrConnection`, but that connection is inert until executed. There are two ways to run it. **`serve()`** runs until the connection is closed. This is for "reactive" components that respond to incoming messages: ```rust theme={null} AgentToClient::builder() .name("my-agent") .on_receive_request(/* ... */) .connect_to(transport)? .serve() .await ``` **`run_until()`** takes an async closure and runs your code concurrently with message handling. The closure receives a *connection context* (conventionally called `cx`) - this is how you interact with the connection, sending messages, spawning tasks, and adding dynamic handlers. When the closure returns, the connection closes: ```rust theme={null} ClientToAgent::builder() .name("my-client") .connect_to(transport)? .run_until(async |cx| { // Your code runs here while messages are handled in the background. // Use `cx` to send requests and notifications. let response = cx.send_request(InitializeRequest::new(ProtocolVersion::LATEST)) .block_task().await?; Ok(response) }) .await ``` The `run_until` pattern directly addresses starvation. Instead of exposing an async stream that users might accidentally block, `run_until` runs your code *concurrently* with message handling. The `cx` type (`JrConnectionCx`) follows the "handle" pattern: cloned values refer to the same connection. It's `'static` so it can be sent across threads or stored in structs. Handlers registered with `on_receive_*` also receive a `cx` parameter. ### Sending messages #### Sending notifications Use `cx.send_notification()` to send a notification. It returns a `Result` that is `Err` if the connection is broken: ```rust theme={null} cx.send_notification(StatusNotification::new("processing"))?; ``` #### Sending requests Use `cx.send_request()` to send a request. This returns a handle for managing the response: ```rust theme={null} let response_handle = cx.send_request(PromptRequest::new(session_id, messages)); ``` The handle is not the response itself - that may not have arrived yet. You have two options for getting it: **`on_response` / `on_ok_response`** registers a handler that runs when the response arrives: ```rust theme={null} cx.send_request(PromptRequest::new(session_id, messages)) .on_ok_response( async move |response: PromptResponse, cx| { println!("Agent finished: {:?}", response.stop_reason); Ok(()) }, acp::on_response!() )?; ``` **`block_task`** returns a future you can await: ```rust theme={null} let response: PromptResponse = cx.send_request(PromptRequest::new(session_id, messages)) .block_task() .await?; ``` The `block_task` approach is convenient but dangerous in handlers (methods that begin with `on_`). See [Controlling ordering](#controlling-ordering) for details. ### Controlling ordering #### Atomic handlers Handler methods (methods whose names begin with `on_`) execute in the order messages arrive. Each handler must complete before the next message is processed: ```rust theme={null} .on_receive_request(async |req: PromptRequest, request_cx, cx| { // No other messages will be processed while this runs cx.send_notification(StatusNotification::new("processing"))?; // The notification is guaranteed to be sent before the response request_cx.respond(PromptResponse::new(StopReason::EndTurn)) }, acp::on_receive_request!()) ``` #### `block_task` and deadlock Using `block_task` inside a handler creates a deadlock: the handler waits for a response, but responses can't be processed until the handler completes. ```rust theme={null} // WRONG - will deadlock .on_receive_request(async |req: PromptRequest, request_cx, cx| { let response = cx.send_request(SomeOtherRequest::new()) .block_task() // Deadlock! Handler blocks waiting for response .await?; // but responses can't be processed until handler returns request_cx.respond(/* ... */) }, acp::on_receive_request!()) ``` Use `on_response` instead, or spawn a task. #### Spawning tasks Use `cx.spawn` to run work concurrently with message handling: ```rust theme={null} .on_receive_request(async |request: PromptRequest, request_cx, cx| { cx.spawn(async move { // Safe to use block_task here - we're in a spawned task let response = cx.send_request(InitializeRequest::new(ProtocolVersion::LATEST)) .block_task() .await?; /* ... */ Ok(()) })?; // Handler returns immediately, spawned work continues request_cx.respond(/* ... */) }, acp::on_receive_request!()) ``` Spawned tasks are tracked in the `JrConnectionCx` and don't require runtime-specific spawning. ### Client sessions When a client sends a `NewSessionRequest`, agents typically need to set up session-specific state: handlers that only apply to this session, MCP servers with tools tailored to the workspace, or initialization logic that runs once the session is confirmed. #### Session builders The session builder API provides a fluent interface for configuring sessions. Start with `cx.build_session()` or `cx.build_session_from()` and chain configuration methods: ```rust theme={null} cx.build_session("/path/to/workspace") .with_mcp_server(my_mcp_server)? // Attach MCP servers (see below) // ... additional configuration ``` MCP servers provide tools that the agent can invoke. We'll show how to define them in the examples below. #### Running sessions with `run_until` The primary way to run a session is with `block_task().run_until()`. This pattern allows your closure to capture borrowed state from the surrounding scope - no `'static` requirement: ```rust theme={null} // Inside a run_until closure (not a handler) let workspace_path = Path::new("/my/workspace"); cx.build_session(workspace_path) .with_mcp_server( McpServer::builder("tools") .tool_fn("get_path", "Returns the path", async move |_: (), _| { // Can capture `workspace_path` by reference! Ok(workspace_path.display().to_string()) }, acp::tool_fn!()) .build() )? .block_task() .run_until(async |mut session| { session.send_prompt("What is the workspace path?")?; let response = session.read_to_string().await?; println!("{response}"); Ok(()) }) .await?; ``` The `run_until` closure receives an `ActiveSession` with methods for interacting with the agent: * **`send_prompt(text)`** - Send a prompt to the agent * **`read_to_string()`** - Read all updates until the turn ends, returning text content * **`read_update()`** - Read individual updates for fine-grained control For more complex MCP servers, you can use the standard rmcp API via the `agent-client-protocol-rmcp` crate: ```rust theme={null} use agent_client_protocol_rmcp::RmcpServer; cx.build_session(workspace_path) .with_mcp_server(RmcpServer::new(my_rmcp_service))? // ... ``` #### Non-blocking sessions with `on_session_start` When you need to start a session from inside an `on_receive_*` handler but can't block, use `on_session_start`. This spawns the session work and returns immediately: ```rust theme={null} .on_receive_request(async |req: NewSessionRequest, request_cx, cx| { cx.build_session_from(req) .with_mcp_server(my_mcp_server)? .on_session_start(async |mut session| { session.send_prompt("Hello")?; let response = session.read_to_string().await?; Ok(()) })?; // Handler returns immediately, session runs in background Ok(()) }, acp::on_receive_request!()) ``` Note that `on_session_start` requires `'static` - closures and MCP servers cannot borrow from the surrounding scope. Use owned data or `Arc` for shared state. #### `start_session` and proxy sessions For cases where you want to avoid the rightward drift of `run_until` but still need blocking behavior, `start_session` returns an `ActiveSession` handle directly: ```rust theme={null} let mut session = cx.build_session(workspace_path) .with_mcp_server(my_mcp_server)? .block_task() .start_session() .await?; session.send_prompt("Hello")?; let response = session.read_to_string().await?; ``` Like `on_session_start`, this requires `'static` for closures and MCP servers. For proxies that want to inject MCP servers but otherwise forward all messages, use `start_session_proxy`: ```rust theme={null} .on_receive_request(async |req: NewSessionRequest, request_cx, cx| { let session_id = cx.build_session_from(req) .with_mcp_server(injected_tools)? .block_task() .start_session_proxy(request_cx) .await?; // Session messages are automatically proxied between client and agent Ok(()) }, acp::on_receive_request!()) ``` ### Handling messages #### Notification handlers Register handlers using `on_receive_notification`. The closure's first argument type determines which notification type it handles: ```rust theme={null} AgentToClient::builder() .on_receive_notification( async |notif: SessionNotification, cx| { // ------------------- // Expected notification type println!("Session update: {:?}", notif.update); Ok(()) }, acp::on_receive_notification!(), // <-- Hacky macro argument required ) ``` Note the 'hacky macro argument'. This is required due to current limitations in async closures. It can be removed once [Return Type Notation](https://github.com/rust-lang/rfcs/pull/3654) is stabilized and [issue #149407](https://github.com/rust-lang/rust/issues/149407) is fixed. #### Request handlers Request handlers receive an additional `request_cx` parameter for sending the response: ```rust theme={null} .on_receive_request( async |req: PromptRequest, request_cx, cx| { // Process the request... cx.send_notification(StatusNotification::new("processing"))?; // Send the response request_cx.respond(PromptResponse::new(StopReason::EndTurn)) }, acp::on_receive_request!(), ) ``` The `request_cx` is `#[must_use]` - the compiler warns if you forget to send a response. It provides three methods: * **`respond(response)`** - Send a successful response * **`respond_with_error(error)`** - Send an error response * **`respond_with_result(result)`** - Send either, based on a `Result` The `request_cx` is `Send`, so you can move it to another task or thread if you need to respond asynchronously: ```rust theme={null} .on_receive_request( async |req: LongRunningRequest, request_cx, cx| { cx.spawn(async move { let result = do_expensive_work(&req).await; request_cx.respond_with_result(result) }); Ok(()) }, acp::on_receive_request!(), ) ``` ### Custom message types Define custom notifications and requests using derive macros: ```rust theme={null} #[derive(Debug, Serialize, Deserialize, JsonSchema, JrNotification)] #[notification(method = "_myapp/progress")] struct ProgressNotification { percent: u32, message: String, } #[derive(Debug, Serialize, Deserialize, JsonSchema, JrRequest)] #[request(method = "_myapp/compute", response = ComputeResponse)] struct ComputeRequest { input: String, } #[derive(Debug, Serialize, Deserialize, JsonSchema)] struct ComputeResponse { result: String, } ``` Custom types work exactly like built-in types - no special `ext_notification` path required: ```rust theme={null} ClientToAgent::builder() .on_receive_notification( async |notif: ProgressNotification, cx| { println!("Progress: {}% - {}", notif.percent, notif.message); Ok(()) }, acp::on_receive_notification!() ) ``` #### Generic message handlers Use `on_receive_message` with `MessageCx` to intercept any incoming message (request or notification) before typed handlers: ```rust theme={null} .on_receive_message( async |message: MessageCx, cx| { // Forward all messages to another thread for processing message_sender.send(message)?; Ok(()) }, acp::on_receive_message!(), ) ``` `MessageCx` is useful for forwarding, logging, or other scenarios where you need to intercept messages before typed dispatch. ### Message handling in depth #### Handler chains A *message handler* takes ownership of a message and either handles it or returns a (possibly modified) copy to be tried by the next handler. Handlers are chained together - each gets a chance to claim the message before it passes to the next. ```mermaid theme={null} flowchart TD MSG[Incoming Message] --> STATIC subgraph STATIC[Static Handlers] S1[Handler 1] --> S2[Handler 2] --> S3[Handler n...] end STATIC -->|not claimed| DYNAMIC subgraph DYNAMIC[Dynamic Handlers] D1[Session handlers, etc.] end DYNAMIC -->|not claimed| DEFAULT[Link Default Handler] DEFAULT -->|not claimed| UNHANDLED{Unhandled} UNHANDLED -->|retry: false| ERROR[Send error response] UNHANDLED -->|retry: true| QUEUE[Queue for retry] QUEUE -->|new handler added| DYNAMIC ``` **Static handlers** are registered at build time via `.on_receive_request()`, etc. They're tried in registration order. **Dynamic handlers** are added at runtime via `cx.add_dynamic_handler()`. They're useful for sub-protocols where groups of related messages are identified by some kind of ID. For example, session messages all share a `session_id` - a dynamic handler can be registered for each session to handle its messages. **Link default handler** provides fallback behavior based on the link type (e.g., proxies forward unhandled messages). #### Message handlers The `JrMessageHandler` trait defines how handlers work: ```rust theme={null} pub trait JrMessageHandler: Send { type Link: JrLink; async fn handle_message( &mut self, message: MessageCx, cx: JrConnectionCx, ) -> Result, Error>; } ``` The handler takes ownership of the message. If it handles the message, it returns `Handled::Yes`. If not, it returns ownership via `Handled::No { message, retry }` so the next handler can try: ```rust theme={null} pub enum Handled { Yes, No { message: T, retry: bool }, } ``` **The `retry` flag**: If any of the static or dynamic handlers returns `retry: true`, and no handler ultimately claims the message, it gets queued and offered to each new dynamic handler as it's added. This solves a race condition with sessions: messages for a session may arrive before the session's dynamic handler is registered. The default handlers for `ClientToAgent` and `AgentToClient` already set `retry: true` for session messages with unrecognized session IDs, so you typically don't need to handle this yourself. For convenience, handlers can return `Ok(())` which is equivalent to `Handled::Yes`. Handlers can also modify the message before passing it along: ```rust theme={null} .on_receive_request(async |mut req: EchoRequest, request_cx, cx| { req.text.push("modified".to_string()); Ok(Handled::No { message: (req, request_cx), retry: false, }) }, acp::on_receive_request!()) ``` #### Registering dynamic handlers Register dynamic handlers at runtime for session-specific or protocol-specific message handling: ```rust theme={null} let registration = cx.add_dynamic_handler(MySessionHandler::new(session_id))?; ``` When `registration` is dropped, the dynamic handler is removed. To keep it alive indefinitely, call `run_indefinitely()`: ```rust theme={null} registration.run_indefinitely(); ``` #### Default handling from link type Each link type defines default handling for unhandled messages. For example: * **`ClientToAgent`** - Errors on unhandled requests, ignores unhandled notifications * **`ProxyToConductor`** - Forwards unhandled messages to the next component You only need to register handlers for messages you want to intercept. #### MatchMessage for implementing handlers When implementing `JrMessageHandler` directly, `MatchMessage` provides ergonomic dispatch: ```rust theme={null} impl JrMessageHandler for MyHandler { type Link = AgentToClient; async fn handle_message( &mut self, message: MessageCx, cx: JrConnectionCx, ) -> Result, Error> { MatchMessage::new(message) .if_request(async |req: InitializeRequest, request_cx| { request_cx.respond(InitializeResponse::new(req.protocol_version)) }) .if_request(async |req: PromptRequest, request_cx| { request_cx.respond(PromptResponse::new(StopReason::EndTurn)) }) .if_notification(async |notif: SessionNotification| { log::info!("Session update: {:?}", notif); Ok(()) }) .await .done() } } ``` For proxies with multiple peers, `MatchMessageFrom` dispatches based on message source: ```rust theme={null} MatchMessageFrom::new(message, &cx) .if_request_from(Client, async |req: PromptRequest, request_cx| { // Handle requests from the client }) .if_notification_from(Agent, async |notif: SessionNotification| { // Handle notifications from the agent }) .await .done() ``` ### Error handling Errors in handlers tear down the connection. If a handler returns an `Err`, the connection closes and all pending operations fail. For request handlers, you can propagate error responses instead of tearing down the connection: ```rust theme={null} .on_receive_request(async |req: ComputeRequest, request_cx, cx| { match process(&req) { Ok(result) => request_cx.respond(ComputeResponse { result }), Err(e) => request_cx.respond_err(JsonRpcError::new( ErrorCode::InvalidParams, format!("Failed to process: {}", e), )), } }, acp::on_receive_request!()) ``` ### Writing proxies #### Multiple peers Simple link types like `ClientToAgent` have one remote peer. Proxy link types like `ProxyToConductor` have two: `Client` (predecessor) and `Agent` (successor). With multiple peers, you must explicitly name which peer you're communicating with: ```rust theme={null} ProxyToConductor::builder() .on_receive_notification_from( acp::Agent, // <-- Receive from the agent async |notif: SessionNotification, cx| { cx.send_notification_to(acp::Client, notif)?; // ----------- // Send to the client Ok(()) }, acp::on_receive_notification!(), ) ``` #### Default forwarding For proxies, the default handling is typically `Forward` - unhandled messages pass through to the next component. You only need to register handlers for messages you want to intercept or modify. #### Session builders for proxies Proxies can add session-scoped handlers: ```rust theme={null} cx.build_session_from(req) .on_receive_notification(async |notif: SessionNotification, cx| { // This handler only runs for this session log_notification(¬if); Ok(()) }, acp::on_receive_notification!()) .on_proxy_session_start(request_cx, async |_| Ok(())) ``` ### Advanced: Defining custom link types Link types define the relationship between peers. The SDK provides built-in types, but you can define your own: ```rust theme={null} use acp::link::{JrLink, LinkDirection}; pub struct MyCustomLink; impl JrLink for MyCustomLink { type ConnectsTo = OtherSideLink; fn direction() -> LinkDirection { LinkDirection::Outbound // We initiate the connection } fn default_request_handling() -> DefaultHandling { DefaultHandling::Error // Unknown requests return an error } fn default_notification_handling() -> DefaultHandling { DefaultHandling::Ignore // Unknown notifications are silently dropped } } ``` ## Shiny future > How will things play out once this feature exists? ### Unified Rust ACP experience The Rust ecosystem will have a single SDK for ACP development. Whether you're building a simple client, a proxy chain, or a programmatic orchestration framework like patchwork-rs, the same SDK handles all cases. ### Smooth transition from the current SDK The new SDK is more ergonomic than the current trait-based approach, so migration should be straightforward for most users. The builder pattern with context parameters (`cx`) replaces the `AgentSideConnection` pattern, and the directional naming (`ClientToAgent` vs `AgentSideConnection`) makes code clearer. We can provide migration guidance and potentially a thin compatibility layer for common patterns, but most users will find the new code simpler than the old. ### Potential crate reorganization Currently, `agent-client-protocol` contains both generic JSON-RPC machinery (builder patterns, message handling, connection management) and ACP-specific types (link types, schema integration). In the future, it might be valuable to split the generic JSON-RPC layer into its own crate. However, this is complicated by the trait implementations: the generic traits need to be implemented for ACP types currently defined in the schema crate. We'd need to carefully consider where type definitions live to avoid orphan rule issues. This reorganization isn't blocking for the initial adoption. ### Cross-language SDK alignment The design principles here - builder patterns, context parameters, directional naming, component abstractions - aren't Rust-specific. They also informed the 1.0 TypeScript SDK, which is available as [`@agentclientprotocol/sdk` v1.0.0](https://www.npmjs.com/package/@agentclientprotocol/sdk/v/1.0.0). This doesn't mean other SDKs should be ports of the Rust SDK. Each language has its own idioms. But the core ideas (explicit message ordering, composable components, context in callbacks) translate across languages. ### Foundation for protocol evolution The builder pattern and component model make it easier to evolve the ACP protocol. New methods can be added without breaking existing code. New component types (beyond client/agent/proxy) can be introduced by implementing the Component trait. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? ### Crate structure The new SDK is organized into several crates with clear responsibilities: * **`agent-client-protocol`** - Core SDK with builder patterns, link types, and component abstractions * **`agent-client-protocol-tokio`** - Tokio runtime integration (spawn, timers, I/O) * **`agent-client-protocol-rmcp`** - Bridge to the rmcp crate for MCP integration * **`agent-client-protocol-conductor`** - Reference conductor implementation * **`agent-client-protocol-derive`** - Derive macros for JSON-RPC traits * **`agent-client-protocol-test`** - Test utilities and mock implementations * **`agent-client-protocol-tee`** - Debugging proxy that logs all traffic * **`agent-client-protocol-trace-viewer`** - Interactive sequence diagram viewer for trace files ### Current status This RFD is completed. The SACP-based Rust SDK has been released as [`agent-client-protocol` v1.0.0](https://crates.io/crates/agent-client-protocol/1.0.0), with API documentation on [docs.rs](https://docs.rs/agent-client-protocol/1.0.0). The TypeScript SDK also reached 1.0 as [`@agentclientprotocol/sdk` v1.0.0](https://www.npmjs.com/package/@agentclientprotocol/sdk/v/1.0.0), validating that the SDK direction was not Rust-only. The implementation lives in [agentclientprotocol/rust-sdk](https://github.com/agentclientprotocol/rust-sdk). The original [`sacp`](https://github.com/symposium-dev/symposium-acp) crates remain historical upstream packages and powered: * The conductor (proxy chain orchestration) * patchwork-rs (programmatic agent orchestration) * Symposium (Rust development environment) ### Migration path The transition has been completed through the 1.0 SDK release: 1. **Import `sacp` crates** to `agentclientprotocol/rust-sdk` with the new `agent-client-protocol-*` naming 2. **Preview the upstreamed SDK** to collect feedback on the new builder-based API 3. **Release `agent-client-protocol` v1.0** as the stable Rust SDK 4. **Align other official SDKs** around the same design goals where language idioms allow, starting with the TypeScript SDK's 1.0 release Most users should find migration straightforward - the builder pattern is more ergonomic than the trait-based approach, so the new code is often simpler than the old. Follow-up migration guides, compatibility helpers, or `sacp` deprecation notices can be handled as normal SDK maintenance outside this RFD. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### What alternative approaches did you consider? We first attempted to build on the existing SDK but due to the limitations decided to try an alternative approach. ### What about other language SDKs? We would like to try and adapt these ideas to other languages. It would be good if the SDKs for all languages took the same general approach. Most of the concerns in this document are not Rust-specific, though as often happens, the limitations become more annoying in Rust because of the limits imposed by the ownership system. ### How does this relate to the Proxy Chains and MCP-over-ACP RFDs? This expanded SDK design is motivated by working through the use cases enabled by [proxy chains](./proxy-chains) and [MCP-over-ACP](./mcp-over-acp). ### How well-tested is this design? The design has been used for a wide range of projects but the majority were written by the SDK author, though Amazon's kiro-cli team and the Goose client adopted sacp for their use case with minimal difficulty. Before we finalize the design, it would be good to have more adopters to help ensure that it meets all common needs. ### Can I derive `JrRequest`/`JrNotification` on enums? Not currently. The derive macros only support structs with a single method name. For enums that group related messages (e.g., all session-related requests), you would need to implement the traits manually. This is a potential future enhancement - enum derives could dispatch to different methods per variant, which would be useful for `MessageCx` typed handlers. For now, use the untyped `MessageCx` with `MatchMessage` for this pattern. ### What changes are needed before stabilizing? The Rust SDK has been stabilized as `agent-client-protocol` v1.0.0, so no RFD-blocking work remains. Future API polish, compatibility helpers, and MCP-over-ACP refinements should be tracked as normal SDK follow-up work. ## Revision history * 2026-06-25: Moved to Completed after the Rust SDK and TypeScript SDK reached v1.0.0. * 2026-05-12: Moved to Preview after the initial crate import was upstreamed to agentclientprotocol/rust-sdk. * Initial draft based on working implementation in symposium-acp repository. # Session Archive and Unarchive Source: https://agentclientprotocol.com/rfds/session-archive * Author(s): [@Rizzen](https://github.com/Rizzen), [@xtmq](https://github.com/xtmq) * Champion: [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? Standardize reversible session archiving in both ACP v1 and v2: Clients can hide conversations from default history, discover archived sessions, and restore them with the same ID and saved history. ## Status quo > How do things work today and what problems does this cause? Why would we change things? [`session/delete`](/protocol/v1/session-delete) removes sessions from history but permits permanent deletion. [`session/close`](/protocol/v1/session-setup#closing-active-sessions) releases execution resources. Neither guarantees reversible hiding, and [`session/list`](/protocol/v1/session-list) cannot explicitly request archived sessions. ## What we propose to do about it > What are you proposing to improve the situation? ### Methods `session/archive` hides a session from default history: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "session/archive", "params": { "sessionId": "sess_abc123" } } ``` `session/unarchive` restores it: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "session/unarchive", "params": { "sessionId": "sess_abc123" } } ``` On success, both return an empty result: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": {} } ``` The new models are: | Models | Fields | | - | - | | `ArchiveSessionRequest`, `UnarchiveSessionRequest` | Required, non-null `sessionId: SessionId`; optional `_meta`. | | `ArchiveSessionResponse`, `UnarchiveSessionResponse` | Optional `_meta`. | | `SessionArchiveCapabilities` | Optional `_meta`. | In each model, `_meta` is an object with arbitrary values. Omission and `null` are equivalent. ### Capabilities Agents advertise one shared `archive` capability: * **v1:** `agentCapabilities.sessionCapabilities.archive`. * **v2 draft:** `capabilities.session.archive`. `{}` means the Agent **MUST** support both methods, the `archived` list filter, and archive-state reporting; omission or `null` means unsupported. Clients **MUST** check support before using either method or the list filter. In v1, Agents that advertise `sessionCapabilities.archive` **MUST** also advertise `sessionCapabilities.list`. v2 already requires listing for Agents supporting sessions. Example v1 initialization response: ```json theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "sessionCapabilities": { "list": {}, "delete": {}, "archive": {} } } } } ``` ### Listing and state Extend `session/list` with an optional `archived` filter: | Value | Sessions returned | | - | - | | Omitted, `null`, or `exclude` | Unarchived only. | | `include` | Unarchived and archived. | | `only` | Archived only. | Agents that advertise `archive` **MUST** support all three values. The filter is an open string enum: values beginning with `_` are reserved for implementation-specific extensions, and other unknown values for future ACP variants. An Agent rejects any value it does not support with `Invalid params` (`-32602`) rather than falling back to the default, so a Client never silently receives the wrong view. The filter combines with `cwd` and applies before pagination. Clients keep the same `cwd` and `archived` values when following `nextCursor`; changing either starts a new pagination sequence. List only archived sessions, e.g. for an "Archived" view: ```json theme={null} { "jsonrpc": "2.0", "id": 3, "method": "session/list", "params": { "cwd": "/home/user/project", "archived": "only" } } ``` Include archived sessions alongside unarchived sessions: ```json theme={null} { "jsonrpc": "2.0", "id": 4, "method": "session/list", "params": { "cwd": "/home/user/project", "archived": "include" } } ``` ```json theme={null} { "jsonrpc": "2.0", "id": 4, "result": { "sessions": [ { "sessionId": "sess_abc123", "cwd": "/home/user/project", "title": "Implement session archive support", "archived": true }, { "sessionId": "sess_def456", "cwd": "/home/user/project", "title": "Update session documentation", "archived": false } ] } } ``` Add an optional boolean `archived` to `SessionInfo`. Omission and `null` are equivalent and convey no archive-state guarantee. Agents that advertise `archive` **MUST** include a boolean value on every listed session. ### Semantics * **Preservation:** Both operations preserve the ID and saved conversation. Archive state persists with session history across connections and restarts; ordinary retention policies still apply. * **Archiving closes active sessions:** If the session is active, `session/archive` **MUST** cancel any ongoing work and free the session's resources as if [`session/close`](/protocol/v1/session-setup#closing-active-sessions) had been called, then archive it. This does not require the `close` capability. `session/unarchive` never loads or resumes a session. * **Session status:** Because archiving closes the session, an Agent that supports [`session/status`](/rfds/session-status) reports an archived session as `saved`. * **Loading archived sessions:** Closing, loading, or resuming does not change archive state. Agents **MAY** reject `session/load` or `session/resume` for an archived session. Clients that want to continue an archived session **SHOULD** call `session/unarchive` first; they already know the state from `SessionInfo.archived`. * **Idempotency:** Archiving an archived session, or unarchiving an unarchived session, succeeds. Neither method requires the session to be active on the current connection. * **Unknown sessions:** Unknown, deleted, or expired sessions return `Resource not found` (`-32002`). This differs from `session/delete`, which succeeds silently for unknown sessions because its end state ("not listed") already holds. Neither archive state can hold for a session that doesn't exist, so silently succeeding would hide stale or mistyped IDs. * **Consistency:** Success commits the change; subsequent list requests reflect it unless another operation intervenes. * **Deletion:** Deleted sessions are excluded from every `archived` filter value, and unarchiving does not restore a deleted session. Agents that advertise `archive` **MUST NOT** implement `session/delete` as an archive that later shows up in archived listings. * **Subagent sessions:** Archiving applies to the given session. Whether archiving a parent also archives its [subagent sessions](/rfds/subagents) is implementation-defined; some Agents archive the whole tree. ## Shiny future > How will things will play out once this feature exists? A user archives a conversation in one Client, finds it in another Client's archived history, and restores it for continued work. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? The implementation **MUST** cover both ACP v1 and v2: `session/archive`, `session/unarchive`, all new models with `_meta`, the shared `archive` capability, the `session/list` filter, and archive-state reporting. Implement these behind `unstable_session_archive`, regenerate both versions' schemas, and update conversions, SDKs, and docs. Validate restoration, retries, persistence, pagination, active sessions, and deletion compatibility in both protocol versions before preview. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why separate methods? They express opposite state transitions under one shared capability. A boolean setter is possible, but a general metadata-editing API exceeds this request. Extending deletion cannot guarantee recovery when Agents may permanently remove data. ### Why does archiving close an active session? Several Agents with native archiving (Codex, Qwen Code, Kimi Code) stop or unload a session when archiving it, and both reference adapters close the session first. Requiring archive to leave execution untouched would force those Agents to reject the request and every Client to handle a "close, then archive" retry. Reusing `session/close` semantics gives Clients one predictable outcome. ### Why a three-value list filter instead of a boolean? Clients usually show archived sessions in their own view, which needs archived-only results; a boolean "include archived" would force Clients to page through every session and filter locally. Native stores differ: Codex lists one side at a time, while others list both together, so Agents need adapter work for at least one of the values either way. A boolean named `archived` would also read as "archived only". ### What alternative approaches did you consider, and why did you settle on this one? * **Extend `session/delete` with soft-delete semantics:** Deletion may be permanent and its behavior is implementation-defined, so it cannot guarantee recovery. * **A single `session/setArchived` method with a boolean:** Equivalent in power, but two methods match the rest of the session lifecycle methods and keep each request's intent obvious. * **A general session-metadata editing method:** Larger in scope than this proposal needs. ### Why is there no `archived` field on `session_info_update`? The Client that archives a session learns the result from the response, and `session/unarchive` never loads a session, so no Client is attached to hear about it. The only remaining audience is other Clients attached to a session when it is archived, and ACP doesn't define multiple Clients sharing a session yet (see the [Multi-Client Session Attach RFD](https://github.com/agentclientprotocol/agent-client-protocol/pull/533)). `session/list` is the source of truth. The field can be added later without breaking anything once multi-client attach exists. ### Why is there no separate capability for listing archived sessions? An Agent that can't archive sessions has no archived sessions of its own, so a list-only capability would only serve Agents that mirror another tool's archive. That can be added later as a sub-capability of `archive` without breaking existing implementations. ## Revision history * 2026-10-30: Make the `archived` list filter an open enum, drop `archived` from `session_info_update`, resolve the list-only capability question, and note the interaction with `session/status`. * 2026-10-28: Archiving closes active sessions; three-value `archived` list filter; clarified null handling, errors, deletion, and subagent sessions; removed the `updatedAt` requirement. * 2026-09-14: Initial proposal. # Closing active sessions Source: https://agentclientprotocol.com/rfds/session-close Author(s): [@SteffenDE](https://github.com/SteffenDE) ## Elevator pitch > What are you proposing to change? We propose adding the ability to close active sessions. This allows the agent to free up any memory and threads/subprocesses associated with that session. ## Status quo > How do things work today and what problems does this cause? Why would we change things? Today, if you start a session, it will remain active until the ACP process is terminated. This means that if the agent implements sessions as separate processes, active users with many sessions can end up with a lot of processes unnecessarily using up system memory. Even if the agent does not spawn separate processes, memory used by large tool results or similar could still accumulate over time. The only way to free up that memory is to terminate the whole ACP process, which will stop all sessions and - if the agent does not support resuming sessions (load / resume / fork) - lead to a bad user experience. ## What we propose to do about it > What are you proposing to improve the situation? Add a new `session/close` method. If supported, the agent **must** cancel any ongoing work related to the session (treat it as if `session/cancel` was called) and then free up any resources associated with the session. ## Shiny future > How will things will play out once this feature exists? Clients can track what sessions are actively used by a user and automatically close old sessions. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? We propose to add a new `"session/close"` method. Agents must declare this option is available by returning `sessionCapabilities: { close: {} }` in their capabilities. The object is reserved to declare future capabilities. Then the client would be able to close a specific session with: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "session/close", "params": { "sessionId": "sess_789xyz" } } ``` Agents might reply with an error if the session is not active or does not exist. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? None so far. ### What alternative approaches did you consider, and why did you settle on this one? It could be an agent specific custom method, since we mainly ran into problems with Claude Code, but even for agents that don't spawn full subprocesses for sessions, cleaning up unneeded sessions still seems like a good idea. ## Revision history * 2026-04-23: RFD marked as Completed; `session/close` is stabilized * 2026-04-14: Move to preview and update capability docs to `sessionCapabilities.close` * 2026-03-09: Rename from session/stop to session/close * 2026-02-24: Initial draft # Session Compaction Source: https://agentclientprotocol.com/rfds/session-compaction Author(s): [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? Add ID-addressed `compaction_update` and `compaction_summary_chunk` session updates to ACP v1 and v2. Agents can report when context compaction starts, update that same timeline entity when it finishes, and optionally stream or materialize the user-displayable summary retained by the compaction. ## Status quo > How do things work today and what problems does this cause? Why would we change things? ACP can report current context-window utilization through `usage_update`, but it cannot report that an Agent is compacting its context or preserve the resulting boundary in session history. Agents currently have to omit compaction, use an implementation-specific update, or describe it through an ordinary agent message. An agent message is the wrong semantic shape. Agent runtimes also expose different amounts of compaction information. Some provide a stable lifecycle item and a user-displayable summary, while others expose only ordered start and completion signals, an encrypted result, or a summary through an optional hook. ## What we propose to do about it > What are you proposing to improve the situation? Add `compaction_update` and `compaction_summary_chunk` to `SessionUpdate` in ACP v1 and v2. The first notification for an ID creates a compaction entity at that position in the session timeline. Later updates and summary chunks with the same ID update that entity in place. A single `compaction_update` with `status: "completed"` is sufficient; reporting progress is optional. Summary content is also optional. It may be sent all at once in the `summary` field or streamed using `compaction_summary_chunk`. For example, an Agent can report that compaction has started: ```json theme={null} { "sessionUpdate": "compaction_update", "compactionId": "cmp_001", "status": "in_progress" } ``` If the summary is available incrementally, the Agent can stream content: ```json theme={null} { "sessionUpdate": "compaction_summary_chunk", "compactionId": "cmp_001", "content": { "type": "text", "text": "## Retained context\n\n" } } ``` The Agent finishes the same entity by reusing its ID. A non-streaming Agent can include the complete summary, while a streaming Agent can use this field as an authoritative replacement of content received so far: ```json theme={null} { "sessionUpdate": "compaction_update", "compactionId": "cmp_001", "status": "completed", "summary": [ { "type": "text", "text": "## Retained context\n\nThe user is updating the ACP schema..." } ] } ``` ### Identity and lifecycle `compactionId` is an opaque, Agent-owned string. It is required, non-null, unique within the session, and never reused for another compaction. Clients initialize a first-seen compaction ID with status `in_progress` and unset optional fields, then apply the notification. `status` is required and non-null on every update. Its initial values are: * `in_progress` - Compaction has started and has not finished. * `completed` - Compaction finished successfully. * `failed` - Compaction finished unsuccessfully. * `cancelled` - Compaction was cancelled before it finished. `CompactionStatus` is open in both protocol versions from its introduction and follows the [v2 enum-extension rules](/rfds/v2/enum-variant-extension). Values beginning with `_` are reserved for implementation-specific extensions, while other unknown values are reserved for future ACP statuses. Clients preserve an unknown string and present an opaque generic state without inferring lifecycle or control behavior from it. The normal transition is `in_progress` to a terminal status. The Agent **MUST** report a terminal status when a reported compaction ends. The first notification fixes the entity's timeline position in notification receive order: it follows previously received timeline content and precedes content first received later. Later patches or chunks for an ID-addressed entity update it in place; they do not move or split it around the compaction. A Client may render an in-progress indicator and replace it with a completed, failed, or cancelled presentation when the corresponding status arrives. ### Optional fields and patch semantics The update has three optional, nullable patch fields: * `summary` is an array of `ContentBlock` values containing the unencrypted, user-displayable summary content produced or retained by a compaction. It should faithfully represent the retained summary while excluding internal prompt framing or instructions. Text blocks may contain Markdown. It is not generic content such as `Compaction completed`. * `error` is a human-readable error description. * `_meta` is reserved for extensibility and follows ACP's existing `_meta` rules. For each patch field, omission leaves the stored value unchanged, `null` clears it, and a concrete value replaces it. In v2, a concrete `_meta` object instead patches the stored metadata by top-level key, as defined by [v2 Metadata Patches](/rfds/v2/meta-patches). On a first-seen ID, omission and `null` both start with no value. For `summary`, both `null` and `[]` clear the current content. ### Streaming summary content `compaction_summary_chunk` contains a required, non-null `compactionId` and one required, non-null `ContentBlock` in `content`. Its optional nullable `_meta`, when present, is scoped to that chunk; omission and `null` both mean that the Agent supplied no chunk metadata. Clients apply `compaction_update` and `compaction_summary_chunk` notifications in receive order for each `compactionId`. A chunk appends its `content` block to the current summary. A later `compaction_update` with a concrete `summary` array replaces all content accumulated from earlier updates and chunks; subsequent chunks append to that replacement. `summary: []` or `summary: null` clears the accumulated content. An update may omit `summary` to retain the content accumulated from chunks, or include the complete summary as an authoritative replacement. Agents should omit `summary` when no unencrypted, user-displayable summary is available or when exposing it could reveal context that was not otherwise user-visible. ### History replay History replay uses the same update, chunk, and patch semantics as live delivery. Replay does not implicitly reset omitted fields. Agents use replacement or clearing summary patches as needed to avoid duplicating content the Client already holds. The v1 capability gate applies to replay as well as live delivery. ### Version-specific capability For v1, add an optional `compaction` object to `ClientSessionCapabilities`: ```json theme={null} { "clientCapabilities": { "session": { "compaction": {} } } } ``` The object appears at `clientCapabilities.session.compaction` in the v1 `initialize` request. Omitting `session`, setting `session` to `null`, omitting `compaction`, or setting `compaction` to `null` all mean the Client does not advertise support. Supplying `{}` for `compaction` means the Client implements the ID, update, chunk, placement, and replay semantics in this RFD. Agents must only send `compaction_update` or `compaction_summary_chunk` to a v1 Client that advertises this capability. V2 does not add or require a capability. ## Shiny future > How will things play out once this feature exists? Users can see context compaction begin and finish at the point where it occurred. Clients can keep one stable timeline row, optionally make the retained summary expandable, and accurately reconstruct historical compaction boundaries after reconnecting. Agents no longer need to turn an internal lifecycle event into conversational text. Implementations with rich provider data can expose the summary, while implementations with only lifecycle signals remain fully conformant. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? ### Implemented The initial Preview protocol implementation landed in [PR #2002](https://github.com/agentclientprotocol/agent-client-protocol/pull/2002): * Both protocol versions define `CompactionId`, `CompactionStatus`, `CompactionUpdate`, and `CompactionSummaryChunk`, with `compaction_update` and `compaction_summary_chunk` variants in their `SessionUpdate` unions. * V1 defines the optional `ClientSessionCapabilities.compaction` capability; v2 does not require a capability. * Both versions preserve unknown status strings and distinguish omitted, `null`, and concrete patch values. ### Stabilization preparation The completion change includes compaction in stable and draft schemas and protocol guides. See the [v1 guide](/protocol/v1/prompt-turn#session-compaction) and [v2 guide](/protocol/v2/prompt-lifecycle#session-compaction). It makes compaction available unconditionally and removes the `unstable_session_compaction` Cargo feature. Existing consumers must remove that feature from their dependency configuration. The wire shapes and v1 capability requirement are unchanged from Preview. Protocol v2 as a whole remains opt-in through `unstable_protocol_v2`; completing this RFD does not stabilize protocol v2. The schema crate [does not provide cross-version conversion](/rfds/v2/overview). SDKs supporting both versions should use explicit versioned implementations or purpose-specific runtime adapters rather than schema-level conversion helpers. ### Preview validation Agent and Client implementers should add or update examples and integration tests to exercise: * V1 capability enforcement for both live updates and replay, including Clients that omit the capability or send `null`. * Lifecycle transitions to `completed`, `failed`, and `cancelled`, including runtimes that only expose completed compactions. * Summary chunk ordering and first-seen ID initialization, authoritative replacement and clearing, completion with an omitted summary, chunks after terminal updates, and failure or cancellation after partial output. * History replay without duplicating accumulated summary content after reconnecting, including v1 message chunks without IDs on either side of a compaction boundary. * Unknown statuses and v2 updates, and safe omission of summaries that cannot be exposed to the user. Cross-repository Agent/Client integration tests and interoperability results are not established by this schema repository. The completion review should include implementer feedback on these behaviors; core-team approval remains the final stabilization decision. ### External implementation evidence The Claude Agent adapter provides public v1 Agent-side implementation evidence: * [PR #1134](https://github.com/agentclientprotocol/claude-agent-acp/pull/1134) added experimental compaction updates and summary streaming, released in `0.78.0`. * [PR #1154](https://github.com/agentclientprotocol/claude-agent-acp/pull/1154) added regression coverage and terminal cleanup for interrupted compactions, released in `0.80.0`. It addressed cancellations, provider failures, and other interruptions that could otherwise leave an `in_progress` entity unfinished. This is evidence that an Agent exercised and refined the lifecycle contract, not proof of Client presentation, history replay, or cross-implementation interoperability. Client-side validation remains a completion-review item. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why is the capability required in v1? Agents currently fall back to agent text because compaction can take a while and it is useful to tell the user what is happening. The capability lets an Agent send `compaction_update` when the Client supports it while preserving that fallback for older v1 Clients. ### Does `summary` contain the Agent's complete replacement history? No. Some runtimes retain compaction output as multiple role-bearing model history items, potentially including developer instructions, retained user messages, or encrypted provider data. `summary` contains only the user-displayable projection of that result as content blocks, without internal framing or hidden instructions. It is optional because some runtimes expose no safe user-displayable projection. ### Why is `summary` a `ContentBlock[]`? ACP Clients already process `ContentBlock` values in Agent output. Reusing that shape preserves multiple or non-text blocks when a runtime exposes them without creating another content representation. A text-only runtime sends one text block, and a runtime with no user-displayable summary omits the field. The array is still a summary artifact, not a sequence of ACP messages and not a lossless encoding of the Agent's internal replacement history. ### Why can `summary` be streamed? Some runtimes produce summary text incrementally, and ACP v2 already composes append-only content chunks with authoritative replacement snapshots for messages and tool calls. Compaction follows the same pattern. Runtimes that only expose a completed result send one `compaction_update`. ### Should the Client collapse earlier messages after compaction? That is a local presentation choice and is not implied by this update. The Client may visually mark or group the earlier portion of the transcript, but it must retain whatever history the surrounding session and replay contracts require. ### How does this interact with `usage_update`? They report different facts. `compaction_update` records a lifecycle boundary and optional retained summary. `usage_update` reports current context window utilization and cost. An Agent will commonly send a lower usage value after compaction, but neither update substitutes for the other. ### What alternative approaches did you consider, and why did you settle on this one? **Agent messages** - They are widely renderable, but they turn protocol activity into conversation content and cannot replace one stable entity in place. **Separate start and finish events** - Simple to emit, but force Clients to correlate events heuristically rather than updating one ID-addressed entity. ## Revision history * 2026-07-22: Initial draft. * 2026-09-23: Moved to Preview; documented the implemented protocol support and remaining integration validation. * 2026-10-06: Prepared completion and stabilization; included compaction in stable artifacts, removed the unstable Cargo feature, expanded schema regression coverage, and clarified receive-order timeline placement and summary patch semantics independent of compaction status. * 2026-10-13: In v2, a concrete `_meta` object patches stored metadata by key, per [v2 Metadata Patches](/rfds/v2/meta-patches). v1 still replaces the whole object. # Session Config Options Source: https://agentclientprotocol.com/rfds/session-config-options Author(s): [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? Allow Agents to provide an arbitrary list of configuration selectors for a given session. Rather than only supporting modes or models, we can allow each Agent to more flexibly specify which configurations to allow the Client to offer the user. ## Status quo > How do things work today and what problems does this cause? Why would we change things? Currently, we allow Agents to [specify a list of modes](https://agentclientprotocol.com/protocol/v1/session-modes) they can run in. The state of the currently selected item is allowed to be modified by both the [Client](https://agentclientprotocol.com/protocol/v1/session-modes#from-the-client) and the [Agent](https://agentclientprotocol.com/protocol/v1/session-modes#from-the-agent). The obvious next selector was a [model selector](https://github.com/agentclientprotocol/agent-client-protocol/pull/182). However, when implementing this, it became clear that even for our current agents, it is not just as simple as "which model do you want?", but also which variant of a given model in terms of thinking parameters that might be better to express as yet another selector. Adding more hard-coded selector options would potentially lead the protocol to need to support many optional ones, or implementors would need to try to find the best existing selector to hack an option into if there wasn't an obvious fit. And if, a few months from now, no agents support something like a mode or reasoning selector, the protocol is left with leftover methods no one really uses, cluttering the interface. Since this space is moving fast, we ideally would find a more flexible option with enough constraints to allow Clients and Agents to both reason about the options provided. ## What we propose to do about it > What are you proposing to improve the situation? Instead, we can allow Agents to provide configuration options in the `session/new` response that not only provide a list of options, but also a `key` of some kind that is a unique identifier for that selector. Additionally, we can optionally allow an Agent to mark each option with a semantic category so that Clients can reliably distinguish broadly common option types (e.g. model selector vs session mode selector vs thought/reasoning level), without needing to infer meaning from the option `id` or `name`. This is intended for UX only (e.g. keyboard shortcuts, icons, preferred placement), and MUST NOT be required for correctness. When the Client receives or sends an update to this selector, it would require both the selector key and the key for the new value. To start, we could continue offering single-value selectors (dropdowns), but allow for the Agent to decide what those are for. ## Shiny future > How will things will play out once this feature exists? The Agent provides a list of available configuration options. The Agent cannot rely on the Client to set or even display these options, as it may not support it. So an Agent MUST always have a default configuration value for every option it provides, and MUST be able to run a turn without these configuration options being set. The Client can render the options provided, send updated values to the Agent, and also display any changes the Agent made during the course of it's execution (for example, if it changes modes or models because of fallbacks or a change in strategy, so that the user can always see the current state). Since we are moving to a world in which there are multiple configuration options, some of which may depend on each other, the Agent MUST provide the complete set of configuration options and their current values whenever a change is made. We would tradeoff some extra data being sent to the Client in order to help minimize the amount of state required to be managed by the Client. The Client would submit a new value, and receive back the full state of all configuration options that it can then replace it's current state with and render. So if changing a model means there are no thinking options, or a new option becomes available, or another value needs to change because the values of an option are different, the Agent will reflect this in its response by providing the entire new state (or an error if it is somehow an invalid selection). ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? To start, we can implement this based on the [Session Modes](https://agentclientprotocol.com/protocol/v1/session-modes) api. Something like an `InitializeResponse` that looks like: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "sessionId": "sess_abc123def456", "configOptions": [ { "id": "mode", // this is the unique `key` for communication about which option is being used "name": "Session Mode", // Human-readable label for the option "description": "Optional description for the Client to display to the user." "category": "mode", "type": "select", "currentValue": "ask", "options": [ { "value": "ask", "name": "Ask", "description": "Request permission before making any changes" }, { "value": "code", "name": "Code", "description": "Write and modify code with full tool access" } ] }, { "id": "models", "name": "Model", "category": "model", "type": "select", "currentValue": "ask", "options": [ { "value": "model-1", "name": "Model 1", "description": "The fastest model" }, { "value": "model-2", "name": "Model 2", "description": "The most powerful model" } ] } ] } } ``` ### Option category (optional) Each top-level config option MAY include an optional `category` field. This is intended to help Clients distinguish broadly common selectors and provide a consistent UX (for example, attaching keyboard shortcuts to the first option of a given category). In addition to `category`, Clients SHOULD use the ordering of the `configOptions` array as provided by the Agent as the primary way to establish priority and resolve ties. For example, if multiple options share the same `category`, a Client can prefer the first matching option in the list when assigning keyboard shortcuts or deciding which options to surface most prominently. `category` is semantic metadata and MUST NOT be required for correctness. Clients MUST handle missing or unknown categories gracefully. Category names beginning with `_` are free for custom use. Category names that do not begin with `_` are reserved for the ACP spec. Proposed enum: * `mode` - Session mode selector * `model` - Model selector * `thought_level` - Thought/reasoning level selector * Any string beginning with `_` - Custom category (e.g., `_my_custom_category`) When we introduce this, we could also allow for grouped options, in case there are logical sub-headers and groupings for the options in an individual selector. ```json theme={null} { "id": "models", "name": "Model", "currentValue": "ask", "type": "select", "options": [ { "group": "Provider A", "options": [ { "value": "model-1", "name": "Model 1", "description": "The fastest model" } ] }, { "group": "Provider B", "options": [ { "value": "model-2", "name": "Model 2", "description": "The most powerful model" } ] } ] } ``` We use a list of objects for all of these, to ensure consistent ordering of both the config options and the possible values across languages that may or may not preserve ordering. For grouping options, it needs to be explored whether or not grouped and ungrouped options can be interspersed, or if we need to restrict to one mode or the other (likely the latter). For updating the value from the client and agent, it would follow the same pattern as [session modes](https://agentclientprotocol.com/protocol/v1/session-modes#from-the-client) but have an additional key. ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "session/set_config_option", "params": { "sessionId": "sess_abc123def456", "configId": "mode", "value": "code" } } ``` And the response to this request would return the full list of config options with current values. ```json theme={null} { "jsonrpc": "2.0", "id": 2, "result": { "configOptions": [ { "id": "mode", "name": "Session Mode", "type": "select", "currentValue": "ask", "options": [..] }, { "id": "models", "name": "Model", "type": "select", "currentValue": "ask", "options": [..] } ] } } ``` The notification would return the full list of config options with current values as well. ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "config_option_update", "configOptions": [ { "id": "mode", "name": "Session Mode", "type": "select", "currentValue": "ask", "options": [..] }, { "id": "models", "name": "Model", "type": "select", "currentValue": "ask", "options": [..] } ] } } } ``` We would also likely move session modes to be `@deprecated` in favor of this approach. Until it is removed, we may want Agents to support both fields, and then the Client, if it uses the new config options, should only use the config options supplied and not the `modes` field to avoid duplication. The config options would also take a `type` field to specify different forms of input for the Client to display. If a client receives an option it doesn't recognize, it should ignore it. Since the Agent is required to have a default value, it can gracefully degrade and ignore the option and the Agent should handle it regardless. The Client should also treat the list of options as prioritized by the Agent. So, if for some reason the Agent provides more options than the Client can reasonably display, the Client should show as many as possible, starting at the beginning of the list. We will start with just supporting `select` for now, and expand to other types as needed. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### What alternative approaches did you consider, and why did you settle on this one? As noted, the Zed team already looked into and implemented experimental support for a model selector. However, this has already diverged from how the Codex CLI is modeling their model selector as of last week, so it seems reasonable to, as per a core design principle of the protocol, only limit the Agent implementations where necessary for the Client to render a faithful UX. Maximizing flexibility for the Agent as they iterate on the best way to model new paradigms seems key here, and it is unclear whether the Client benefits from knowing which type of selector this is. We originally discussed internally having a design closer to this proposal, however walked it back thinking it would be helpful for the Client to know what was being selected. However, as we've now dealt with multiple Agent implementations, it is unclear if this has actually helped the Client, and allowing for more flexibility seems desirable. ### What about connection-level configuration options? This RFD is only concerned with session-level configuration, for which it seems reasonable to require that the Agent can select a default value at all times and not require input from the client before continuing. There seems to be another type of configuration option that is needed when first setting up an Agent (i.e. provider options, plugins, etc.) that are more persistent and may be required by an Agent prior to being able to create a session. These would need to be tackled somewhere closer to the initialization phase, or elsewhere and are out of scope for this RFD. ### What about multi-value selectors? or checkboxes? Or *insert favorite input option here*? This is a question we should discuss of how much complexity we want to introduce for the first version, and how we want to express this to via Client capabilities to allow for more option types in the future. ## Revision history * 2025-10-29: Initial draft * 2026-01-09: Add option categories * 2026-01-15: Allow for category extensions # Session Delete Source: https://agentclientprotocol.com/rfds/session-delete Author(s): [@chazcb](https://github.com/chazcb) Champion: [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? Add a capability-gated `session/delete` method so clients can remove sessions from `session/list`. This complements `session/list` by giving users control over which sessions appear in their session history. ## Status quo > How do things work today and what problems does this cause? Why would we change things? The [`session/list` RFD](/rfds/session-list) introduced the ability for clients to enumerate sessions. However, there's no standard way to remove sessions from this list. Without `session/delete`, users have no control over their session history—old sessions accumulate, and clients must implement non-standard deletion mechanisms or rely on agent-specific cleanup policies. ## What we propose to do about it > What are you proposing to improve the situation? Add a `session/delete` JSON-RPC method that is capability-gated. Agents advertise support via `sessionCapabilities.delete` in their initialization response. ```json theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "sessionCapabilities": { "delete": {} } } } } ``` ### Method ```json theme={null} { "jsonrpc": "2.0", "id": 3, "method": "session/delete", "params": { "sessionId": "sess_abc123def456" } } ``` ### Request Parameters | Field | Type | Required | Description | | - | - | - | - | | `sessionId` | `SessionId` | Yes | The session to delete | ### Response On success, returns an empty result: ```json theme={null} { "jsonrpc": "2.0", "id": 3, "result": {} } ``` ### Semantics * **Removes from list**: The primary effect is that deleted sessions no longer appear in `session/list` results. * **Implementation-defined storage behavior**: Agents may implement soft delete (mark as hidden) or hard delete (remove data). The protocol does not prescribe which. * **Implementation-defined load behavior**: Agents may choose what happens when a client calls `session/load` on a deleted session—return the session anyway, return an error, or any other behavior. The protocol does not prescribe which. * **Idempotent**: Deleting an already-deleted session (or a session that never existed) SHOULD succeed silently rather than error. ## Alternatives considered ### Automatic lifecycle policies only Rely on agents to implement their own session retention policies (e.g., delete sessions older than 30 days) without exposing user control. **Tradeoffs**: Users have no control over which sessions are kept. A session the user wants to keep might be deleted, or a session the user wants gone might persist. ### Add a `hidden` flag to sessions Instead of delete, allow users to mark sessions as hidden. They'd still exist but not appear in `session/list` by default. **Tradeoffs**: More complex—requires filter parameters on `session/list` to show/hide hidden sessions. For most use cases, delete is simpler and matches user expectations. ### Batch deletion Support deleting multiple sessions in one call via a `sessionIds` array. **Tradeoffs**: Could be added later as an extension. Single-session delete covers the common case and keeps the initial implementation simple. ## Shiny future > How will things play out once this feature exists? Users can manage their session history, and all ACP clients can offer this using the same protocol method rather than implementing their own mechanisms. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? 1. **Schema**: Add `session/delete` method definition, `DeleteSessionRequest` and `DeleteSessionResponse` types. 2. **Capabilities**: Add `sessionCapabilities.delete` capability flag. 3. **Protocol**: Add `session/delete` to method tables. 4. **Docs**: Update session management docs to include deletion. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why not prescribe soft vs hard delete? Different agents have different storage architectures and compliance requirements. Some may need to retain data for auditing; others may want to free storage immediately. The protocol focuses on the user-facing behavior (removed from list) and leaves storage decisions to implementers. ### Why not prescribe behavior for loading deleted sessions? Similar reasoning—some agents may want to allow "undelete" by loading a soft-deleted session, others may want a clean error. The protocol provides the deletion mechanism; agents decide the semantics that fit their use case. ### Should delete require confirmation? No. Confirmation UX is a client concern. The protocol provides the delete operation; clients can add confirmation dialogs, undo functionality, or other UX patterns as they see fit. ### What if the session is currently active? Agents may reject deletion of active sessions or handle it however they choose. This is implementation-defined. A reasonable approach is to allow deletion—the session simply won't appear in future `session/list` calls. ### Why is this a separate RFD from session/list? The [`session/list` RFD](/rfds/session-list#what-about-session-deletion) explicitly deferred deletion to keep scope focused. Now that `session/list` is established, `session/delete` is a natural complement. ## Revision history * **2026-06-05**: RFD marked as Completed; `session/delete` is stabilized * **2026-06-02**: Moved to Preview * **2025-02-03**: Fixed capability example to use agent capability (initialize response) * **2025-01-24**: Initial draft # Forking of existing sessions Source: https://agentclientprotocol.com/rfds/session-fork * Author(s): [@josevalim](https://github.com/josevalim) * Champion: [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? We propose adding the ability to "fork" a new session based on an existing one. This will allow us to use the current conversation as context to generate pull request descriptions, summaries, etc. without polluting the user history. ## Status quo > How do things work today and what problems does this cause? Why would we change things? Imagine we want to summarize the current conversation to use it in a future chat. If we send a message asking for the summary, it will become part of its context, affecting future user interactions. Therefore we want to be able to fork a session, issue additional messages, and then close the fork. ## What we propose to do about it > What are you proposing to improve the situation? To add a "session/fork" method. ## Shiny future > How will things will play out once this feature exists? We will be able to implement functionality that requires using the current chat without polluting its history, ranging from summaries to potentially subagents. I can also see this feature being extended in the future to support an optional message ID, so the fork happens at a specific message, allowing clients to implement functionality like editing previous messages and similar. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? We propose to add a new "session/fork" method. Agents must declare this option is available by returning `session: { fork : {} }` in its capabilities. The object is reserved to declare future capabilities, such as forking from a specific message, a tool call, or similar. Then the client would be able to request a fork of the given session: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "session/fork", "params": { "sessionId": "sess_789xyz", "cwd": "...", "mcpServers": [...] } } ``` The request expects the same options as `session/load`, such as `cwd` and `mcpServers`. Similarly, the agent would respond with the `sessionId` of the new session, plus optional data such as config options, the same as `session/new`. As with `session/new`, the forked session is active once the agent responds, set up with the request's options, such as `cwd` and `mcpServers`. The client can prompt it right away, without calling `session/load` or `session/resume` first. Agents may reply with an error if forking of that specific session or with the given options is not supported, for example if the agent does not support forking with a different working directory than the initial session. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? **Q: Should a new method be introduced or should "session/new" be expanded?** They must be different because they will effectively require different options. For example, "session/new" has options such as capabilities and MCP which are not recommended to be set when forking, as the context being forked was built with other tools, and forking may accept a messageId for checkpoints. **Q: Should fork only accept the `sessionId` or also other options, similar to `session/load`?** Initially, we proposed to only accept the `sessionId`, but this would make it more difficult to allow forking of inactive sessions in agents like `claude-agent-acp`, as Claude does not retain the configured MCP servers of a session. Limiting fork to only already active sessions would limit its usefulness. Moreover, allowing to pass different options also allows features like dynamically adding MCP servers to existing sessions to work by forking them with the new options, if the agent supports it. If it does not, the client can still show an appropriate error message. ### What alternative approaches did you consider, and why did you settle on this one? None. This proposal is inspired by the abilities exposed in Claude Agent SDK. It must be validated against other agents too. ## Revision history * 2025-11-17: Mentioned capabilities format, updated FAQ. * 2025-11-20: Added request format and updated capabilities format. * 2025-12-10: Adjust fork options to align with `session/load`. * 2026-10-12: Clarify that a forked session is active once the agent responds, so the client does not need to resume it before prompting. # Session Info Update Source: https://agentclientprotocol.com/rfds/session-info-update * Author(s): [@ignatov](https://github.com/ignatov) ## Elevator pitch Add a `session_info_update` variant to the existing `SessionUpdate` notification type that allows agents to update session metadata (particularly title/name), enabling dynamic session identification in client UIs without requiring a new endpoint. ## Status quo Currently, the ACP protocol provides session management through `session/new`, `session/load`, and `session/list` (unstable). The `session/list` endpoint returns `SessionInfo` objects that include an optional `title` field for displaying session names in client UIs. However, there are several problems: 1. **No way to communicate title updates** - The `title` field in `SessionInfo` is static in the list response. Agents cannot dynamically update it as the session evolves. 2. **No mechanism for real-time metadata updates** - Unlike commands (`available_commands_update`) or modes (`current_mode_update`), there's no way for agents to: * Auto-generate titles after the first meaningful exchange * Update titles as conversation context shifts * Provide custom metadata that reflects session state 3. **Inconsistent with protocol patterns** - Other dynamic session properties use `session/update` notifications (commands, modes, plans), but metadata has no equivalent mechanism. The current workaround is for clients to: * Maintain their own title mapping (doesn't persist or sync) * Only show static metadata from `session/list` * Have no way to receive agent-generated titles in real-time ## What we propose to do about it Add a new `session_info_update` variant to the existing `SessionUpdate` discriminated union that allows agents to notify clients about metadata changes. This update would: 1. **Follow the existing `SessionUpdate` pattern**: * Uses the same notification mechanism as `available_commands_update`, `current_mode_update`, etc. * Sent via `session/update` method * Agent-initiated, no request/response needed 2. **Align with `SessionInfo` structure**: * Contains the same fields as `SessionInfo` from `session/list` * All fields are optional (partial updates) * Enables incremental metadata updates * **Important**: `SessionInfoUpdate` must stay aligned with `SessionInfo` - when new fields are added to `SessionInfo`, they should also be added to `SessionInfoUpdate` as optional fields 3. **Support common use cases**: * Agent auto-generates title after first prompt * Agent updates title as conversation context shifts * Agent provides custom metadata for client features (tags, status, etc.) * User explicitly requests title change (agent responds with update notification) 4. **Integrate seamlessly**: * No new capability required (uses existing `session/update` mechanism) * Compatible with `session/list` - metadata should persist and be reflected in list responses * Works during active sessions ### Notification Structure The agent sends a `session/update` notification with `sessionUpdate: "session_info_update"`: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "session_info_update", "title": "Implement user authentication", "_meta": { "tags": ["feature", "auth"], "priority": "high" } } } } ``` ### SessionInfoUpdate Type The update type mirrors `SessionInfo` but with all fields optional: ```typescript theme={null} { sessionUpdate: "session_info_update", title?: string | null, // Update or clear the title updatedAt?: string | null, // ISO 8601 timestamp (usually agent sets this) _meta?: object | null // Custom metadata update signal } ``` **Note:** `sessionId` and `cwd` are NOT included since: * `sessionId` is already in the notification's `params` * `cwd` is immutable and set during `session/new` ### Examples #### Update title and working directory metadata After the user sends their first meaningful prompt, the agent can generate and send a title along with metadata about the working directory: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "session_info_update", "title": "Debug authentication timeout", "_meta": { "projectName": "api-server", "branch": "main" } } } } ``` #### Update title as conversation evolves As the conversation shifts focus: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123def456", "update": { "sessionUpdate": "session_info_update", "title": "Debug authentication timeout → Add retry logic" } } } ``` ## Shiny future Once this feature exists: 1. **Dynamic session identification** - Agents can: * Auto-generate meaningful titles from conversation content * Update titles as conversations evolve * Provide rich metadata for better organization 2. **Improved client UIs** - Clients can: * Show real-time title updates in session lists * Display session status, tags, or other metadata * Update UI immediately without polling `session/list` 3. **Consistent protocol patterns** - Session metadata updates work like other dynamic session properties (commands, modes), creating a unified model 4. **Bidirectional workflows** - Combined with a potential future request method: * User renames session → client sends request → agent acknowledges with `session_info_update` notification * Agent auto-generates title → sends `session_info_update` notification → client displays it 5. **Enhanced use cases**: * Session templates that auto-set titles and tags * Progress indicators via `_meta` * Integration with external tools via metadata * Rich session browsing and filtering ## Implementation details and plan ### Phase 1: Schema Changes 1. **Update `schema.unstable.json`**: * Add `SessionInfoUpdate` type definition * Add new variant to `SessionUpdate` oneOf array * Align fields with `SessionInfo` but make all optional ```json theme={null} { "SessionInfoUpdate": { "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUpdate to session metadata. All fields are optional to support partial updates.", "properties": { "_meta": { "description": "Extension point for implementations" }, "title": { "description": "Human-readable title for the session", "type": ["string", "null"] }, "updatedAt": { "description": "ISO 8601 timestamp of last activity", "type": ["string", "null"] } }, "type": "object" } } ``` Add to `SessionUpdate` oneOf: ```json theme={null} { "allOf": [ { "$ref": "#/$defs/SessionInfoUpdate" } ], "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUpdate to session metadata", "properties": { "sessionUpdate": { "const": "session_info_update", "type": "string" } }, "required": ["sessionUpdate"], "type": "object" } ``` ### Phase 2: Protocol Documentation 2. **Create documentation** in `/docs/protocol/session-metadata.mdx`: * Explain the notification mechanism * Provide examples of common patterns * Document omitted, `null`, and object semantics for `_meta` * Clarify relationship with `session/list` 3. **Update existing docs**: * Reference in `/docs/protocol/session-setup.mdx` * Add to `/docs/protocol/prompt-turn.mdx` session update section ### Phase 3: SDK Implementation 4. **Implement in Rust SDK**: * Add `SessionInfoUpdate` struct * Add variant to `SessionUpdate` enum * Update notification handling in agent and client traits * Add helper methods for common patterns 5. **Implement in TypeScript SDK** (if applicable): * Add TypeScript types * Update notification handlers * Add helper methods ### Phase 4: Example Implementation 6. **Update example agents**: * Demonstrate auto-generating title from first prompt * Show updating metadata during session * Example of using `_meta` for custom fields ### Compatibility Considerations * **Fully backward compatible**: This adds a new notification variant to an existing mechanism * **No breaking changes**: Existing agents and clients continue working * **Graceful degradation**: Clients that don't handle this notification simply ignore it * **No new capability needed**: Uses existing `session/update` infrastructure ### Design Decisions **Why notification instead of request/response?** * Consistent with existing `SessionUpdate` patterns (`available_commands_update`, `current_mode_update`) * Agents initiate updates based on conversation state * Simpler than bidirectional request/response * Enables real-time updates without polling **Why make all fields optional?** * Allows partial updates (only update what changed) * More efficient - don't resend unchanged data * Flexible for different use cases * Mirrors partial update patterns in other protocols **Why not include `sessionId` and `cwd` in the update?** * `sessionId` is already in the notification params * `cwd` is immutable (set in `session/new`, never changes) * Keeps update focused on mutable metadata **How do `_meta` updates work?** * Omitted `_meta` means no metadata update was supplied. * `"_meta": null` is an explicit clear signal. * `"_meta": { ... }` supplies a metadata object for clients and extensions to interpret. ### Security Considerations * **No additional security concerns**: Uses existing session authentication * **Input validation**: * Agents should validate title length (recommend 500 chars max) * Sanitize metadata to prevent injection * Validate `_meta` structure based on agent requirements * **Resource limits**: Agents should limit update frequency and metadata size ## Frequently asked questions ### Why not create a new endpoint like `session/update-metadata`? The notification pattern is more appropriate because: 1. **Consistency**: Other dynamic session properties (commands, modes) use notifications 2. **Agent-initiated**: Agents typically generate titles from conversation context 3. **Real-time**: No request/response overhead, updates flow naturally 4. **Simpler**: Reuses existing `session/update` infrastructure ### How does this work with `session/list`? The updated metadata should persist and be reflected in subsequent `session/list` calls. The notification provides real-time updates to connected clients, while `session/list` provides the current state for discovery. ### Can clients trigger title updates? This RFD covers agent-initiated updates. Client-initiated updates could work by: 1. Client sends a prompt asking to rename session 2. Agent updates its internal state 3. Agent sends `session_info_update` notification 4. Client receives and displays the update A future RFD could add explicit request/response for this if needed. ### What if multiple updates are sent in quick succession? Clients should process updates in order and apply each field according to its field semantics. ### Should `updatedAt` be automatically set by the agent? Yes, typically the agent should update this timestamp when any session activity occurs, not just when metadata changes. However, including it in `session_info_update` allows agents to explicitly control it if needed. ### Do agents need a new capability for this? No. All agents that support `session/update` notifications can send this variant. Clients that don't recognize it will ignore it (standard JSON-RPC behavior). ### How does this interact with `session/fork`? When forking, the parent session's metadata could be copied (implementation choice). The forked session would have its own `sessionId` and could receive separate `session_info_update` notifications. ### What happens if title is too long? This is an implementation choice. Agents MAY: * Truncate long titles * Reject updates (though this is a notification, so no error response) * Set a reasonable limit (e.g., 500 characters) Clients SHOULD handle long titles gracefully (truncate in UI, show tooltip, etc.). ### Can `_meta` have nested objects? Yes, `_meta` is an arbitrary object. Agents define its structure. ### What alternative approaches did you consider, and why did you settle on this one? Several alternatives were considered: 1. **Add a new request/response endpoint (`session/update-metadata`)** - This would be inconsistent with how other dynamic session properties (commands, modes) are handled. The notification pattern is more appropriate for agent-initiated updates. 2. **Add title parameter to `session/new`** - Only allows setting title at creation time, doesn't support dynamic updates as the conversation evolves. 3. **Client-side only metadata tracking** - Doesn't work across devices, can get out of sync, and duplicates storage. This is the current workaround and has significant limitations. 4. **Generic `session/update` request for all properties** - Could conflict with immutable properties (sessionId, cwd) and has unclear semantics about what can be updated. The proposed notification-based approach: * **Consistent** with existing protocol patterns * **Flexible** for both agent-initiated and user-initiated updates * **Simple** to implement and understand * **Extensible** via `_meta` field ## Revision history * **2025-11-28**: Initial draft proposal # Session List Source: https://agentclientprotocol.com/rfds/session-list * Author(s): [@ahmedhesham6](https://github.com/ahmedhesham6) * Champion: [@benbrandt](https://github.com/benbrandt) ## Elevator pitch Add a `session/list` endpoint to the ACP protocol that allows clients to query and enumerate existing sessions from an agent, enabling session management features like session history, session switching, and session cleanup. ## Status quo Currently, the ACP protocol provides session management through `session/new` and `session/load` endpoints. However, there is no way for clients to: 1. **Discover existing sessions** - Clients cannot query what sessions exist on an agent 2. **Display session history** - Users cannot see a list of their past conversations 3. **Manage multiple sessions** - Switching between sessions requires clients to track session IDs themselves 4. **Clean up old sessions** - No way to discover stale or abandoned sessions for cleanup This creates several problems: * **Poor user experience** - Users cannot browse their conversation history or resume previous sessions easily * **Client-side complexity** - Each client must implement its own session tracking and persistence * **Inconsistent behavior** - Different clients handle session management differently, leading to fragmented experiences The current workaround is for clients to maintain their own session registry, but this: * Requires persistent storage on the client side * Can get out of sync if sessions are created/destroyed outside the client * Doesn't work across different client instances or devices * Cannot leverage agent-side session metadata or state ## What we propose to do about it Add a new `session/list` JSON-RPC method to the protocol that returns metadata about sessions known to the agent. This endpoint would: 1. **Return a list of sessions** with essential metadata: * `sessionId` - Unique identifier * `cwd` - Working directory for the session * `title` - Optional human-readable title (could be auto-generated from first prompt) * `updatedAt` - Timestamp of last update to the session * `_meta` - Optional agent-specific metadata 2. **Support filtering and pagination**: * Filter by working directory * Agent provides an optional cursor for retrieving the next page of results 3. **Be an optional capability**: * Agents advertise `sessionCapabilities: { list: {} }` in initialization if they support this feature * Clients check for this capability before attempting to call `session/list` * Agents without persistent session storage don't need to implement this ### JSON-RPC Request The client calls `session/list` with optional filtering and pagination parameters: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "session/list", "params": { "cwd": "/home/user/project", "cursor": "eyJwYWdlIjogMn0=" } } ``` #### Request Parameters All parameters are optional: * `cwd` (string) - Filter sessions by working directory * `cursor` (string) - Opaque cursor token from a previous response's `nextCursor` field for cursor-based pagination #### Minimal Request Example A request with no filters returns all sessions with default sorting: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "session/list", "params": {} } ``` ### JSON-RPC Response The agent responds with a list of sessions and cursor pagination metadata: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "result": { "sessions": [ { "sessionId": "sess_abc123def456", "updatedAt": "2025-10-29T14:22:15Z", "cwd": "/home/user/project", "title": "Implement session list API", "_meta": { "messageCount": 12, "hasErrors": false } }, { "sessionId": "sess_xyz789ghi012", "updatedAt": "2025-10-28T16:45:30Z", "cwd": "/home/user/another-project", "title": "Debug authentication flow" }, { "sessionId": "sess_uvw345rst678", "updatedAt": "2025-10-27T15:30:00Z", "cwd": "/home/user/project" } ], "nextCursor": "eyJwYWdlIjogM30=" } } ``` #### Response Fields **Response object:** * `sessions` (array) - Array of session information objects * `nextCursor` (string, optional) - Opaque cursor token. If present, pass this in the next request's `cursor` parameter to fetch the next page. If absent, there are no more results. **SessionInfo object:** * `sessionId` (string, required) - Unique identifier for the session * `cwd` (string, required) - Working directory for the session * `title` (string, optional) - Human-readable title (may be auto-generated from first prompt) * `updatedAt` (string, optional) - ISO 8601 timestamp of last activity * `_meta` (object, optional) - Agent-specific metadata (e.g., message count, error status, tags) #### Empty Result Example When no sessions match the criteria: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "result": { "sessions": [] } } ``` ## Shiny future Once this feature exists: 1. **Clients can build session browsers** - Users can view a list of all their conversations, sorted by recency or relevance 2. **Session switching becomes seamless** - Users can easily switch between ongoing conversations 3. **Better resource management** - Clients can identify and clean up old or inactive sessions 4. **Cross-device continuity** - Users could potentially access their sessions from different devices (if agent supports it) 5. **Improved UX patterns**: * "Recent conversations" sidebar * Search through past sessions * Archive/delete old sessions * Resume interrupted work easily Agents that implement this feature gain: * Better visibility into active sessions * Opportunity to implement session lifecycle policies * Foundation for future features like session sharing or collaboration ## Implementation details and plan ### Phase 1: Core Protocol Changes 1. **Update schema.json** to add: * `session/list` method definition * `ListSessionsRequest` and `ListSessionsResponse` types * `SessionInfo` type * `sessionCapabilities/list` capability flag 2. **Update protocol documentation** in `/docs/protocol/session-setup.mdx`: * Document the new endpoint * Explain when to use it vs. maintaining client-side session tracking * Provide examples of common use cases ### Phase 2: Reference Implementation 3. **Implement in Rust SDK** (`src/agent.rs` and `src/client.rs`): * Add `list_sessions` method to agent trait * Provide default implementation (empty list) for agents without persistence * Add client method to call `session/list` 4. **Add to TypeScript SDKs** (if applicable): * Update TypeScript types * Add client methods ### Phase 3: Example Implementation 5. **Create example agent** that demonstrates: * In-memory session registry * Automatic title generation from first prompt * Session lifecycle management (cleanup after N days) * Pagination and filtering ### Compatibility Considerations * **Backward compatible**: Existing agents continue working without implementing this * **Capability-based**: Clients check for `sessionCapabilities.list` capability before using * **No breaking changes**: No modifications to existing endpoints ### Security Considerations * **Session isolation**: Agents must ensure sessions are only listed for the authenticated client * **Resource limits**: Agents should enforce reasonable page sizes internally to prevent abuse ## Frequently asked questions ### What alternative approaches did you consider, and why did you settle on this one? Several alternatives were considered: 1. **Client-side session tracking only** - This is the current approach, but it has limitations: * Doesn't work across devices * Can get out of sync * Adds complexity to every client implementation 2. **Session events/notifications** - Push notifications when sessions are created/destroyed: * More complex to implement * Requires long-lived connections * Still requires client-side state management * Better suited as a future enhancement, not a replacement 3. **File-based session manifest** - Agent writes session list to a file that clients read: * Couples agent and client file system access * Doesn't work for remote agents * No standard format The proposed RPC approach is: * **Consistent with existing protocol design** - Uses same RPC patterns as other endpoints * **Flexible** - Supports filtering, pagination, and agent-specific metadata * **Optional** - Agents can opt-in based on their architecture * **Simple** - Single request/response pattern, easy to implement and use ### Why not make this mandatory for all agents? Many agents may not have persistent storage or multi-session capabilities. Making this optional: * Allows simple, stateless agents to remain compliant * Reduces implementation burden * Lets agents evolve session management over time ### How does this interact with `session/load`? `session/load` remains the mechanism to actually restore a session. `session/list` is for discovery only: 1. Client calls `session/list` to get available sessions 2. User selects a session 3. Client calls `session/load` with the chosen `sessionId` Agents may support `session/list` without supporting `session/load` (e.g., for read-only session browsing). ### Should we include session content in the list response? No, for several reasons: * **Performance** - Full conversation history could be large * **Privacy** - Listing sessions might be less sensitive than exposing full content * **Separation of concerns** - Use `session/load` to get full session content ### What about session deletion? Session deletion is intentionally left out of this RFD to keep scope focused. It is covered separately by the [Session Delete RFD](/rfds/session-delete) and the [`session/delete`](/protocol/v1/session-delete) method. ### How should pagination work for large session lists? We use cursor-based pagination: * Request includes an optional `cursor` * Response includes `nextCursor` when more results are available * Clients should treat a missing `nextCursor` as the end of results * Clients MUST treat cursors as opaque tokens: don't parse, modify, or persist them across sessions * The cursor MUST be a string; never send a raw JSON object as the cursor * Servers SHOULD provide stable cursors and handle invalid cursors gracefully Good request example: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "session/list", "params": { "cwd": "/home/user/project", "createdAfter": "2025-10-20T00:00:00Z", "cursor": "eyJwYWdlIjogMn0=", "search": "auth" } } ``` Corresponding response example: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "result": { "sessions": [/* ... */], "nextCursor": "eyJwYWdlIjogM30=" } } ``` ## Revision history * **2025-10-29**: Initial draft proposal * **2025-10-30**: Update to use `_meta` field for agent-specific metadata * **2025-10-30**: Switch from offset-based to cursor-based pagination using continuation tokens * **2025-10-30**: Rename `lastAccessedAt` to `updatedAt` for consistency * **2025-10-30**: Remove `preview` field from SessionInfo (out of scope) * **2025-10-30**: Remove session orphaning from problem statement * **2025-10-30**: Replace `sortBy`/`sortOrder` with `search` parameter; remove `total` count from response * **2025-10-31**: Update pagination: `continuationToken` → `cursor`, `nextContinuationToken` → `nextCursor`, remove `hasMore` * **2025-11-11**: Remove `createdAt`, `updatedAt`, and `search` filters from the request parameters * **2025-11-23**: Remove `limit` parameter from request; make `createdAt` and `updatedAt` optional in SessionInfo * **2025-11-24**: Update capabilities schema, consolidate to single `updatedAt` timestamp # Session Notices Source: https://agentclientprotocol.com/rfds/session-notices Author(s): [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? Add a fire-and-forget `notice` session update to ACP v1 and v2 for information that should be visible to the user without becoming conversation history or a durable protocol entity. In v1, a Client capability lets Agents choose between notices and an existing presentation channel such as agent messages. ## Status quo > How do things work today and what problems does this cause? Why would we change things? Agents encounter user-relevant conditions that are not messages, tool calls, etc. Examples include an optional integration being unavailable, configuration falling back to defaults, or a model request being rerouted while work continues. ACP currently gives Agents no standard presentation event for these cases. They must either omit the information, use an implementation-specific update, or emit an agent message. These events also do not need Agent-managed identity or lifecycle. Whether a warning remains visible, disappears after a delay, or can be dismissed is a Client and user-interface decision. ## What we propose to do about it > What are you proposing to improve the situation? Add a `notice` variant to `SessionUpdate` in ACP v1 and v2: ```json theme={null} { "sessionUpdate": "notice", "severity": "warning", "title": "MCP server unavailable", "description": "Continuing without it." } ``` The fields are deliberately small: * `severity` is required and non-null. Its initial values are `info`, `warning`, and `error`. * `title` is a required, non-null, non-empty plain-text string that can stand alone in a compact presentation. * `description` is an optional, nullable plain-text string with additional detail or guidance. Omission and `null` both mean that the Agent supplied no description. * `_meta` is optional and nullable. Omission and `null` are equivalent and mean that the Agent supplied no event metadata. `NoticeSeverity` is open in both protocol versions from its introduction and follows the [v2 enum-extension rules](/rfds/v2/enum-variant-extension). Values beginning with `_` are reserved for implementation-specific extensions, while other unknown values are reserved for future ACP severities. Clients preserve an unknown string and use a generic notice presentation without inferring salience, lifetime, or control behavior from it. Adding a severity does not require protocol negotiation. A notice has no ID, response, acknowledgement, update, or removal, and **SHOULD NOT** be included in session replay. Repeated notices are independent events, even when their fields are identical. ### Client presentation A Client that chooses to present notices makes them accessible to the user and controls their presentation. It may use a toast, banner, inline status region, notification center, or another surface. It may coalesce repeated notices and apply user preferences. Severity is a hint. For example, a Client may show `info` for a short period, leave `warning` visible until local dismissal, and present `error` more prominently. ACP does not prescribe those choices or a timeout. User dismissal is entirely local. The Client does not report dismissal to the Agent, and the Agent does not send a removal event. If the Agent needs to know whether the user saw, accepted, or acted on something, a notice is the wrong primitive. `error` severity still describes a user-facing notice. It does not fail a JSON-RPC request, stop foreground work, change session state, or imply a prompt stop reason. ### Delivery and history A notice is scoped to the session identified by the surrounding `session/update` notification. Notices are live events, not session history. After reconnecting, an Agent may emit a new notice if the condition is still currently relevant. That is a new live event rather than replay of the earlier notice, and the Client remains free to coalesce it. Agents must not rely on notice delivery for protocol correctness, required user action, authorization, task completion, or fatal-error reporting. Those cases belong in the relevant request, permission, elicitation, message, tool, or lifecycle primitive. The Agent must behave as though the notice may not have been received, understood, displayed, or seen by the user. ### Version-specific capability For v1, add an optional `notices` object to `ClientSessionCapabilities`: ```json theme={null} { "clientCapabilities": { "session": { "notices": {} } } } ``` The object appears at `clientCapabilities.session.notices` in the v1 `initialize` request. Omitting `session`, setting `session` to `null`, omitting `notices`, or setting `notices` to `null` all mean the Client does not advertise support. Supplying `{}` for `notices` means the Client can present notices to the user with the semantics in this RFD. Agents **MUST NOT** send `notice` updates to a v1 Client unless it advertises this capability. The capability lets the Agent choose where to send user-facing information. When the Client does not advertise notice support, the Agent may use an ordinary agent message instead if the information should still be surfaced to the user. That fallback is conversation content and follows normal message-history semantics. Advertising notice support does not acknowledge delivery or guarantee that the user has seen an individual notice; Clients still control presentation and user preferences. V2 does not add or require a capability. It preserves unknown notices through its unknown session-update fallback, after which the Client may ignore or generically present them. V1 keeps its closed `SessionUpdate` union and uses the capability rather than requiring unsupported Clients to accept a new variant. ## Shiny future > How will things will play out once this feature exists? Agents can surface operational information without pretending it is part of the conversation. Clients can integrate notices into their own visual language and accessibility model. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? ### Implemented The initial Preview protocol implementation landed in [PR #2004](https://github.com/agentclientprotocol/agent-client-protocol/pull/2004), with the v1 Client capability added in [PR #2171](https://github.com/agentclientprotocol/agent-client-protocol/pull/2171): * Both protocol versions define `Notice`, the open `NoticeSeverity` string enum, and the `notice` variant in their `SessionUpdate` unions. * V1 defines the optional `ClientSessionCapabilities.notices` capability; v2 does not require a capability. * Both versions preserve unknown severity strings and treat omitted and `null` descriptions and event metadata equivalently. ### External implementation evidence V1 runtime implementations have also landed: | Implementation | Reference | Behavior | | - | - | - | | Zed | [PR #64606](https://github.com/zed-industries/zed/pull/64606) | Advertises support with ACP beta enabled; presents session-local, dismissible notices outside the transcript, with generic presentation for unknown severities. | | Claude Agent adapter | [PR #1155](https://github.com/agentclientprotocol/claude-agent-acp/pull/1155), included in [v0.81.1](https://github.com/agentclientprotocol/claude-agent-acp/releases/tag/v0.81.1) | Gates live notices on the Client capability, retains fallback behavior, and keeps notices separate from history and task/error control flow. | | Codex adapter | [PR #532](https://github.com/agentclientprotocol/codex-acp/pull/532), included in [v1.13.1](https://github.com/agentclientprotocol/codex-acp/releases/tag/v1.13.1) | Gates notices on the Client capability, preserves legacy fallback behavior, and excludes notices from loaded history. | ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why is the capability required in v1? Without it, an Agent cannot tell whether a v1 Client can present notices or will simply drop them. As with compaction, the capability lets the Agent use the dedicated presentation event when supported and fall back to an agent message when the information should still reach users of older Clients. It advertises a presentation channel, not acknowledgement of any individual notice. ### Why is there no notice ID? The Agent never updates, resolves, or removes a notice. Identity would invite Clients to infer a lifecycle that the protocol does not define. Clients may use local identities for rendering, dismissal, or diagnostic retention. ### Why does the notice not say whether it is dismissible or how long it lasts? Those are presentation choices that vary by Client surface, accessibility needs, severity policy, and user preferences. The Agent supplies severity; the Client decides whether and when the event disappears. ### Should the Client report dismissal to the Agent? No. Dismissal only changes local presentation. If Agent behavior depends on a user decision, the Agent needs an explicit response-bearing primitive such as elicitation or permission, not a notice. ### Why is this a `session/update` variant instead of a new `session/notice` method? `session/update` is already ACP's Agent-to-Client carrier for session-scoped activity. The known `notice` variant can define its live-only lifetime without adding another notification method. The v1 capability lets Agents choose a fallback for Clients that do not implement the variant, while the replay guidance makes clear that supporting Clients should not treat notices as durable history. ### What alternative approaches did you consider, and why did you settle on this one? **Agent messages** - Universally visible, but they pollute conversation history and can be easily missed in the rest of the text. They remain a fallback for v1 Clients that do not advertise notice support. **Structured actions and acknowledgements** - Useful when user interaction is required, but those cases should use response-bearing primitives rather than turning notices into a second elicitation system. ## Revision history * 2026-10-09: Moved to Completed; stabilized notices in both protocol versions, retaining the v1 capability gate, capability-free v2 delivery, open severities, and live-only semantics. Protocol v2 remains draft overall. * 2026-09-24: Moved to Preview * 2026-09-17: Added a v1 Client capability so Agents can choose between notices and an agent-message fallback. V2 remains capability-free. * 2026-08-20: Updated the implementation plan for the schema-only architecture, which keeps v1 and v2 types separate, documents replay guidance normatively, and leaves runtime and example adoption to downstream SDKs. * 2026-07-22: Initial draft. # Session options Source: https://agentclientprotocol.com/rfds/session-options Author(s): [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? Add a `session/options` method that returns the config options a session would start with, without creating or resuming a session. Clients call it to fill a "new session" screen (model picker, other config options) before the user sends a first prompt. With a `sessionId`, Clients can also show what an existing session would have before resuming it. Agents that support `session/options` also accept initial config option values on session setup requests. Clients send back the values the user picked, and the session starts with them. Both parts are advertised with a single capability. This RFD covers v1 and v2. v2 also returns available commands. See [Version differences](#version-differences). ## Status quo > How do things work today and what problems does this cause? Why would we change things? [Session config options](./session-config-options.mdx) are only available after a session exists. The Agent returns them in the session setup response (`session/new`, `session/load`, or `session/resume` in v1, `session/new` or `session/resume` in v2), and the Client changes them with `session/set_config_option`. v1 modes and v2 available commands work the same way. The config options RFD left configuration needed before a session exists out of scope. This leaves Clients with two options for a "new session" screen: * Create a session as soon as the screen opens, to read its config options. Creating a session can start MCP servers, set up provider state, and add an entry to `session/list`. If the user never sends a prompt, the Client has created a session it did not need. * Show no config options until the session exists. The user picks a model after the session has started, and the Client sends one `session/set_config_option` request per change. Neither option lets the user pick settings first and start a session with them. ## What we propose to do about it > What are you proposing to improve the situation? ### Capability Agents advertise support with an `options` capability in their session capabilities. In v1: ```json theme={null} { "agentCapabilities": { "sessionCapabilities": { "options": {} } } } ``` In v2: ```json theme={null} { "capabilities": { "session": { "options": {} } } } ``` An Agent that advertises the capability **MUST** implement `session/options` and **MUST** accept the `configOptions` field on every session setup request it supports. Clients **MUST NOT** call `session/options` or send `configOptions` on session setup requests unless the capability is present. ### `session/options` The request takes the same workspace parameters as `session/new`, plus an optional `sessionId`, so the Agent can resolve options for that context: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "session/options", "params": { "cwd": "/home/user/project", "additionalDirectories": ["/home/user/shared-lib"] } } ``` * `cwd` is required and **MUST** be an absolute path. * `additionalDirectories` is optional. Omitted and `null` are equivalent to an empty list. * `sessionId` is optional. Omitted and `null` are equivalent and mean a new session. * There is no `mcpServers` parameter. See [Why doesn't `session/options` take MCP servers?](#why-doesnt-sessionoptions-take-mcp-servers) When `sessionId` is present, the Agent returns what restoring that session with the same `cwd` and `additionalDirectories` would return (`session/load` or `session/resume` in v1, `session/resume` in v2). The same `cwd` rules as those methods apply. If the session does not exist, the Agent **MUST** return `-32002` (Resource not found). The response contains the config options the session would start with: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "configOptions": [ { "id": "model", "name": "Model", "category": "model", "type": "select", "currentValue": "model-1", "options": [ { "value": "model-1", "name": "Model 1" }, { "value": "model-2", "name": "Model 2" } ] } ] } } ``` `configOptions` uses the same type and rules as on `NewSessionResponse` for that protocol version. The response also carries the other initial session state for that version (v1 `modes`, v2 `availableCommands`), described in [Version differences](#version-differences). `session/options` **MUST NOT** create or resume a session. The Agent **MUST NOT** send `session/update` notifications for it, and the call **MUST NOT** add an entry to `session/list` or change an existing session. The Agent **MAY** read workspace files and its own configuration to resolve options. It **SHOULD NOT** connect to MCP servers to answer `session/options`. Some Agents only know their options from a running runtime, such as a subprocess that reports its models. Such an Agent **MAY** start that runtime to answer `session/options`. The rules above still hold for it: it stores no session, writes nothing to the history of the session named by `sessionId`, and adds no entry to `session/list`. Clients **SHOULD NOT** call `session/options` on a timer, because such an Agent may start its runtime for each call. See [What if the Agent has to start its runtime to know its options?](#what-if-the-agent-has-to-start-its-runtime-to-know-its-options) The response is a snapshot. The options a session actually starts with are the ones in the session setup response. ### Initial values on session setup Session setup requests gain an optional `configOptions` field. Omitted and `null` are equivalent to an empty list. Each entry uses the same value shape as `session/set_config_option`: ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "session/new", "params": { "cwd": "/home/user/project", "mcpServers": [], "configOptions": [ { "configId": "model", "type": "id", "value": "model-2" }, { "configId": "reasoning", "type": "id", "value": "high" } ] } } ``` The Agent applies the entries in list order, as if the Client had called `session/set_config_option` for each entry after the session was set up. Each entry is checked against the option set as it stands at that point, so an earlier entry (such as the model) can change which values a later entry (such as the reasoning level) allows. Clients **SHOULD** send entries in the order the Agent listed the options in the `session/options` response. For resumed or loaded sessions, the entries apply on top of the session's restored configuration. On `session/fork`, the entries apply on top of the configuration the fork would start with without them. To show the options before a fork, Clients call `session/options` with the `sessionId` of the source session. Notifications: * The Agent **SHOULD NOT** send `config_option_update` notifications for these entries. The setup response contains the resulting values. * Until the `session/new` or `session/fork` response, the Client does not know the session. The Agent **SHOULD NOT** send other `session/update` notifications caused by applying the entries before that response, such as a mode change or a notice that a value fell back. It sends them after the response. * In v2, a `session/resume` can reach a session that is active on other connections. See [Version differences](#version-differences). Error handling: * An entry that does not match the schema (for example, a missing `configId` or a `value` that does not match its `type`) **MUST** fail the request with `-32602` (Invalid params). * Two entries with the same `configId` **MUST** fail the request with `-32602`. * A well-formed entry whose `configId` is unknown, whose `type` does not match the option's type (for example, a `boolean` entry for a `select` option), or whose value is not allowed at the point it is applied, **MUST** be ignored. Options can change type between `session/options` and session setup, so this is stale state, not a Client bug. The option keeps its default value, or the value the Agent resolved from earlier entries. A value the option lists but the Agent's runtime refuses when it is applied, such as a model the provider no longer serves, is not allowed either. The Agent ignores it and does not fail the request, since the session already exists. * The `configOptions` in the response **MUST** contain the values the session actually has after all entries are applied. Clients compare them with what they sent to find entries the Agent ignored. ### Version differences #### v1 * The capability is `sessionCapabilities.options`, behind an unstable feature. * `session/options` returns `configOptions` and `modes`, with the same types and optionality as on `NewSessionResponse`. * `configOptions` is accepted on `session/new`, `session/load`, `session/resume`, and, when the Agent supports it, `session/fork`. As on v1 `session/set_config_option`, `type` is optional and defaults to `id`. * The existing rules for boolean options still apply. Agents only return `type: "boolean"` options from `session/options`, and Clients only send `type: "boolean"` entries in `configOptions`, when the Client advertises `sessionCapabilities.configOptions.boolean`. * Clients **MUST NOT** send `sessionId` on `session/options` unless the Agent supports `session/load` (`loadSession`), `session/resume` (`sessionCapabilities.resume`), or `session/fork` (`sessionCapabilities.fork`). * Modes do not get an initial value field. Agents that expose modes as a config option (category `mode`) can receive the mode through `configOptions`. * There is no `availableCommands` in the response. v1 session setup responses do not include `availableCommands`. Agents send them in a `session/update` notification after the session exists. #### v2 * The capability is `capabilities.session.options`. Supplying `{}` means supported. Omission or `null` means unsupported. * `configOptions` is accepted on `session/new`, `session/resume`, and, when the Agent supports it, `session/fork`. Entries **MUST** include the `type` discriminator, as on v2 `session/set_config_option`. * An entry with a value `type` the Agent does not support **MUST** fail the request with `-32602`, as on v2 `session/set_config_option`. * For `session/resume`, the Agent applies the entries before it replays history for `replayFrom` and before it responds. * A `session/resume` can reach a session that is active on other connections. The entries change its configuration, so the Agent **SHOULD** send `config_option_update` on those connections, as for any other configuration change. The requesting connection gets the values in the response. The response includes optional `availableCommands`, with the same type and rules as on `NewSessionResponse`: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "availableCommands": [ { "type": "command", "name": "review", "description": "Review the current changes" } ] } } ``` `availableCommands` is advisory. Commands can depend on state the Agent only has once the session exists (MCP prompts, project files, skills). Agents **MAY** return a partial list or omit it. Clients **MUST** use the commands from the `session/new` or `session/resume` response and later `available_commands_update` notifications for the session itself. ## Shiny future > How will things will play out once this feature exists? A Client opens a "new session" screen and calls `session/options` with the workspace the user picked. It shows the model picker and other config options right away, and in v2 the slash commands it knows about. The user picks a model and a reasoning level, types a prompt, and sends it. The Client calls `session/new` with those values and then `session/prompt`. The first turn runs with the settings the user picked, and no session exists until the user commits to one. A Client can also call `session/options` with a `sessionId` from its session list to show which model a past session uses. The user can change it before resuming, and the Client passes the new value on `session/resume` (or `session/load` in v1). ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? 1. Add `SessionOptionsRequest` and `SessionOptionsResponse`, the `session/options` method constant, and the `options` session capability to the v1 and v2 schemas behind an `unstable_session_options` feature. 2. Add the optional `configOptions` field to the session setup requests for each version behind the same feature, including `session/fork`. 3. Document the method and the initial values on the `session-setup` and `session-config-options` pages in `docs/protocol/v1` and `docs/protocol/v2`, following the version differences above. 4. Update the example Agents and Clients. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why not return config options from `initialize`? Config options can depend on the workspace (project settings) and on authentication (which models an account can use). `initialize` runs before either is known, and it has no `cwd`. ### Why not create a session and close it if the user never prompts? Creating a session has side effects: it can start MCP servers, set up provider state, and add an entry to `session/list`. Clients would need to create and close sessions every time the user opens a "new session" screen or switches workspace. ### Why one capability for both parts? Clients that query options want to send the user's choices back. A separate capability would let an Agent advertise one part without the other, and Clients would need to handle both combinations. ### Why ignore unavailable values instead of rejecting the request? A rejected `session/new` request means the Client has to retry without the values, and the user waits for two round trips. Options can change between `session/options` and `session/new` (for example, a model is removed), so a stale value is an expected case. The response tells the Client what the session actually uses. Malformed values still fail with `-32602`, and so do unsupported value types in v2. Those are Client bugs, not stale state. ### Why doesn't `session/options` take MCP servers? Config options rarely depend on which MCP servers are connected, and starting servers to find out would make `session/options` slow. Servers can take seconds to start, and some need the user to authenticate. The main thing MCP servers contribute before a session exists is prompts that appear as commands, and v2 already treats `availableCommands` from `session/options` as advisory. Clients still pass `mcpServers` on session setup requests. If a later use case needs them, an optional `mcpServers` parameter can be added to `session/options` without breaking existing Clients. ### What if the Agent has to start its runtime to know its options? That is allowed. An Agent that wraps another program may only learn the models, modes, and other options from a running process. It can start one for `session/options` and stop it once it has the answer. The process must not store a session, write to the history of the session named by `sessionId`, or leave anything behind that `session/list` shows. Such an Agent pays the start cost on every call, and anything the runtime does at startup, such as user-configured startup hooks, runs for each call too. This is why Clients should not poll. The rules constrain what the call leaves behind, not the process. An Agent can keep the started runtime and use it for the next `session/new` with the same parameters, as long as no session exists until then. ### Why no notifications for initial values? The setup response carries the resulting values, so a `config_option_update` for them repeats it. For `session/new` and `session/fork`, the Client also learns the session ID from the response. A `session/update` sent before it names a session the Client cannot place, and v2 lets Clients drop such notifications. Anything else the Agent wants to report can follow the response. A v2 session can be active on several connections. The other connections do not see the response, so they get `config_option_update` like for any other change. ### Why a list instead of a map from `configId` to value? The order of entries matters because options can depend on each other. JSON object key order is not reliable across implementations. ### Why does v2 return more than v1? v2 also returns `availableCommands`. v1 session setup responses do not return commands, so `session/options` would be the only place v1 sends commands outside a `session/update` notification. v2 session setup responses already return initial `availableCommands`, so `session/options` can use the same field. ### Why are available commands advisory? Some Agents only know their commands after the session loads: MCP prompts need connected servers, and skills or project commands can change on disk. Requiring a complete list would force Agents to do most of the session setup work in `session/options`. ### Why no initial values for commands? Commands are not settings. The Client runs a command by sending it in a prompt after the session exists. ### What alternative approaches did you consider, and why did you settle on this one? * **Return options from `initialize`.** See above. * **Create sessions eagerly.** See above. * **Separate methods for new and resumed sessions.** The parameters and response are the same apart from `sessionId`, so one method with an optional `sessionId` is enough. * **Accept initial values without a query method.** Clients would not know which option IDs and values exist, so they could only send values they had seen in an earlier session. ## Revision history * 2026-11-03: Initial draft * 2026-11-10: Accept `configOptions` on `session/fork`. Hold back other `session/update` notifications for initial values until the `session/new` or `session/fork` response. In v2, send `config_option_update` on other connections where a resumed session is active. A value the runtime refuses is ignored. An Agent may start its runtime to answer `session/options`, and Clients should not poll it. # Resuming of existing sessions Source: https://agentclientprotocol.com/rfds/session-resume * Author(s): [@josevalim](https://github.com/josevalim) * Champion: [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? We propose adding the ability to resume existing sessions. This is similar to "session/load", except it does not return previous messages. ## Status quo > How do things work today and what problems does this cause? Why would we change things? While the spec provides a "session/load" command, not all coding agents implement it. This means that, once you close your editor, browser, etc, you can't resume the conversation. This is particularly a problem for agents that do not directly implement ACP and the functionality is implemented via a wrapper. In such cases, they may provide the ability to resume (without history), which we would like to hook into. Not only that, resuming could be used as a mechanism for proxies and adapter libraries to emulate "session/load". ## What we propose to do about it > What are you proposing to improve the situation? Add a "session/resume" command and a capability `{ sessionCapabilities: { resume: {} } }`. ## Shiny future > How will things will play out once this feature exists? We will be able to resume existing conversations, providing a better user experience. Not only that, if an agent does not implement "session/load" but it does implement "session/resume", it is now possible to implement a proxy/adapter that intercepts the agents messages and writes them to disk. Now when the client issues a "session/load", the proxy/adapter converts it to a "session/resume", and then returns the stored messages. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Should we introduce a new operation (session/resume) or add an option to (session/load)? A separate method provides a few benefits: * for clients that for whatever reason don't want the history, they can just resume * for agents that can only supply resume, a proxy on top could provide load on top of it, but the agent is still clear on what it supports * for agents who support both, it should be trivial to use the same resume functionality, they just either replay events or do not ### What alternative approaches did you consider, and why did you settle on this one? The biggest question is if it makes sense to support both "session/load" and "session/resume". When we start a new session over ACP, we introduce custom MCP tools and configuration. This means that, while we could use "session/load" to load our own chats, loading third-party chats would likely lead to a flawed user experience, as our tools would not be available. And depending on the ACP implementation, not even the capabilities would be respected (as loading a third-party session would not include our capabilities in its history, misleading the agent). Therefore, if we assume "session/load" is for loading conversations started by the client itself, "session/resume" is effectively a subset of "session/load", decoupled from storage mechanics. If an agent implements "session/load", then it can be used directly, but if it doesn't, a proxy or adapter can provide a reasonable fallback on top of "session/resume". This argues "session/resume" is the basic primitive which "session/load" builds on top of. ## Revision history * 2026-04-22: RFD marked as Completed; `session/resume` is stabilized * 2026-04-14: Update capability shape to `sessionCapabilities.resume` * 2025-11-24: Update FAQ to mention session/resume vs session/load # Client-Set Session Titles Source: https://agentclientprotocol.com/rfds/session-set-title Author(s): [@lifeizhou-ap](https://github.com/lifeizhou-ap) Champion: [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? Add an optional `session/set_title` request that lets a Client set the title of a session. The Agent persists the title as session metadata and returns the title it actually stored, which may be a normalized form of the one the Client supplied. An Agent may generate session titles. After `session/set_title` succeeds, the Agent should not replace the Client-supplied title with one it generates automatically. ## Status quo > How do things work today and what problems does this cause? Why would we change things? ACP allows an Agent to report a session title, through `SessionInfo.title` in `session/list` and through the `session_info_update` notification, but provides no operation for a Client to set one. As a result, a title the user chooses in the Client cannot be stored with the session through ACP, and the Agent's next generated title may replace whatever the Client displays. Agents already support renaming outside ACP. Claude Code has `/rename` and a `renameSession()` SDK function, and the Codex app-server has `thread/name/set`. The claude-agent-acp adapter exposes this through a vendor-specific `_session/rename` extension, so Clients that want renaming today have to target individual adapters. [Issue #1978](https://github.com/agentclientprotocol/agent-client-protocol/issues/1978) identifies the same missing operation while also proposing semantics for Agent-generated titles and an optional initial title. This RFD addresses only the Client-to-Agent operation. ## What we propose to do about it > What are you proposing to improve the situation? Add a capability-gated `session/set_title` request, in both ACP v1 and v2, that lets a Client set the title of a session. The Agent persists the title and returns the stored title in the response. The session does not need to be loaded, so a Client can rename sessions directly from a `session/list` view. ## Shiny future > How will things will play out once this feature exists? A user renames a session in their editor's session list, and the new title shows up wherever that session is listed, including in other Clients connected to the same Agent and in the Agent's own UI. The title stays put: the Agent's title generation no longer replaces it after the next turn. Clients no longer need per-Agent extensions or transcript parsing to keep user-chosen titles. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? ### Protocol The method is added to both ACP v1 and v2. The request, response, and resulting `session_info_update` are identical in both versions; only where the capability is advertised differs. #### Capability In v1, an Agent advertises support through `agentCapabilities.sessionCapabilities.title` in the `initialize` response: ```json theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 1, "agentCapabilities": { "sessionCapabilities": { "title": {} } } } } ``` In v2, an Agent advertises support through `capabilities.session.title` in the `initialize` response: ```json theme={null} { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": 2, "capabilities": { "session": { "title": {} } } } } ``` In both versions, omitting the field or setting it to `null` means the Agent does not support the method, and `{}` means it does. Clients must not call `session/set_title` unless this capability is present. The capability only covers Client-set titles. Agents report titles through `session/list` and `session_info_update` without it. Later title features, such as an initial title on `session/new`, can add fields to this object. #### Request and response The request is the same in v1 and v2: ```json theme={null} { "jsonrpc": "2.0", "id": 42, "method": "session/set_title", "params": { "sessionId": "sess_123", "title": "Investigate OAuth timeout" } } ``` **sessionId** `SessionId` *required* The session to retitle. The session does not need to be loaded on the current connection; any session the Agent would return from `session/list` can be retitled. **title** `string` *required* The new title for the session. Must be present and must not be `null`. There is no way to clear a title or return to an Agent-generated title through this method. The response contains the title the Agent persisted: ```json theme={null} { "jsonrpc": "2.0", "id": 42, "result": { "title": "Investigate OAuth timeout" } } ``` **title** `string` *required* The title as persisted by the Agent. This may differ from the requested title if the Agent normalized it. Clients **SHOULD** display this value rather than the one they sent. #### Validation and normalization * The Agent **MAY** normalize the title before persisting it, for example by trimming surrounding whitespace, collapsing line breaks and repeated whitespace, or truncating it to a maximum length. The response reports the normalized title. * Other validation rules are defined by the Agent. If a title fails validation, including a title that is empty after normalization, the Agent returns `InvalidParams` (`-32602`) with a message explaining why it was rejected. For example: ```json theme={null} { "jsonrpc": "2.0", "id": 42, "error": { "code": -32602, "message": "Title must not be empty." } } ``` * The Agent returns success only after persisting the title. If it cannot do so, it returns an error. #### Errors * If `sessionId` does not identify a session the Agent knows about, the Agent returns `ResourceNotFound` (`-32002`). * An Agent **MAY** refuse to retitle a session it cannot safely update, such as an archived session, an ephemeral session that is not persisted, or a session currently held by another process that would overwrite the new title. In that case it returns an error with a message explaining why. #### Notifications and `session/list` * If the session is loaded, the Agent **MAY** send a `session/update` notification containing a `session_info_update` with the persisted title, for example so that other Clients viewing the session see the change. The requesting Client **SHOULD NOT** depend on this notification; the response already carries the persisted title. The notification uses the existing `session_info_update`, which has the same shape in v1 and v2: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_123", "update": { "sessionUpdate": "session_info_update", "title": "Investigate OAuth timeout" } } } ``` * If the Agent supports `session/list`, later `session/list` results return the persisted title for the session. `session/set_title` does not require `session/list` support; a successful response is enough for the Client to know the title was persisted. #### Agent-generated titles * After `session/set_title` succeeds, the Agent **SHOULD NOT** replace the title with one it generates automatically. This is a SHOULD rather than a MUST because some Agents, such as adapters around an existing CLI, do not fully control when the underlying agent generates titles. * If the Agent is generating a title when `session/set_title` succeeds, it **SHOULD** discard the generated title. * This does not restrict later user-initiated renames through other paths, such as an Agent slash command like `/rename` or another Client calling `session/set_title`. Each successful rename replaces the previous title. * Clients **MAY** call `session/set_title` while a prompt turn is in progress. Retitling does not affect the turn. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why `session/set_title` instead of `session/rename`? It matches the existing `session/set_mode` and `session/set_config_option` methods, and names the field being set. In SDKs it maps to `SetSessionTitleRequest` / `SetSessionTitleResponse` and a `set_session_title` method. ### Why not a general `session/set_info` that mirrors `session_info_update`? `session_info_update` carries `title`, `updatedAt`, and `_meta`, but `updatedAt` is Agent-owned activity data that Clients should not set, and `_meta` already has its own extensibility rules. A dedicated method keeps the semantics narrow: required title, normalization, and protection from generated titles. If more Client-settable session metadata appears later, it can get its own method or a follow-up RFD can generalize this one. ### Why does the response include the title? Agents normalize titles today. claude-agent-acp collapses whitespace and caps titles at 256 characters, and Codex trims names. Returning the persisted title lets the Client display exactly what the Agent stored without waiting for a notification, which may not be sent for sessions that are not loaded. ### Why doesn't the session need to be loaded? The main use case is renaming from a session list, where most sessions are not loaded. Existing implementations already support this: Claude Code appends a custom-title record to the session transcript, and Codex updates thread metadata in its store, without resuming the session. ### Why can't a Client clear a title or go back to a generated title? `title` is required and non-null to keep the method simple. Clearing a title through `session_info_update` (`title: null`) remains something only the Agent does. A reset mechanism can be added later if Clients need it. ### Why is there no `title` on `session/new`? [Issue #1978](https://github.com/agentclientprotocol/agent-client-protocol/issues/1978) also proposes letting a Client supply an initial title when creating a session. This RFD leaves that out; a Client can call `session/set_title` right after `session/new`, and an initial title can be added in a follow-up if needed. ## Revision history * 2026-08-19: Initial proposal. * 2026-10-26: Show v1 and v2 capabilities, return the persisted title in the response, allow normalization, allow retitling sessions that are not loaded, make the notification optional, define errors, and add FAQ. * 2026-10-30: Rename the capability from `setTitle` to `title` so later title features can extend the same object. # Session status Source: https://agentclientprotocol.com/rfds/session-status Author(s): [@chazcb](https://github.com/chazcb) Champion: [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? Add a `session/status` method that lets a Client ask an Agent about a single session without changing anything: * **Open**: the Agent has this session in memory right now. * **Saved**: the Agent knows this session and it can be resumed, but it is not in memory. * **Unknown**: the Agent does not know this session. This is returned as a `-32002` error. `session/status` never loads, resumes, creates, or changes a session. ## Status quo > How do things work today and what problems does this cause? Why would we change things? All the session lifecycle methods change Agent state: * `session/new` creates a session. * `session/load` and `session/resume` make the Agent start handling a session for the connection that sent them. In v2, `session/load` is gone and replay is a `replayFrom` option on `session/resume`. * `session/close` cancels a session's work and frees its resources. `session/list` says which sessions exist, but not which ones the Agent has in memory right now. So a Client has no way to ask "do you have this session right now?" without becoming a participant in it. This matters when: * **A routing layer runs several Agent instances.** It needs to find which instance has a session before it forwards a `session/resume`. Sending `session/resume` to an instance just to find out loads the session there, so two instances could end up running the same session. * **A Client reconnects over a long-lived transport.** After a network drop, it wants to know whether the session is still in memory or the Agent restarted, before deciding how to recover and what to show the user. * **A Client checks a session ID before using it.** Today an unknown ID only shows up as an error from whichever method it used first, and there is no shared error code for it. ## What we propose to do about it > What are you proposing to improve the situation? Add `session/status`, a read-only request from the Client to the Agent. ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "session/status", "params": { "sessionId": "sess_abc123" } } ``` The Agent has the session in memory: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "status": "open" } } ``` The Agent knows the session but does not have it in memory: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "status": "saved" } } ``` The Agent does not know the session: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "error": { "code": -32002, "message": "Resource not found", "data": { "sessionId": "sess_abc123" } } } ``` ### Status values * `open`: The Agent has this session in memory, for any connection. This does **not** mean the requesting connection is attached to it. A Client that did not create or resume the session on its own connection **MUST** still call `session/resume` (or `session/load` in v1) before sending `session/prompt` or expecting `session/update` notifications. * `saved`: The Agent knows the session and can resume it, but it is not in memory. The Client can call `session/resume` (or `session/load` in v1) to start it. Clients **MUST** treat a `status` value they don't recognize as `saved`. That keeps a later status value from being read as permission to skip `session/resume`. ### Foreground state (v2) In v2, an `open` response **SHOULD** also include `state`: the session's current foreground state, using the same `StateUpdate` snapshot the Agent sends in `state_update` notifications (`running`, `idle`, or `requires_action`). `SubagentUpdate.state` already reuses this snapshot the same way. ```json theme={null} { "jsonrpc": "2.0", "id": 1, "result": { "status": "open", "state": { "state": "requires_action" } } } ``` * `state` is optional. If it is omitted, `null`, or malformed, the Agent is not reporting foreground state. Clients **MUST NOT** read that as `idle`. * Like the snapshot `session/resume` sends, this is a snapshot. It is not a new transition, completion, or usage report. An `idle` snapshot may carry the last `stopReason` for context, and Clients **MUST NOT** count it as a new completion. * v1 has no foreground state model, so the v1 response has no `state` field. ### Errors If the Agent does not know the session, it **MUST** return error `-32002` (Resource not found) with the requested `sessionId` in `data`. Unknown session IDs are an error, not a normal answer, so `session/status` reports them the same way other session methods should. ### Contract * `session/status` **MUST NOT** have side effects. It must not load, resume, create, close, or change the session, and it must not attach the requesting connection to it. * Checking whether a session is `open` **SHOULD** be cheap (an in-memory lookup), and Clients may call it often, for example as a routing probe. * Telling `saved` apart from unknown may require a storage lookup. If an Agent cannot do that cheaply, it **MAY** return `saved` for any session it does not have in memory. A later `session/resume` will then fail with `-32002` if the session does not exist. * The result is a snapshot. A session reported `open` may be closed or evicted before the Client's next request, so Clients **MUST** still handle errors from later session methods. ## Shiny future > How will things will play out once this feature exists? * Routing layers ask each Agent instance for `session/status` to find the one with the session `open`, and send `session/resume` there instead of loading it on the wrong instance. * Clients reconnecting over a long-lived transport can tell "the Agent still has my session" from "the Agent restarted and the session needs resuming", and show the right thing right away. * v2 Clients and dashboards can show whether a session is working, idle, or waiting on the user without attaching to it. For example, they can surface a session blocked on a permission request elsewhere. * Agents report unknown session IDs with one error code, which other session methods can adopt too. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? ### Capability `session/status` is optional. Agents advertise it with a session capability marker. v1: ```json theme={null} { "agentCapabilities": { "sessionCapabilities": { "status": {} } } } ``` v2: ```json theme={null} { "capabilities": { "session": { "status": {} } } } ``` Clients **MUST NOT** call `session/status` unless the Agent advertises this capability. Like other session capability markers, an invalid value means the capability is unsupported. ### Schema Following the existing naming rules (`session/status` → `session_status`): * `SessionStatusRequest`: `sessionId` (required), `_meta` (optional). * `SessionStatusResponse`: `status` (required), `_meta` (optional). In v2 only, it also has `state` (optional `StateUpdate`, deserialized with `DefaultOnError`, since a fallback just means no foreground state was reported). * `SessionStatus`: string enum, `open` | `saved`, open to future values (see the unrecognized-value rule above). * `SessionStatusCapabilities`: empty object with optional `_meta`, added as `status` on the v1 `SessionCapabilities` and the v2 session capabilities. ### Plan 1. Add the method behind an `unstable_session_status` feature flag in the v1 and v2 schemas. 2. Document it in the session setup docs, including the `-32002` error. 3. Implement it in at least one Agent and one routing layer or Client before stabilizing. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why not just call `session/resume`? `session/resume` attaches the requesting connection and makes the Agent start handling the session. That is what a Client wants once it has decided where the session should run, but not when it is only asking. A routing layer that probes by resuming loads the session on every instance it asks. ### Why `open` and `saved`? v2 already calls a session "active" on a connection from `session/new`, `session/resume`, or `session/fork` until `session/close` or disconnect. A status of `active` that means "in memory for any connection" would invite Clients to skip `session/resume`. `open` and `saved` follow the session's lifecycle instead: `session/close` frees an `open` session, after which it reads as `saved`, and `session/resume` opens it again. Names describing memory directly, such as `in_memory` or `resident`, and casual pairs such as `hot` / `cold`, were considered and rejected. ### Why is an unknown session an error instead of a `not_found` status? `open` and `saved` are expected answers about a session the Agent knows. An ID the Agent has never seen is a bad request, and other session methods already fail on it. Returning `-32002` here gives that failure one consistent shape instead of a second way to say it. ### Does `open` mean I can send `session/prompt` right away? Only if your connection already created or resumed the session. `open` means the Agent has the session in memory, maybe for another connection. Multi-client attach semantics are covered separately in the [Multi-Client Session Attach RFD](https://github.com/agentclientprotocol/agent-client-protocol/pull/533). ### Why not add this to `session/list`? `session/list` is paged and filtered by `cwd`. It is the wrong tool for a cheap, frequent check on one known ID. Optional row fields on `session/list` (such as a turn `state`) can still exist alongside `session/status`. ### Why is foreground state v2-only? v1 has no foreground state model. Turn completion is only signaled by the `session/prompt` response, so a v1 Agent has no defined snapshot to report. v2 already defines `StateUpdate` and requires `session/resume` to send it, so `session/status` can return the same snapshot without any new semantics. ### Should the response include the session's current position? Not yet. Once message IDs and replay cursors are stable, the response could include the session's current position, so a reconnecting Client can choose a `replayFrom` cursor. That can be added as an optional response field later without breaking this proposal. ### What alternative approaches did you consider, and why did you settle on this one? * **Transport-level heartbeats:** these only show the connection is alive, not that the Agent still has a particular session. * **Probing with `session/resume`:** this has side effects (see above). * **Two states, with unknown sessions as a `not_found` status:** this merges "can be resumed" with "never existed", which a reconnecting Client needs to tell apart. It also reports unknown IDs differently from other session methods. ## Revision history * 2026-10-30: Rename the status values from `active` / `inactive` to `open` / `saved`, since v2 already uses "active" for a session attached to a connection. * 2026-10-26: Reworked to three states (`active` / `inactive` / `-32002` error), dropped the `live` naming so it isn't confused with v2 turn state, pointed recovery at `session/resume`, added v2 capability and connection semantics, added a v2-only `state` foreground snapshot on `active` responses, and made the contract a snapshot rather than a guarantee. * 2026-04-15: Initial draft. # Session Context Size and Cost Source: https://agentclientprotocol.com/rfds/session-usage * Author(s): [@ahmedhesham6](https://github.com/ahmedhesham6) * Champion: [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? Add a standardized `usage_update` session notification that lets agents report the current context window utilization and optional cumulative session cost. This RFD is intentionally scoped to session-level context size and cost. End-turn token accounting is covered separately in the [End-Turn Token Usage RFD](/rfds/end-turn-token-usage). ## Status quo > How do things work today and what problems does this cause? Why would we change things? ACP currently has no standardized way for agents to communicate: 1. **Context window status** - How much of the model's context window is being used 2. **Cost information** - Estimated cumulative cost for API usage This creates several problems: * **No context management** - Clients cannot warn users when a session is approaching context limits or suggest compaction * **No cost transparency** - Users cannot track spending or estimate whether a long-running session should continue * **Inconsistent implementations** - Each agent reports context and cost differently, if it reports them at all Common AI coding tool behavior suggests users benefit from: * Context percentage indicators such as "19%" * Absolute token details such as "31.4K of 200K tokens" * Warning thresholds around high context utilization * Auto-compaction or handoff suggestions near context limits * Cumulative session cost tracking rather than only per-turn cost breakdowns ## What we propose to do about it > What are you proposing to improve the situation? Agents send context window and cost information via `session/update` notifications with `sessionUpdate: "usage_update"`: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123", "update": { "sessionUpdate": "usage_update", "used": 53000, "size": 200000 } } } ``` ### Context Window Fields * `used` (number, required) - Tokens currently in context * `size` (number, required) - Total context window size in tokens Clients can compute `remaining` as `size - used` and `percentage` as `used / size * 100`. If a model has a dynamic context window, agents should report the current effective limit and send another `usage_update` if that limit changes. If an agent cannot provide a meaningful context window size, it should not send `usage_update`; this RFD does not define a `null` or omitted `size` state. ### Cost Field * `cost` (object, optional, nullable) - Cumulative session cost * `amount` (number, required) - Total cumulative cost for the session * `currency` (string, required) - ISO 4217 currency code, such as `"USD"` or `"EUR"` Example with optional cost: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_abc123", "update": { "sessionUpdate": "usage_update", "used": 53000, "size": 200000, "cost": { "amount": 0.045, "currency": "USD" } } } } ``` Agents send updates when they have current data available: * After `session/new`, once the session ID exists * After `session/load`, `session/resume`, or `session/fork` for restored sessions * After `session/prompt`, when usage data becomes available * Anytime context window state or cumulative cost changes significantly This approach provides flexibility for different agent implementations: * Agents that can query current usage without a prompt can send updates immediately after session setup * Agents that only receive usage data while prompting can send updates after prompt completion * Agents that cannot calculate cost can still report context window status ### Design Principles 1. **Session state** - Context size and cumulative cost describe the session, not one prompt response 2. **Agent-pushed notifications** - Agents proactively send updates when data becomes available, following the same pattern as dynamic session properties such as `available_commands_update`, `current_mode_update`, and `session_info_update` 3. **Agent calculates, client can verify** - Agents know their model and tokenizer best, but expose raw values so clients can compute derived display values 4. **Flexible cost reporting** - Cost is optional because not all agents track it, and the currency is explicit because agents may bill in different currencies 5. **Optional but recommended** - Context and cost reporting remains optional to preserve compatibility ## Shiny future > How will things will play out once this feature exists? **For Users:** * **Visibility**: Users see current context window usage with percentage indicators * **Cost awareness**: Users can track cumulative spending at any time * **Better planning**: Users know when to start a new session, compact context, or hand off work * **Transparency**: Users get a consistent view of resource consumption across agents **For Client Implementations:** * **Consistent UI**: Clients can show usage through standard progress indicators, detail hovers, and warning states * **Smart warnings**: Clients can warn users as sessions approach high context utilization * **Cost controls**: Clients can implement budget alerts and session-level spend displays * **Reactive updates**: Clients update UI immediately when agents push new data * **No polling needed**: Clients do not need a separate status request to keep context displays current **For Agent Implementations:** * **Standard reporting**: Agents get a clear contract for reporting context window and cost state * **Flexibility**: Agents can report only the cost information they can calculate * **Model diversity**: The shape works across providers and local models ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? 1. Add a `UsageUpdate` variant to `SessionUpdate` with discriminator `sessionUpdate: "usage_update"`. 2. Add a `Cost` type with `amount` and `currency` fields. 3. Gate this Rust crate surface behind the `unstable_session_usage` feature. 4. Document the `session/update` notification variant in the protocol docs. 5. Add examples showing when agents should send context window and cost updates. This RFD does not add end-turn token usage to the turn-completion signal. That proposal remains in draft in the [End-Turn Token Usage RFD](/rfds/end-turn-token-usage). ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why split this from end-turn token usage? Context window size and cumulative cost are session-level state that clients may need before, during, or after a prompt. Token accounting for a completed turn has different open questions, including whether values should be per-turn or cumulative and how cache metrics should map across providers. ### How do users know when to hand off or compact context? The `usage_update` notification provides the raw values clients need: * `used` and `size` give absolute numbers for precise tracking * Clients can compute `remaining` as `size - used` * Clients can compute `percentage` as `used / size * 100` **Recommended client behavior:** | Percentage | Action | | - | - | | \< 75% | Normal operation | | 75-90% | Yellow indicator, suggest "Context filling up" | | 90-95% | Orange indicator, recommend "Start new session or summarize" | | > 95% | Red indicator, warn "Next prompt may fail - handoff recommended" | ### Why is cost in `session/update` instead of the turn-completion signal? Cost is cumulative session state, similar to context window utilization: * Users usually want total spending, not only per-turn costs * Both cost and context window are session-level metrics that can change when agents compact, switch models, or restore sessions * Cost is optional because not all agents track it ### Why not assume USD for cost? Agents may bill in different currencies: * European agents might bill in EUR * Asian agents might bill in JPY or CNY * Currency conversion rates change Agents should report the actual billing currency and let clients convert if needed. ### How does this work with streaming responses? Agents may send `usage_update` notifications during streaming if context state changes and they have reliable current data. They should also send an update after prompt completion when final context size or cost data becomes available. ### What about models without fixed context windows? Agents should report the current effective context window size. For models with dynamic windows, agents should report the current limit and send another update if it changes. If there is no meaningful context window size, agents should not send `usage_update`; `size` is required and non-null. ### What about rate limits and quotas? This RFD focuses on context window utilization and cumulative cost. Rate limits and quotas are separate concerns that could be addressed in a future RFD. ### Should cached tokens count toward context window usage? Yes. Cached tokens still occupy context window space even when they are cheaper to process. Context window usage should include all tokens currently in context. ### Why a notification instead of a request? Using `session/update` notifications instead of a `session/status` request provides several benefits: 1. **Consistency**: Follows the same pattern as other dynamic session properties 2. **Agent flexibility**: Agents can send updates when they have data available 3. **No polling**: Clients receive updates reactively 4. **Real-time updates**: Updates flow naturally as part of the session lifecycle ### What if the client connects mid-session? When a client connects to an existing session through `session/load` or `session/resume`, agents should send a `usage_update` notification if they have current context window data available. This lets the client UI immediately display accurate context and cost information. For agents that only provide usage during active prompting, the client UI may not show usage until after the first prompt is sent. ### What alternative approaches did you consider, and why did you settle on this one? **Everything in the turn-completion signal** - Simpler, but context window and cost are session state that users may want independently of prompt turns. **Request/response with `session/status`** - Requires clients to poll, and some agents do not have APIs to query current status without a prompt. **Client calculates everything** - Rejected because clients do not know the agent's tokenizer, exact context window size, model routing, or pricing. **Only percentage, no raw tokens** - Rejected because users want absolute numbers, clients cannot verify calculations, and it is less transparent. ## Revision history * 2025-12-07: Initial draft * 2025-12-13: Changed from `session/status` request method to `session/update` notification with `sessionUpdate: "context_update"`. Made `cost` optional and removed `remaining` field (clients can compute as `size - used`). This approach provides more flexibility for agents and follows the same pattern as other dynamic session properties. * 2025-12-17: Renamed `reasoning_tokens` to `thought_tokens` for consistency with ACP terminology. Removed `percentage` field (clients can compute as `used / size * 100`). * 2025-12-19: Renamed `sessionUpdate: "context_update"` to `sessionUpdate: "usage_update"` to better reflect the payload semantics (includes both context window info and cumulative cost). * 2026-06-02: Split end-turn token accounting into a separate draft RFD. * 2026-06-03: Moved to Preview. * 2026-06-05: Moved to Completed. # Streamable HTTP & WebSocket Transport Source: https://agentclientprotocol.com/rfds/streamable-http-websocket-transport * Author(s): [alexhancock](https://github.com/alexhancock), [jh-block](https://github.com/jh-block) * Champion: [anna239](https://github.com/anna239) ## Elevator pitch > What are you proposing to change? ACP needs a standard remote transport. We propose **long-lived GET streams** for server→client messages (one connection-scoped plus one per session), with **POST** for client→server messages, and **WebSocket upgrade** as an alternative on the same endpoint. A single `/acp` endpoint supports two connectivity profiles: * **Streamable HTTP (POST/GET/DELETE)** — Long-lived SSE streams per connection: one connection-scoped stream for connection-level server→client messages, plus one session-scoped stream per session for session-level messages. POST requests return immediately (202 Accepted, except `initialize`). Requires HTTP/2. * **WebSocket upgrade (GET with `Upgrade: websocket`)** — persistent, full-duplex, low-latency bidirectional messaging. Clients that support remote ACP over HTTP MUST support both Streamable HTTP and WebSocket. This allows servers to support only WebSocket if they choose, simplifying deployment. Both profiles share the same JSON-RPC message format and ACP lifecycle as the existing **stdio** local subprocess transport. ## Status quo > How do things work today and what problems does this cause? Why would we change things? ACP only has stdio. There is no standard remote transport, which causes fragmentation as implementers invent their own HTTP layers, leading to incompatible SDKs and deployments. ## What we propose to do about it > What are you proposing to improve the situation? ### 1. Adds an HTTP Transport ACP adopts a streamable HTTP transport with three key characteristics: 1. **Long-lived GET streams (one connection-scoped, one per session)** — All server→client messages (responses to requests and unsolicited notifications) are delivered via SSE streams opened with GET. The **connection-scoped stream** (scoped to `Acp-Connection-Id`) carries connection-level messages: responses to `session/new` and `session/load` (which the client cannot receive on a session-scoped stream because it does not yet have a `sessionId`), and any server-initiated messages not tied to a specific session. The **session-scoped stream** (scoped to `Acp-Connection-Id` + `Acp-Session-Id`) carries all messages for a single session: session update notifications, server-to-client requests like `request_permission`, and responses to session-scoped POSTs like `session/prompt` and `session/cancel`. Responses are correlated to the POST that originated them by JSON-RPC `id`. 2. **POST requests return immediately (except initialize)** — Client→server messages are sent via POST. Most POST requests return `202 Accepted` immediately with an empty body. The actual response comes later on the appropriate GET stream, correlated by JSON-RPC `id`. The `initialize` request is special: it returns `200 OK` with a JSON response body containing capabilities and the `Acp-Connection-Id`. The `Acp-Connection-Id` is also included in the response header. 3. **Requires HTTP/2** — Streamable HTTP transport MUST use HTTP/2. This provides multiplexing for concurrent POST requests while maintaining long-lived GET streams (one connection-scoped plus one per session), and improves efficiency for high-frequency message exchanges. ### 4. Adds WebSocket as a first-class upgrade on the same endpoint A GET with `Upgrade: websocket` upgrades to a persistent bidirectional channel — same endpoint, same lifecycle model. This is important for ACP, as it is more bidirectional in its nature as a protocol. ### 5. Requires cookie support on HTTP transports Clients MUST accept, store, and return cookies set by the server on all HTTP-based transports (Streamable HTTP and WebSocket). Cookies MUST be sent on subsequent requests to the server for the duration of the connection. Clients MAY discard all cookies when a connection is terminated. This allows servers to rely on cookies for session affinity (e.g., sticky sessions behind a load balancer) and other small amounts of per-connection state. ### 6. Defines a unified routing model | Method | Upgrade Header? | Behavior | | - | - | - | | `POST` | — | Send JSON-RPC message. `initialize` returns 200 with JSON body. All others return 202 Accepted immediately. | | `GET` | No | Open SSE stream. `Acp-Connection-Id` alone → connection-scoped stream. `Acp-Connection-Id` + `Acp-Session-Id` → session-scoped stream. | | `GET` | `Upgrade: websocket` | Upgrade to WebSocket for full-duplex messaging | | `DELETE` | — | Terminate the connection | ### 7. Preserves the full ACP lifecycle The `initialize` → `initialized` → messages → close lifecycle is identical regardless of transport. The `Acp-Connection-Id` binds requests to the initialized connection and its negotiated capabilities. Session identity is carried in JSON-RPC message bodies via the `sessionId` field. ## Durability and reliability expectations > What guarantees does this transport make, and what is deferred? This RFD is targeted for inclusion in **v1** as an additive feature, with more robust durability and reliability primitives coming in **v2**. The lists below clarify what implementers can expect from using the HTTP/WS transport in different versions of ACP ### v1 In v1, durability and reliability are the implementer's responsibility — the protocol provides the building blocks, not the guarantees. Specifically, you can expect: * **Sessions survive disconnects.** A session persists on the server independently of any one connection, so after a dropped connection a client can reconnect and resume it via `session/load`. * **Session affinity is preserved across reconnects.** Required client cookie support lets a load balancer route a reconnecting client back to the same backend; deployments without native sticky sessions can supply affinity themselves using an external store such as Redis keyed by connection/session ID. * **Reconnect and retry are up to the implementer.** Detecting a dropped connection and re-establishing it is handled at the SDK/host layer, optionally via a local proxy. * **Liveness detection is up to the implementer.** Keeping intermediaries from timing out and detecting half-open or unresponsive connections is done with SDK/host-level transport and application ping/pong, not by the protocol. * **In-flight messages are not replayed.** There is no message sequencing or stream resumption, so server→client messages emitted while a client was disconnected are not redelivered on reconnect. ### v2 These are requirements of this transport and its SDKs, not changes to the core v2 messages, so they can land after v2 without breaking it. Message IDs and the update lifecycle are already part of core v2. * **Message IDs on streamed messages.** Streamed message chunks carry IDs (a "last replay ID"), enabling reliable retry and resumption after a reconnect. * **Stream resumability.** SSE `Last-Event-ID`-style resumption lets a reconnecting client replay messages missed while disconnected. * **Defined reconnection semantics.** Reconnection scenarios are addressed by the protocol/SDKs rather than left entirely to each implementer. * **More reliable notification update cycles.** v2 tightens the update/notification lifecycle to reduce lost or out-of-order updates. * **Standardized keepalive.** Transport-level ping/pong, plus an additive application-level ping if needed, become part of this transport's reliability story, enabling more sophisticated awareness by both client and server of when the other end has crashed. ## Shiny future > How will things play out once this feature exists? * **SDK implementers** get a clear, testable transport spec — Rust, TypeScript, and Python SDKs can all interoperate. * **Desktop clients** use WebSocket for low-latency streaming; all clients support it as a baseline. * **Cloud deployments** expose agents behind standard HTTP load balancers using the stateless-friendly HTTP mode, with cookie-based sticky sessions guaranteed by client support. * **Proxy chains** can route ACP traffic over HTTP for multi-hop agent topologies. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? ### Transport Architecture ``` ┌─────────────────────────────────┐ │ /acp endpoint │ └──────┬──────────┬───────────────┘ │ │ ┌───────────▼──┐ ┌────▼──────────────┐ │ HTTP State │ │ WebSocket State │ │(connections) │ │ (connections) │ └───────┬──────┘ └────┬──────────────┘ │ │ ┌───────▼──────────────▼───────────────┐ │ ACP Agent (JSON-RPC handler) │ │ serve(agent, read, write) │ └─────────────────────────────────────┘ ``` ### Identity Model ACP over Streamable HTTP uses two HTTP headers for connection and session identity, plus JSON-RPC message fields: * **`Acp-Connection-Id`** (HTTP header) — Transport-level identifier returned by the server in the `initialize` response. Required on all HTTP requests after `initialize` and on every GET stream (both connection-scoped and session-scoped). Binds requests to an initialized connection and its negotiated capabilities. * **`Acp-Session-Id`** (HTTP header) — Session-level identifier returned in the `session/new` response body. Required on all session-scoped POST requests (`session/prompt`, `session/cancel`, permission responses, etc.) and on the session-scoped GET stream. * **`sessionId`** (JSON-RPC field) — Session-level identifier also included in JSON-RPC `params` for session-scoped methods and in responses on the GET streams. A single connection may host multiple sessions, each with its own `sessionId` and its own session-scoped GET stream. ### Streamable HTTP Message Flow ``` Client Server │ │ │ ═══ Connection Initialization ═══ │ │ │ │─── POST /acp ─────────────────────>│ { method: "initialize", id: 1 } │ Content-Type: application/json │ (no Acp-Connection-Id header) │ │ │<────── 200 OK ─────────────────────│ { id: 1, result: { capabilities, connectionId } } │ Acp-Connection-Id: │ Response includes Acp-Connection-Id header │ Content-Type: application/json │ │ │ │ ═══ Open Connection-Scoped GET ═══│ │ │ │─── GET /acp ──────────────────────>│ Open long-lived connection-scoped SSE stream │ Acp-Connection-Id: │ for connection-level server→client messages │ Accept: text/event-stream │ (no Acp-Session-Id header) │ ┌─────────────────────│ (SSE stream open) │ │ │ │ │ │ │ ═══ Session Creation ═══ │ │ │ │─── POST /acp ─────────────────────>│ { method: "session/new", id: 2, │ Acp-Connection-Id: │ params: { cwd, mcpServers } } │ │ │<────── 202 Accepted ───────────────│ (returns immediately) │ │ │ │<─────────────│─ SSE event ─────────│ { id: 2, result: { sessionId: "sess_abc123" } } │ │ │ (response on connection-scoped stream) │ │ │ │ ═══ Open Session-Scoped GET ═══ │ │ │ │─── GET /acp ──────────────────────>│ Open long-lived session-scoped SSE stream │ Acp-Connection-Id: │ for sess_abc123 │ Acp-Session-Id: sess_abc123 │ │ Accept: text/event-stream │ │ ┌─────────────────────│ (SSE stream open) │ │ │ │ ═══ Prompt Flow ═══ │ (all events below arrive on the session-scoped stream) │ │ │─── POST /acp ─────────────────────>│ { method: "session/prompt", id: 3, │ Acp-Connection-Id: │ params: { sessionId: "sess_abc123", prompt } } │ Acp-Session-Id: sess_abc123 │ │ │ │<────── 202 Accepted ───────────────│ (returns immediately) │ │ │ │<─────────────│─ SSE event ─────────│ notification: AgentMessageChunk (sessionId: "sess_abc123") │<─────────────│─ SSE event ─────────│ notification: AgentThoughtChunk (sessionId: "sess_abc123") │<─────────────│─ SSE event ─────────│ notification: ToolCall (sessionId: "sess_abc123") │<─────────────│─ SSE event ─────────│ notification: ToolCallUpdate (sessionId: "sess_abc123") │<─────────────│─ SSE event ─────────│ notification: AgentMessageChunk (sessionId: "sess_abc123") │<─────────────│─ SSE event ─────────│ { id: 3, result: { sessionId: "sess_abc123", ... } } │ │ │ (response comes on GET stream) │ │ │ │ ═══ Permission Flow ═══ │ │ (when tool requires confirmation) │ │ │ │─── POST /acp ─────────────────────>│ { method: "session/prompt", id: 4, ... } │ Acp-Connection-Id: │ │ Acp-Session-Id: sess_abc123 │ │ │ │<────── 202 Accepted ───────────────│ │ │ │ │<─────────────│─ SSE event ─────────│ notification: ToolCall (sessionId: "sess_abc123") │<─────────────│─ SSE event ─────────│ { method: "request_permission", id: 99, │ │ │ params: { sessionId: "sess_abc123", ... } } │ │ │ (server-to-client request) │─── POST /acp ────────────────────>│ { id: 99, result: { outcome: "allow_once" } } │ Acp-Connection-Id: │ (client response) │ Acp-Session-Id: sess_abc123 │ │ │ │<────── 202 Accepted ───────────────│ │ │ │ │<─────────────│─ SSE event ─────────│ notification: ToolCallUpdate (sessionId: "sess_abc123") │<─────────────│─ SSE event ─────────│ { id: 4, result: { sessionId: "sess_abc123", ... } } │ │ │ (response comes on GET stream) │ │ │ │ ═══ Cancel Flow ═══ │ │ │ │─── POST /acp ─────────────────────>│ { method: "session/prompt", id: 5, ... } │ Acp-Connection-Id: │ │ Acp-Session-Id: sess_abc123 │ │ │ │<────── 202 Accepted ───────────────│ │ │ │ │<─────────────│─ SSE event ─────────│ notification: AgentMessageChunk (sessionId: "sess_abc123") │ │ │ │─── POST /acp ─────────────────────>│ { method: "session/cancel", │ Acp-Connection-Id: │ params: { sessionId: "sess_abc123" } } │ Acp-Session-Id: sess_abc123 │ │ │ │<────── 202 Accepted ───────────────│ (notification, no id) │ │ │ │<─────────────│─ SSE event ─────────│ { id: 5, result: { sessionId: "sess_abc123", ... } } │ │ │ (response comes on GET stream) │ │ │ │ ═══ Resume Session Flow ═══ │ │ (new connection, existing session)│ │ │ │─── POST /acp ─────────────────────>│ { method: "initialize", id: 1 } │ (no Acp-Connection-Id) │ New connection │<────── 200 OK ─────────────────────│ { id: 1, result: { capabilities, connectionId } } │ Acp-Connection-Id: │ │ │ │─── GET /acp ──────────────────────>│ Open new connection-scoped GET stream │ Acp-Connection-Id: │ │ ┌─────────────────────│ (SSE stream open) │ │ │ │─── GET /acp ──────────────────────>│ Open session-scoped GET stream for sess_abc123 │ Acp-Connection-Id: │ │ Acp-Session-Id: sess_abc123 │ │ ┌─────────────────────│ (SSE stream open) │ │ │ │─── POST /acp ─────────────────────>│ { method: "session/load", id: 2, │ Acp-Connection-Id: │ params: { sessionId: "sess_abc123", cwd } } │ Acp-Session-Id: sess_abc123 │ │ │ │<────── 202 Accepted ───────────────│ │ │ │ │<─────────────│─ SSE event ─────────│ notification: UserMessageChunk (on session-scoped stream) │<─────────────│─ SSE event ─────────│ notification: AgentMessageChunk (on session-scoped stream) │<─────────────│─ SSE event ─────────│ notification: ToolCall (on session-scoped stream) │<─────────────│─ SSE event ─────────│ notification: ToolCallUpdate (on session-scoped stream) │<─────────────│─ SSE event ─────────│ { id: 2, result: { sessionId: "sess_abc123" } } │ │ │ (response on connection-scoped stream) │ │ │ │ ═══ Connection Termination ═══ │ │ │ │─── DELETE /acp ───────────────────>│ Terminate connection │ Acp-Connection-Id: │ │<────────── 202 Accepted ───────────│ │ ▼ │ (GET stream closes) ``` #### Content Negotiation and Validation * POST `Content-Type` **MUST** be `application/json` (415 otherwise). * GET `Accept` **MUST** include `text/event-stream` (406 otherwise). * POST requests for session-scoped operations **MUST** include both `Acp-Connection-Id` and `Acp-Session-Id` headers. * GET requests without `Upgrade: websocket` **MUST** include `Acp-Connection-Id`. If `Acp-Session-Id` is also present, the stream is session-scoped; otherwise it is connection-scoped. An unknown `Acp-Session-Id` for the given connection returns 404. * ACP does not use JSON-RPC batches. A POST body that is a JSON array returns `400 Bad Request` with a single JSON-RPC error response (`-32600`, `id: null`), and none of its entries are processed. * HTTP/2 is **REQUIRED** for Streamable HTTP transport. ### WebSocket Request Flow #### Connection Establishment (GET with Upgrade) ``` Client Server │ GET /acp │ │ Upgrade: websocket │ │────────────────────────────────────────►│ │ HTTP 101 Switching Protocols │ │ Acp-Connection-Id: │ │◄────────────────────────────────────────│ │ ══════ WebSocket Channel ══════════════│ ``` A new connection is created on upgrade. The `Acp-Connection-Id` is returned in the upgrade response headers. The client must still send `initialize` as the first JSON-RPC message over the WebSocket to negotiate capabilities before creating sessions. #### Bidirectional Messaging All messages are WebSocket text frames containing a single JSON-RPC message. Binary frames are ignored. A frame containing a JSON array gets a single JSON-RPC error response (`-32600`, `id: null`), and none of its entries are processed. On disconnect, the server cleans up the connection and any associated sessions. ### Unified Endpoint Routing ``` GET /acp ├── Has Upgrade: websocket? → WebSocket handler └── No → SSE stream handler ├── Missing Acp-Connection-Id? → 400 Bad Request ├── Unknown Acp-Connection-Id? → 404 Not Found ├── Has Acp-Session-Id unknown for this connection? → 404 Not Found ├── Has Acp-Session-Id → Open session-scoped SSE stream └── No Acp-Session-Id → Open connection-scoped SSE stream POST /acp ├── Initialize request (no Acp-Connection-Id)? → Create connection, return 200 with JSON ├── No Acp-Connection-Id? → 400 Bad Request ├── Unknown Acp-Connection-Id? → 404 Not Found ├── Session-scoped request missing Acp-Session-Id? → 400 Bad Request └── Has valid Acp-Connection-Id (and Acp-Session-Id if required) → Forward to agent, return 202 Accepted DELETE /acp ├── Has Acp-Connection-Id? → Terminate connection and all associated sessions, return 202 └── No Acp-Connection-Id? → 400 Bad Request ``` ### Connection and Session Model ``` Connection { connection_id: String, // Acp-Connection-Id capabilities: NegotiatedCapabilities, sessions: HashMap, // keyed by sessionId (JSON-RPC field) get_stream: Option, // Connection-scoped GET stream to_agent_tx: mpsc::Sender, from_agent_rx: Arc>>, handle: JoinHandle<()>, } Session { session_id: String, // sessionId (JSON-RPC field) get_stream: Option, // Session-scoped GET stream // session-specific state } ``` The agent task is spawned once per connection. Server→client messages are routed to either the connection-scoped GET stream or the appropriate session-scoped GET stream based on whether the message is tied to a specific session. Sessions are identified by the `sessionId` field in JSON-RPC messages. The transport layer adapts channels to the wire format (SSE events for HTTP, text frames for WebSocket). ### Comparing to MCP Streamable HTTP | MCP Requirement | ACP Implementation | Status | | - | - | - | | POST for all client→server messages | ✅ | Compliant | | Accept header validation (406) | ✅ | Compliant | | Notifications/responses return 202 | ✅ (except `initialize` returns 200) | Mostly compliant | | Requests return SSE stream | ❌ (long-lived GET streams instead) | Documented deviation | | Session ID on initialize response | ✅ (`Acp-Connection-Id`) | Compliant (renamed) | | Session ID required on subsequent requests | ✅ (`Acp-Connection-Id` + `Acp-Session-Id`) | Compliant (extended) | | GET opens SSE stream | ✅ (connection-scoped + session-scoped) | Compliant (extended) | | DELETE terminates session | ✅ (terminates connection) | Compliant | | 404 for unknown sessions | ✅ (unknown connection IDs) | Compliant | | Batch requests | ❌ (rejected with `-32600`) | Documented deviation | | Resumability (Last-Event-ID) | ❌ | Deferred to v2 | | Protocol version header | ❌ | Future work | ### Deviations from MCP Streamable HTTP 1. **Long-lived GET streams (connection-scoped + per-session)**: MCP opens a new SSE stream for each request response. ACP uses long-lived GET streams per connection — one connection-scoped stream plus one session-scoped stream per session. POST requests (except `initialize`) return 202 Accepted immediately, and responses arrive on the appropriate GET stream correlated by JSON-RPC `id`. 2. **Initialize returns JSON directly**: MCP's `initialize` returns an SSE stream. ACP's `initialize` returns `200 OK` with a JSON response body containing capabilities and `connectionId`. The `Acp-Connection-Id` is also included in the response header. 3. **HTTP/2 required**: ACP requires HTTP/2 for multiplexing concurrent POST requests alongside the long-lived GET stream. 4. **Two-header model**: ACP uses both `Acp-Connection-Id` (for connection identity) and `Acp-Session-Id` (for session identity on POST requests and on the session-scoped GET stream). MCP only uses `Mcp-Session-Id`. This allows ACP to distinguish connection-level state from session-level operations while supporting multiple concurrent sessions on one connection. 5. **WebSocket extension**: MCP doesn't define WebSocket. ACP adds it as a required client capability. Clients MUST support WebSocket, and servers MAY choose to only support WebSocket connections. 6. **Cookie support required**: Clients MUST handle cookies on HTTP transports for the duration of the connection, enabling sticky sessions and per-connection server state. 7. **No batch requests**: ACP does not use JSON-RPC batches, so a JSON array is rejected with `400 Bad Request` and a `-32600` error response with `id: null`. 8. **No resumability yet in reference implementation**: SSE event IDs and `Last-Event-ID` resumption are deferred to v2 (see [Durability and reliability expectations](#durability-and-reliability-expectations)). ### Implementation Plan 1. **Phase 1 — Specification** (this RFD): Define the transport spec and align terminology. 2. **Phase 2 — Reference Implementation** (in progress): Working implementation in Goose (`block/goose`). 3. **Phase 3 — SDK Support**: Add Streamable HTTP and WebSocket client support to Rust SDK (`sacp`), then TypeScript SDK. 4. **Phase 4 — Hardening**: Origin validation, `Acp-Protocol-Version`, SSE resumability, security audit. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why not just use MCP Streamable HTTP as-is? MCP opens a new SSE stream for each request response, which creates many short-lived connections and complicates load balancing. ACP uses long-lived GET streams per connection (one connection-scoped plus one per session), dramatically reducing connection count and simplifying sticky session routing. This is better suited for ACP's bidirectional, multi-session nature. ### How are sessions identified? ACP uses `Acp-Connection-Id` in HTTP headers to identify the connection, and `Acp-Session-Id` (plus the `sessionId` JSON-RPC field) to identify sessions. A single connection may host multiple sessions. The connection-scoped GET stream delivers connection-level messages; each session-scoped GET stream delivers messages for exactly one session. ### Why add WebSocket support? ACP is highly bidirectional with frequent streaming updates. WebSocket provides true bidirectional messaging with lower per-message overhead than HTTP. Clients MUST support WebSocket so that servers can choose to only support WebSocket connections, simplifying deployment. Streamable HTTP remains available as an additional option for environments where WebSocket is not viable on the server side (e.g., serverless). ### How does the server distinguish WebSocket from SSE on GET? By inspecting the `Upgrade: websocket` header. This is standard HTTP behavior. ### Can a client have multiple sessions on one connection? Yes. A client may call `session/new` multiple times within a single `Acp-Connection-Id`. Each returns a distinct `sessionId` in the response body (delivered on the connection-scoped GET stream). For each session, the client opens a separate session-scoped GET stream using `Acp-Connection-Id` + `Acp-Session-Id`. ### What alternative approaches did you consider, and why did you settle on this one? * **Per-request SSE streams (like MCP)**: Rejected — creates too many long-lived connections, complicates load balancing, and wastes resources. * **Separate endpoints** (`/acp/http`, `/acp/ws`): Rejected — single endpoint is simpler; WebSocket upgrade is natural HTTP. * **WebSocket only**: Rejected — doesn't work through all proxies. * **Single connection-scoped GET stream with JSON-RPC demuxing**: Rejected — forces both server and client to parse JSON-RPC bodies to route by session, couples all sessions' backpressure together, and makes per-session resume/reconnect awkward. Splitting into a connection-scoped stream plus per-session streams keeps all session-level routing on HTTP headers. ### How does this interact with authentication? [ACP authentication](/protocol/v2/authentication) is orthogonal and layered on top via HTTP headers, query parameters, or WebSocket subprotocols. `Acp-Connection-Id` and `Acp-Session-Id` are transport-level identifiers, not auth tokens. ### What about the `Acp-Protocol-Version` header? Clients SHOULD include it on all requests after initialization. Not yet implemented; part of Phase 4 hardening. ### Why require HTTP/2? HTTP/2 provides multiplexing, allowing many concurrent POST requests alongside the long-lived GET streams (one connection-scoped plus one per active session) on a single TCP connection. This is essential for efficient operation with the long-lived-stream model. HTTP/1.1 would require separate TCP connections for each concurrent POST and each GET stream, defeating the efficiency gains. ## Revision history * **2026-10-30**: ACP no longer uses JSON-RPC batches. A JSON array is rejected with a single `-32600` error response with `id: null` (with `400 Bad Request` over HTTP) instead of `501`, and batch support is no longer planned. * **2026-10-29**: Clarified that the v2 reliability features are requirements of this transport, not changes to core v2 messages, so the transport does not block v2. * **2026-07-02**: Moved to Active to reflect current Transports Working Group focus. * **2026-06-05**: Added a "Durability and reliability expectations" section splitting out what implementers can expect in v1 (sessions survive disconnects, session affinity is preserved across reconnects, and reconnect/retry/liveness are the implementer's responsibility with no in-flight message replay) versus v2 (message IDs, stream resumability, defined reconnection semantics, more reliable notification cycles, and standardized keepalive). Marked Last-Event-ID resumability as deferred to v2. * **2026-05-04**: Split the single GET stream into two: a connection-scoped stream (GET with `Acp-Connection-Id`) for connection-level messages such as responses to `session/new` and `session/load`, and session-scoped streams (GET with `Acp-Connection-Id` + `Acp-Session-Id`) for session updates, server-to-client requests like `request_permission`, and responses to session-scoped POSTs. Routing happens on HTTP headers rather than JSON-RPC body inspection; per-session streams have independent lifetimes. * **2026-04-23**: Major revision to single long-lived GET stream model. Changed from per-request SSE streams to a single connection-scoped GET stream for all server→client messages. POST requests (except `initialize`) now return 202 Accepted immediately. `initialize` returns 200 OK with JSON response body. Required HTTP/2 for multiplexing. This change makes the HTTP usage more similar to WebSocket and supports better the bidirectional nature of ACP. * **2026-04-15**: Minor edits * **2026-04-01**: Introduced a two-header identity model: `Acp-Connection-Id` (returned at `initialize`, binds to the connection) and `Acp-Session-Id` (returned at `session/new`, scopes to a session). This addresses feedback that the original single `Acp-Session-Id` conflated transport binding with ACP session identity, and enables session-scoped GET listener streams for targeted server-to-client event delivery. Removed connection-scoped GET streams — all GET SSE listeners now require both `Acp-Connection-Id` and `Acp-Session-Id`. * **2025-03-10**: Initial draft based on the RFC template and goose reference implementation. # Subagent Sessions Source: https://agentclientprotocol.com/rfds/subagents RFD for exposing agent-created subagents as restricted ACP sessions Author(s): Vadim Briliantov, Ben Brandt ## Elevator pitch > What are you proposing to change? Allow an Agent to expose subagents that it creates when delegating work. Each subagent is represented by its own ACP session ID, so its messages, thoughts, plans, tool calls, and current work can be displayed independently from the parent session. The Agent associates a reusable child session with its parent through an upsert-style `subagent_update`. Child events then flow automatically on the same connection. Messages between sessions use `session_message` upserts, which carry optional sender and recipient metadata, and `session_message_chunk` notifications with normal message content, rather than tool-call content. The association is not a task or a one-shot lifetime. The parent can message the same child again after earlier work finishes. One-shot children remain a supported case: an Agent whose runtime creates a fresh worker for each delegation announces a new child each time and never assigns it more work. The protocol does not limit subagents to that pattern. Client-initiated session mutations remain disabled unless explicitly advertised for that child; this proposal initially defines only cancellation of current work. ## Status quo > How do things work today and what problems does this cause? Why would we change things? ACP models a conversation as a single session update stream. Agents can run work concurrently internally, but there is no portable way to tell the Client that an update came from a subagent or to describe the relationship between the two sessions. Agents therefore have to flatten subagent activity into the parent session, hide it, or encode it in custom tool calls. Clients cannot reliably: * render concurrent work as separate activity; * associate plans, messages, and tool calls with the worker that produced them; * distinguish a worker's current title from the history of tasks sent to it; * track nested subagents; * cancel one subagent without cancelling the parent turn; or * distinguish an idle child from one that is still processing work. Treating a subagent as an ordinary user-facing session is also inaccurate. It would imply that Clients can call methods such as `session/prompt`, or future queueing and steering methods, even when the underlying runtime has no way to accept user input for that worker. ## What we propose to do about it > What are you proposing to improve the situation? ### Capability negotiation In v1, add an optional `subagents` object to `ClientCapabilities`. A non-null object means the Client understands the association updates, session-directed messages and chunks, and restricted-session semantics in this RFD. The field is optional and nullable, like adjacent capability objects. Omission or `null` means the capability is not supported; `{}` means it is supported. ```json theme={null} { "clientCapabilities": { "subagents": {} } } ``` In v1, an Agent **MUST NOT** send the updates defined by this RFD unless the Client advertised `subagents`. It may still use subagents internally and present their results through the parent session. There is no Agent-side capability. Subagent visibility flows only from Agent to Client, so the Client capability alone is enough to prevent sending updates the other side cannot understand; a Client learns that a particular Agent exposes subagents by receiving the first update. In ACP v2, subagent updates are part of the baseline session model and support is assumed rather than negotiated; see [Subagents in ACP v2](#subagents-in-acp-v2). ### Announcing and updating an association `subagent_update` notifies the Client that the enclosing parent session has created and owns another session. The first update for an unknown `update.sessionId` announces that ownership association; later updates patch its metadata without creating a new child or transferring ownership. This is not a message to the child or merely a link to a related session. When an Agent creates a subagent that it wants to expose, it **MUST** send the announcing `subagent_update` before sending any request or notification bearing the child's session ID, including any live session message naming it as sender or recipient. This includes permission, elicitation, filesystem, and terminal requests where supported by the protocol version: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_parent", "update": { "sessionUpdate": "subagent_update", "sessionId": "sess_child_1", "title": "Test investigator", "description": "Investigates platform-specific test failures.", "capabilities": { "cancel": {} } } } } ``` Only `update.sessionId` is required: * `update.sessionId` is an opaque `SessionId` unique within the ACP connection. It identifies the same child across repeated delegations and **MUST NOT** be reused for an unrelated session. * `title` is an optional human-readable label for the child in its parent's view. It need not be unique; the Client chooses a fallback if none is supplied. * `description` is an optional human-readable description of the child's role or purpose. It is current display metadata, not a transcript of instructions. * `capabilities` optionally describes the Client-initiated session mutations permitted for this specific child session. `cancel` is an optional, nullable capability object: omitted or `null` means unsupported, while `{}` advertises support. The object may include optional nullable `_meta`; omitted or `null` `_meta` means no capability metadata. If `capabilities` was never supplied, no session mutations are permitted. * `state` is an optional current-work snapshot, defined in [Current work state](#current-work-state). It is not a lifecycle outcome. * `cwd` and `additionalDirectories` optionally report the child's working directories, defined in [Working directories](#working-directories). * `_meta` optionally carries association metadata. In both versions, these optional fields are nullable patches: omission means unchanged, `null` clears the field, and a concrete value replaces the whole previous field. The exception is a concrete `_meta` object in v2, which patches the stored metadata by top-level key as defined by [v2 Metadata Patches](/rfds/v2/meta-patches). Clearing `title` or `description` removes the parent's display override. Clearing `state` leaves current activity unconfirmed, not idle. Clearing `cwd` or `additionalDirectories` makes the child inherit that value from its parent again. Both `capabilities: null` and `capabilities: {}` disable Client-initiated mutations. The parent stream carries `title` and `description` so Clients can maintain a subagent roster without collecting metadata from every child stream. These are the parent's labels for its child. The child's ordinary `session_info_update` can still describe its own conversation; it does not patch the parent association's display metadata. Updating either title does not rewrite the content of earlier messages or operations. The `capabilities` object is replaced as a whole, not patched recursively. For example, `capabilities: { "cancel": null }` disables individual cancellation in either version. Outer `capabilities: null` clears the entire capability set. Capability advertisements inside that set are not patches: omitted or `null` `cancel` means unsupported, not unchanged. The outer `sessionId` establishes the immediate parent. This supports arbitrary nesting without adding a second parent identifier. If a child spawns another subagent, the Agent sends `subagent_update` with the child's session ID as the outer `sessionId`. A child has one immediate parent; the association cannot reparent an existing session, refer to itself, or create a cycle. This association describes ownership and management, not the set of sessions that may interact with the child. Session-directed messages describe communication and may go from a child back to its parent or to another known session without changing the ownership tree. Session identity follows the exposed conversation, not an individual provider task, turn, or tool call. Completing a task does not create a new conversation. Provider IDs can be used directly when their scope and lifetime meet the identity requirements above; otherwise adapters can derive suitable ACP IDs or maintain a mapping. Reuse is allowed, not required. Many runtimes run a subagent once, often synchronously inside a single tool call, and discard it. Such an Agent announces a new child session for each run and never sends it another assignment. This conforms to this RFD. The child keeps its last reported state and history, and the Agent need not report anything further for it. See [Do subagents have to be reusable?](#do-subagents-have-to-be-reusable) Announcement ordering also applies to short-lived work. Clients attribute subsequent traffic to the announced child and apply its restricted-session semantics; routing internals and presentation are implementation choices. SDKs may tolerate non-conforming Agents by buffering early traffic, but that tolerance does not replace the Agent's announcement obligation. Provider callbacks need not arrive in announcement order. If an interaction arrives before the corresponding spawn metadata, the adapter can announce a minimal association as soon as it knows the child's identity and immediate parent, or buffer the interaction until it can do so. It **MUST NOT** guess parentage or temporarily announce a nested child under the root. Exposure is optional. If the runtime cannot supply sufficient identity and parentage without blocking the operation, the Agent may keep that operation unexposed and represent it through the parent instead. It **MUST NOT** later move an already-issued interaction to a different session. Once a child is exposed, new interactions known to belong to that child's work **MUST** use its session ID rather than silently falling back to the root. A parent's own request for permission to create or delegate to a child remains a parent interaction; it does not require announcing a child that does not yet exist. The child's execution context — its working directory, MCP servers, and available tools — is chosen by the Agent and is not guaranteed to match the parent's. An Agent may, for example, run a child in a scratch directory or without the parent's MCP servers. Whatever the context, all child activity flows through the same ACP connection: Agent-to-Client requests made on behalf of a child are subject to the same Client capabilities and permission checks as the parent's, and the Agent **MUST NOT** use a child to circumvent restrictions the Client imposed on the parent session. The Agent reports the parts of that context a Client needs as described in [Child session context](#child-session-context). ### Automatic child event delivery Announcement registers the child for routing on the existing ACP connection. The Agent then sends child events without waiting for another Client request. This RFD does not introduce `session/attach`, `session/subscribe`, or a per-child event opt-in. Clients **MUST NOT** call `session/load` or `session/resume` on a child to begin receiving its events. Automatic delivery is an ACP contract, not an assumption about the provider API. Depending on the provider, adapters may need to enable child output, attach listeners, or restore subscriptions when reconnecting. A provider that already delivers the necessary events requires no additional mechanism. Existing session updates are addressed to the child in the normal way. For example, the child can report its own conversation title separately from the parent's roster label: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_child_1", "update": { "sessionUpdate": "session_info_update", "title": "Windows integration test failure" } } } ``` Updates from the parent and any number of children may be interleaved. Ordering is defined by the transport order within each session, subject to the announcement requirement above. Subagents may use Agent-to-Client methods such as filesystem, terminal, and permission requests when the Client advertised those capabilities. A subagent session is therefore not "read-only" with respect to the workspace. It is restricted only in the direction of user interaction: the Client observes it and may use explicitly advertised controls, but cannot submit new work to it. Existing permission and security boundaries apply equally to parent and child activity. ### Child session context A child is not created through `session/new`, so the context a Client supplies during ordinary session setup — working directory, additional directories, MCP servers, and similar setup parameters — is not something the Client chose for it. Directories default to the parent's, but the Agent chooses the child's context and reports what the Client needs to display the child and evaluate its requests. Where ACP already reports a piece of session context for ordinary sessions, the child uses that same mechanism, addressed to its own session ID: | Context | Reported through | | - | - | | Working directory and additional dirs | `cwd` and `additionalDirectories` on the parent's `subagent_update`; see [Working directories](#working-directories) | | Display label and role | `title` and `description` on the parent's `subagent_update` | | Initial task and later instructions | `session_message` in the child's transcript; see [Delegated tasks](#delegated-tasks) | | The child's own conversation title | Child-addressed `session_info_update` | | Model, reasoning level, and other options | Child-addressed `config_option_update`; see [Child configuration](#child-configuration) | | Current work state | See [Current work state](#current-work-state) | | Plan, token usage, and cost | Child-addressed `plan` and `usage_update`; see [Cost reporting](#cost-reporting-without-inferred-aggregation) | In v1, an Agent that still uses legacy session modes may report a child's current mode with a child-addressed `current_mode_update`. As with configuration, reporting a mode does not authorize `session/set_mode`. The Client cannot prompt a child, so a child's slash commands are not actionable. Agents need not send `available_commands_update` for a child, and Clients **MUST NOT** offer commands from one as input to the child or its parent. This RFD does not report a child's MCP servers, available tools, or system prompt; see [Why not report MCP servers or tools for a child?](#why-not-report-mcp-servers-or-tools-for-a-child) #### Working directories `subagent_update` has two optional, nullable directory fields: * `cwd`: the child's working directory, with the same meaning as `cwd` in ordinary [session setup](/protocol/v1/draft/session-setup#working-directory). It **MUST** be an absolute path. * `additionalDirectories`: further directories the child works in, with the same meaning as `additionalDirectories` in ordinary session setup. Each entry **MUST** be an absolute path. `[]` reports that the child has no additional directories. Both follow the association's patch convention: omission leaves the stored value unchanged, `null` clears it, and a concrete value replaces it. `additionalDirectories` is replaced as a whole array, not merged. A field that has not been reported, or has been cleared, is inherited: the child's effective value is its immediate parent's current effective value. For a root session that is the value from ordinary session setup; for a nested child it may itself be inherited. The two fields are inherited independently, so a child moved to its own worktree that should not keep the parent's additional directories reports `additionalDirectories: []` alongside its `cwd`. Because silence means "same as the parent", an Agent **MUST** report a value that differs from the parent's before sending child traffic that depends on it. An Agent that cannot determine a child's directories **SHOULD NOT** expose that child as sharing the parent's workspace; it can keep the child's Client-mediated work unexposed, as described in [Announcing and updating an association](#announcing-and-updating-an-association). A child running in its own worktree, for example, is announced as: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_parent", "update": { "sessionUpdate": "subagent_update", "sessionId": "sess_child_1", "title": "Test investigator", "cwd": "/home/user/project/.worktrees/test-investigator", "additionalDirectories": [] } } } ``` Reporting these fields does not depend on the Agent advertising the `additionalDirectories` session capability, which governs directories the Client sends during session setup. In v1, the fields are covered by the `subagents` Client capability like the rest of the association. The Agent may change a reusable child's directories, for example by giving each new assignment a fresh worktree. It sends the updated values before child traffic that depends on them. A change does not rewrite earlier messages or tool calls, whose paths are already absolute. The reported directories describe where the Agent placed the child; they do not ask the Client to create, check out, or clean up anything. The Agent owns these resources like any other child resource. In v1, when a child's `terminal/create` request omits `cwd`, the Client uses the child's effective `cwd`. Agents **SHOULD** still pass an explicit `cwd` on child terminal requests. ##### A child's root set In v1, the [root-set checks](/protocol/v1/draft/session-setup#workspace-root-security) that filesystem and terminal requests apply to "the session's root set" use, for a child, the child's effective `[cwd, ...additionalDirectories]`. This is a report, not a grant the Client negotiates. Choosing where a child runs is the Agent's decision, just as Agent-local tools act without going through the Client, and the root set confines the child's work only where a sandbox enforces it. Agents commonly place worktrees outside the project, for example in a temporary directory or a per-user cache; reporting them keeps the Client's view of the child accurate and lets its Client-mediated requests there pass the ordinary root-set check. A Client with a stricter policy for directories outside the parent's root set applies it to the requests it receives, as it would for any session. Agents **SHOULD** report the narrowest directories the child needs, such as the worktree itself rather than its containing temporary directory or the user's home. A directory named only in model output or replayed history is not part of a child's root set. Agent-local tools remain subject to the Agent's own sandbox and permission policy, as for any session. On reconnection, replayed directory values describe the recorded context. Agents **SHOULD** send current values after reconnecting when they differ, and **MUST** report a new value or `null` when a child's directory no longer exists. #### Child configuration Agents **SHOULD** report a child's current configuration, when available, using the existing `config_option_update` notification with the child's session ID. Send an initial snapshot after announcing the child and a fresh snapshot when its configuration changes, including changes between assignments to the same child. Each notification contains the complete reported configuration, using the existing [v1](/protocol/v1/draft/session-config-options#from-the-agent) or [v2](/protocol/v2/draft/session-config-options#from-the-agent) config option shapes. No configuration fields are added to the parent association. Child configuration is not assumed to match the parent's. If the Agent cannot report it, the Client **MUST NOT** infer values from the parent or manufacture configuration options. When reporting configuration for a child that does not permit Client-initiated configuration changes, Agents **SHOULD** restrict each select option's available values to its current value. This preserves the value's human-readable name without advertising choices the Client cannot select. Clients **SHOULD** display singleton selects as labels or disabled selectors. Boolean options have no available-values list and **SHOULD** be displayed read-only under the same restriction. Reporting config options does not authorize `session/set_config_option`, even to set an option to its current value. This RFD defines only the `cancel` mutation capability; enabling configuration changes requires a future, explicit per-child capability. The Agent may still change the child's configuration itself and report a new snapshot. On reconnection, historical configuration may remain visible but **MUST NOT** be presented as confirmed current configuration. Agents **SHOULD** refresh configuration for restored children when available. With history replay, current configuration snapshots are sent after the successful load/resume response; without replay, they may arrive before or after that response, subject to announcement ordering. ### Session-directed messages Add `session_message` and `session_message_chunk` variants to `SessionUpdate` in both versions. These report a session's outgoing or incoming messages to or from another session, not responses addressed to the human user and not tool calls. They use the existing `session/update` notification, not a new JSON-RPC method or a new `ContentBlock` type. The enclosing `params.sessionId` identifies the transcript being updated, not necessarily the sender. Both variants have: * `messageId`: required, non-nullable, and unique within the enclosing session, just like other message IDs. It identifies the entry in that transcript, not a globally shared message or either participant. * `content`: a `session_message` may replace the whole `ContentBlock[]`; `session_message_chunk` requires one non-nullable `ContentBlock` to append. Normal text, images, audio, and resource content use their existing shapes. * `_meta`: optional and nullable. It updates message-scoped metadata on `session_message`; it is chunk-scoped on `session_message_chunk`. Only `session_message` carries the message's identity. A chunk carries only content, as `agent_message_chunk` does: * `senderSessionId`: optional and nullable. Identifies the sending session when supplied. * `recipientSessionId`: optional and nullable. Identifies the receiving session when supplied. * `senderMessageId`: optional and nullable. On an incoming view, the `messageId` of the same message's outgoing view in the sender's transcript. * `recipientMessageId`: optional and nullable. On an outgoing view, the `messageId` of the same message's incoming view in the recipient's transcript. Agents **SHOULD** include participant IDs on the first `session_message` for a message when available, and when streaming a message whose participants are known, send that upsert before its first chunk. Later upserts may omit them or supply previously missing identities. These fields follow the same patch convention as `content`: omission leaves the stored value unchanged, `null` clears it, and a value replaces it. `senderMessageId` and `recipientMessageId` link the two views of a message so that a Client looking at either one can find the other, including when it has not yet received or rendered the other transcript's entry. They follow the same patch convention as the participant IDs. An Agent can therefore stream a view before it knows the other one's ID and supply the reference later with a metadata-only upsert. For example, it can add `recipientMessageId` to the outgoing view once it has reported the incoming view. Agents **SHOULD** supply each reference once they know it. When both views carry references, they **MUST** name each other; a Client that receives conflicting references treats the views as unlinked. A reference does not indicate that the recipient finished processing the message, and it does not establish ownership. Known participant information must remain consistent with the enclosing transcript and earlier updates for that message. When both IDs are known, they identify different sessions and the outer `params.sessionId` matches one of them. Matching the sender represents the outgoing view; matching the recipient represents the incoming view. Supplied live participant IDs refer to sessions known through ordinary setup or a `subagent_update` announcement; missing participants do not prevent displaying the message. Whole-message updates use the same patch convention in both versions: omitted `content`, `_meta`, participant IDs, and message references leave the stored value unchanged, `null` clears the field, and concrete values replace the whole field. The exception is a concrete `_meta` object in v2, which patches the stored metadata by top-level key as defined by [v2 Metadata Patches](/rfds/v2/meta-patches). `content: []` also clears accumulated content. New messages start with empty content and no metadata when those fields are omitted. Chunk `_meta` is not a message patch: omitted or `null` means no metadata for that chunk. Clients should render outgoing entries as "To …" with a recipient link and incoming entries as "From …" with a sender link. Both use normal message content while remaining distinct from user messages and answers to the user. Neither needs a tool-call card, title, execution status, or a raw-input viewer. When participant metadata is insufficient, Clients can use a generic inter-session presentation and add links when identities arrive. Missing metadata is not evidence of human authorship or confirmed receipt. For example, the parent's outgoing view of a message to its child is: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_parent", "update": { "sessionUpdate": "session_message", "messageId": "msg_to_child_1", "senderSessionId": "sess_parent", "recipientSessionId": "sess_child_1", "content": [ { "type": "text", "text": "Also check whether the failure occurs on Windows." } ] } } } ``` If the Agent observes that message in the child's conversation, it can report the incoming view using the same shape. The sender and recipient stay the same; the outer session and transcript-local message ID change: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_child_1", "update": { "sessionUpdate": "session_message", "messageId": "msg_from_parent_1", "senderSessionId": "sess_parent", "recipientSessionId": "sess_child_1", "senderMessageId": "msg_to_child_1", "content": [ { "type": "text", "text": "Also check whether the failure occurs on Windows." } ] } } } ``` The Agent can then link the parent's outgoing view to it with a metadata-only upsert: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_parent", "update": { "sessionUpdate": "session_message", "messageId": "msg_to_child_1", "recipientMessageId": "msg_from_parent_1" } } } ``` These notifications report Agent-owned communication; the Client does not forward the content or invoke `session/prompt` because it received one. Neither form acknowledges recipient processing or establishes new ownership. Actual delivery is handled by the Agent. The Agent reports each side only when it can observe that side: an outgoing entry is not sufficient evidence to manufacture an incoming entry. Clients **MUST NOT** infer receipt or synthesize an Agent-reported incoming transcript entry solely from an outgoing entry. This does not prevent a clearly labeled projection of outgoing messages in a cross-session view. The two views have independently scoped message IDs, and Clients **MUST NOT** assume equal IDs identify the same communication across sessions. Only `senderMessageId` and `recipientMessageId` link the two views. An incoming entry uses this message kind, not an additional ordinary user message that would misattribute the communication. Rendering the same entry in multiple views or quoting it in a summary is a presentation choice. Its content reflects what was observed in that conversation; it need not match the outgoing view byte for byte if the Agent transformed the content during delivery. Neither view indicates that the recipient finished processing the message. Normal tool calls remain available for actual tools, including tools that perform delegation or waiting. They report those operations' inputs, outputs, and outcomes. Agents do not need to invent a tool call to report a directed message. #### Referencing sessions from tool calls Add a `session` variant to `ToolCallContent` in both versions. It is a display-only reference to another session that the tool call operates on, in the same way that `terminal` content references a terminal by ID: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_parent", "update": { "sessionUpdate": "tool_call_update", "toolCallId": "call_wait_1", "content": [ { "type": "session", "sessionId": "sess_child_1" }, { "type": "session", "sessionId": "sess_child_2" } ] } } } ``` `sessionId` is required. `_meta` is optional and nullable, and omitted or `null` means no metadata. Clients use the reference to link the tool call to the referenced session, for example to open the child's conversation from the tool call. Delegation itself is a message. Agents **SHOULD** report the task a parent sends a child as a `session_message`, as described in [Delegated tasks](#delegated-tasks), and need not keep a tool call only to link the parent to the child. Session references are for tool calls that remain visible because they report a real operation, such as a spawn that needed permission, a tool that waits on one or more children, or a batch spawn. A tool call can reference several sessions, and a reusable child can be referenced by many tool calls over its lifetime. A referenced session follows the announcement rule above: it **MUST** be known through ordinary session setup or a `subagent_update` announcement before a tool call references it. A replayed reference to a session that is not available follows the historical replay rules. A reference does not establish ownership, grant Client-initiated controls, or report that the referenced session received or finished any work. Its tool call's status does not define the referenced session's lifetime or work state. In v1, `session` content is covered by the `subagents` Client capability like the rest of this RFD. In v2, receivers that do not recognize it preserve it as unknown tool call content. #### Delegated tasks The task a parent gives a child, including the first one that starts the child's work, is a session-directed message from the parent to the child. Agents **SHOULD** report it as the incoming view in the child's transcript, a `session_message` with outer `sessionId` set to the child and `senderSessionId` set to the parent, before the child's response to it. If the parent's conversation also records the delegation, Agents **SHOULD** report the outgoing view in the parent's transcript and link the two views. Later instructions to the same child use the same form. Agents **SHOULD NOT** report this task as a `user_message_chunk` or a v2 `user_message` in the child's transcript. A user message would attribute the task to the human user. A `session_message` lets Clients render it as communication between sessions, for example as "From Parent" at the top of the child's conversation. The `description` on `subagent_update` describes the child's role and is not a substitute for the task message. A parent that delegates through a tool may also report the task in that tool call's input. The tool call reports the operation. The child's `session_message` reports what the child received. #### Streaming A directed message may start with a chunk on either side; a prior whole-message notification and complete participant metadata are not required: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_child_1", "update": { "sessionUpdate": "session_message_chunk", "messageId": "msg_2", "content": { "type": "text", "text": "Start by reproducing " } } } } ``` Subsequent chunks append normal message content for the same transcript-local `messageId`. Participant metadata and references arrive in a metadata-only upsert, before, between, or after the chunks, without repeating or replacing the content: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_child_1", "update": { "sessionUpdate": "session_message", "messageId": "msg_2", "senderSessionId": "sess_parent", "recipientSessionId": "sess_child_1" } } } ``` A `session_message` is an upsert: when it supplies a content array, that array replaces all content accumulated for the message rather than appending. It can also update metadata without resending content. Later chunks append to the stored content. A chunk carries no participant IDs or references, and its `_meta` does not patch message metadata. ### Why session IDs appear in different places These IDs answer different questions; they are not competing ways to route the same event: | Location | Purpose | | - | - | | Outer `params.sessionId` | Which session's transcript or entities does this update address? | | `params.update.sessionId` in `subagent_update` | Which child is owned by the parent named by the outer ID? | | `params.update.senderSessionId` in a session message | Which session sent, or is sending, this message? | | `params.update.recipientSessionId` in a session message | Which session is this message addressed to? | | `sessionId` in `session` tool call content | Which session does this tool call operate on? | For example, with parent `sess_parent` and child `sess_child_1`: 1. An association update has outer `sessionId: "sess_parent"` and `update.sessionId: "sess_child_1"`. This registers the parent-child relationship and the child's capabilities. 2. An outgoing message has outer `sessionId: "sess_parent"`, `senderSessionId: "sess_parent"`, and `recipientSessionId: "sess_child_1"`. This updates the parent's history with a link to the child. 3. The received view has outer `sessionId: "sess_child_1"` and the same sender and recipient. Its independent message ID identifies the entry in the child's history, and its `senderMessageId` links back to the parent's outgoing view, which can name it with `recipientMessageId`. 4. The child's own messages, plans, and tool calls have outer `sessionId: "sess_child_1"`. They update the child's history, not the parent session. V2 work-state notifications use this child-addressed stream and are mirrored on the parent association; v1 reports work state through the association as described below. 5. A reply reverses the sender and recipient, not the ownership association. The Agent can report its outgoing view in the child's transcript and its incoming view in the parent's transcript. Communication links can point both ways without making the ownership tree cyclic. Neither participant ID replaces the outer routing ID or the separate ownership announcement. The Client may navigate between the conversations without treating a message as a transfer of ownership or control. ### Current work state There is no separate subagent lifecycle enum. Work can start and stop many times within the same child session. Becoming idle, completing an operation, or cancelling current work does not permanently end the association. V2 uses the child's ordinary `state_update` notifications and their existing foreground-work semantics. Agents **SHOULD** also mirror each reported child state on the immediate parent's `subagent_update.state`, so both the parent's roster and the child's own stream carry the information. These are two reports of one logical child state, not independent lifecycles. Mirrored reports use the same `StateUpdate` snapshot and are idempotent: a second copy does not represent additional work, completion, or token usage. Copies of a transition precede later transitions on either path, so a delayed mirror cannot overwrite newer state. For example, a v2 child reports: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_child_1", "update": { "sessionUpdate": "state_update", "state": "idle", "stopReason": "end_turn" } } } ``` The parent-carried snapshot has the same shape in both versions. V2 emits it alongside the child's notification; v1 uses it because it has no equivalent child notification or Client-issued child prompt response: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_parent", "update": { "sessionUpdate": "subagent_update", "sessionId": "sess_child_1", "state": { "state": "idle", "stopReason": "end_turn" } } } } ``` The v1 payload mirrors the v2 state object: * `running`: foreground work is in progress. * `requires_action`: foreground work is blocked on user action. * `unknown`: the Agent cannot currently determine foreground activity, for example after losing a remote child's event feed while the ACP connection remains live. This is a nonterminal work state, not a work outcome. * `idle`: foreground work is not in progress; the parent may assign more work. Optional nullable `stopReason` takes v1's existing `StopReason` values plus `error`, which carries an optional, nullable JSON-RPC `error` object beside it, as in the v2 idle `state_update`. Omitted or `null` means no reason was reported. When the draft end-turn usage feature is supported, optional nullable `usage` follows the same convention. * Each known state may contain optional nullable `_meta`; omitted and `null` both mean no metadata for that snapshot. When the v1 Agent observes child foreground work starting, resuming, or stopping, it **MUST** report the corresponding `running` or `idle` state. It **SHOULD** report `requires_action` while observed foreground work is blocked on user action, and include `stopReason` when the reason for stopping is known. This does not require reconstructing unobserved intermediate transitions or guessing activity from provider callbacks. Cancellation uses `idle` with `stopReason: "cancelled"`, not a terminal child state. A failure that ends the child's foreground work uses `idle` with `stopReason: "error"` and, when available, the failure in `error`. A v1 child has no prompt response that could carry a JSON-RPC error, so this snapshot is the only place a v1 Client learns that the child's work failed: ```json theme={null} { "sessionUpdate": "subagent_update", "sessionId": "sess_child_1", "state": { "state": "idle", "stopReason": "error", "error": { "code": -32000, "message": "Authentication required" } } } ``` When observability of child foreground work is actually lost, the Agent **MUST** report `unknown` using the existing state payload: v1 sends `subagent_update` with `"state": { "state": "unknown" }` on the parent stream; v2 sends `state_update` with `"state": "unknown"` on the child stream. Silence alone is not evidence of lost observability. V2 mirrors this snapshot on the parent association as well. The Client **MUST NOT** continue presenting an earlier `running` or `requires_action` as confirmed live activity after `unknown`, though it may retain that last-known value for context. A subsequent `running`, `requires_action`, or `idle` replaces `unknown` for the same child ID. `unknown` neither closes or cancels the child nor resolves pending requests; it does not automatically revoke mutation capabilities. If a control is no longer available, the Agent updates `capabilities` separately. The association's `state` field is a replacement snapshot, not a nested patch: omission leaves the previous snapshot unchanged, `null` clears it, and a concrete object replaces it entirely. For example, `{ "state": "running" }` replaces an earlier idle snapshot and its stop reason. If no state has been reported, or the snapshot is cleared, the Client has no confirmed current-work state; neither announcement nor clearing implies `running`, `idle`, or cancellation. A later state report on either supported path can supply the current snapshot again. Unrelated association updates need not repeat it. Unrecognized state objects preserve both their discriminator and payload. Values beginning with `_` are implementation-specific; other unknown values are reserved for future ACP states. An unknown value does not imply completion or closure. Unrecognized stop reasons on an idle snapshot are preserved the same way in both versions. V2 keeps its open state and stop-reason handling, with `unknown` added to ordinary `StateUpdate` under the experimental `unstable_subagents` feature. Idle is not a successful task outcome or a declaration that the session has been released. As in ordinary v2 sessions, background activity may still emit updates while foreground work is idle. Operation results and failures are reported through the relevant tool calls or other ordinary session output; the `error` stop reason is only for a failure that ends the child's foreground work, and does not close the session or fail its parent. ### Connection loss Connection availability is separate from reported work state. After losing the ACP connection, the Client **MUST NOT** continue presenting a last-known running state as confirmed live activity, or infer that unfinished work succeeded, failed, or was cancelled. It may show the child as disconnected or its current activity as unknown while retaining recorded outcomes. This Client-local uncertainty differs from an Agent-reported `unknown` state while ACP is connected. This is local presentation, not a synthesized wire state or a permanent change to the session's history. Fresh state reported after reconnecting is authoritative and may be `running` again for the same child ID. Neither the parent's prompt response nor its transition to idle implies a lost connection or a stopped child. ### Reconnection and replay The Client reconnects through the ordinary parent session. Direct child `session/load` and `session/resume` are not supported by this proposal. The Agent decides whether parent reconnection reattaches surviving child runtimes, restores them, or only makes their recorded history available. The protocol does not prescribe a runtime-recovery algorithm. The replay entry point depends on the protocol version: * **ACP v1:** `session/load` requests history replay. `session/resume` restores the parent without replaying history. * **ACP v2:** `session/resume` with `replayFrom: { "type": "start" }` requests full history replay. Omitted or `null` `replayFrom` means no history replay. v2 has no `session/load` method. The parent session's ordinary replay obligations are unchanged. In addition, the Agent **SHOULD** replay available recorded associations and child history on a best-effort basis. Provider retention, process restarts, and missing transcripts may leave some or all child history unavailable; complete child history is not a prerequisite for supporting live subagent sessions. The following rules still apply to whatever is replayed: * Replayed child updates **MUST** preserve their original session identities, known parentage, and per-session ordering. Child announcements precede child traffic. * If identity and parentage are recoverable but conversation content is not, the Agent may replay only the association. This is historical context, not evidence of a live runtime or a complete transcript. * If an association cannot be reconstructed truthfully, the Agent **MUST NOT** guess its parent or issue traffic for an unannounced child. It may omit that child's own replay. * A recorded directed message in a known session's history may still be replayed with its available participant metadata and content when the other participant's association or history is unavailable. This applies to incoming as well as outgoing entries. A historical address is not an announcement. Clients **MUST NOT** infer ownership, live activity, or controls from it; they can show the other participant as unavailable until its session becomes known. Agents **MUST NOT** invent either participant ID or reinterpret the content as an ordinary message to or from the human user. * The Agent **SHOULD** make known gaps apparent through a supported advisory mechanism rather than imply that child replay is complete. Missing history is not evidence that a child never existed, stopped, failed, or was cancelled. * All history selected for this replay **MUST** be sent before the response. The response completes the best-effort child replay; it does not certify that every child record was available. Delayed historical child state must not be sent after that boundary as if it were fresh activity. Adapters **SHOULD** retain or reconstruct child identity, associations, and ACP-visible conversation data where practical. This does not require a durable copy of every child event. Replay can use provider transcripts or retained snapshots rather than reproduce the original wire chunking. These best-effort history rules do not weaken identity or announcement requirements for live child traffic after reconnection. Capability negotiation still applies during replay. V1 Clients that did not advertise `subagents` receive ordinary parent history, not unsupported child updates or session-directed message variants. Parent-level results and summaries can still be replayed. Reconnection separates routing context from current work state and controls. When loading or resuming a parent, the Client **MUST** invalidate cached live work state and mutation authorization for its children. Historical data may remain visible, but effective child capabilities start empty and current work state starts unconfirmed. Historical capability patches never populate that effective set; omitting a current capability field cannot revive an earlier `cancel` grant. The Client **MUST NOT** enable child mutations until the load/resume succeeds and a current capability grants them. If the operation fails, current state and authorization received during that attempt are invalidated. The Client need not retain an earlier session tree. Before using a child in live traffic, the Agent establishes the child's complete ancestor chain in parent-before-child order during this load/resume. Replayed associations can provide that routing context and need not be repeated merely because the response has been sent. Missing intermediate ancestors still need announcing, even if their runtimes were not restored; an association establishes identity, not a live runtime. **When replay is requested**, the successful response is the freshness boundary for child work-state and mutation-capability snapshots: * Before the response, these snapshots are historical. They **MUST NOT** authorize Client-initiated mutations or establish confirmed current activity. * Current snapshots are sent after the response. Normal association and state updates suffice; no extra announcement phase is needed for already-known associations. An Agent can omit capabilities when none are enabled, because the effective set starts empty rather than inheriting historical grants. Replay **MUST NOT** reissue recorded permission, elicitation, or other Agent-to-Client requests. Newly issued requests are live and may proceed once their child and ancestors are announced, under ordinary request handling. Responding to them does not enable historical Client-initiated controls. Other live transcript traffic can also proceed if the Agent preserves per-session ordering and ensures subsequent replay cannot overwrite or duplicate newer live content. Buffering affected traffic is one way to meet those requirements, not a requirement to stop every child stream. **When no replay is requested**, announcements, current snapshots, and ordinary child traffic may arrive before or after the resume response, subject to announcement ordering. These snapshots are current observations, not history replay; controls still wait for successful resume. Agent-to-Client requests retain their ordinary handling; their responses need not wait for resume to finish. For example, if `root` → `coordinator` → `worker` was previously announced and only `worker` resumes, the Agent establishes `coordinator` under `root`, then `worker` under `coordinator`, before sending fresh `worker` traffic. Replay may already have supplied these associations. Without replay they can be announced before the resume response. A routing-only ancestor can omit capabilities and work state; it has no enabled controls or confirmed activity. The worker is not reparented directly under `root`. The Agent **SHOULD** report current child work state when it can determine it. Historical running states are not proof of current activity. An Agent **MUST NOT** manufacture a failure, cancellation, or permanent orphan outcome solely because the persisted history lacks a final update or a runtime could not be restored. A history-only child remains displayable, with unconfirmed current activity and no enabled mutations. ### Restricted session methods Client-initiated methods that modify a child session or its runtime are disabled unless explicitly enabled by that child's capabilities. This is an allowlist, not a list of individual prohibited methods: Clients **MUST NOT** invoke an unadvertised mutation, including a future method, merely because the Agent supports it for ordinary sessions. Mutations include prompting, queueing, steering, cancellation, closing, deletion, mode or configuration changes, and forking. Loading or resuming also changes runtime attachment and is not a read-only history query. The only mutation capability defined by this RFD is `cancel`; direct child load, resume, and close are therefore not allowed. A child's tool call or terminal that advertises its own `capabilities.cancel` enables `tool_call/cancel` or `terminal/cancel` for that item, sent with the child's `sessionId`, whether or not the child advertises `cancel`. It enables nothing else on the child. The parent Agent's own communication with its children is not a Client-initiated mutation and is not restricted by these capabilities. Read-only operations retain their normal protocol semantics and capability requirements; this RFD does not grant access to additional sessions or define a new history-query method. Responses to Agent-to-Client requests are not Client-initiated session mutations and **MUST** still be delivered. Restricted children are discovered through parent associations rather than ordinary standalone `session/list` entries. This avoids offering load, resume, or prompt controls that are not available for them. If forking a parent copies child history, the Agent **MUST** consistently remap the copied session IDs in both message participant fields and in `session` tool call content, including references to the forked root. Each copied child still has one parent and a distinct identity. Participants outside the copied tree do not become part of the copy; unavailable participants follow the historical replay rules above. Copying history does not itself create live child runtimes. Parent deletion keeps its ordinary history-management semantics; it is not a substitute for closing active sessions. ### Cancellation and resource ownership If `capabilities.cancel` is a non-null object, the Client may send the existing `session/cancel` notification with the child's session ID. This cancels current work in that child, not its parent or siblings. The per-child capability controls individual Client cancellation; it does not prevent the Agent from cancelling its own delegated work. Cancelling a session's current work, whether a parent's or an individually cancelled child's, also cancels the descendant work that the cancelled work is waiting on, such as a child whose result a pending tool call needs. Whether other descendants keep running is up to the Agent: a background child that the cancelled work did not wait on may continue, as it would have if that work had ended normally. The Client learns which descendants stopped from their reported work state, not from the cancellation itself. An omitted or `null` per-child `cancel` capability does not waive this cascade from an ancestor. Adapters should verify whether the provider already supplies it or needs additional descendant cancellation. Advertise individual cancellation only when the adapter can target the child's current work correctly in that runtime mode. Cancellation retains ordinary session semantics: abort the affected work and send its pending updates before confirming cancellation. A child confirms cancellation with `idle` and `stopReason: "cancelled"` through its v1 state snapshot or ordinary v2 notification, mirrored on the v2 parent association. There is no Client-issued child `session/prompt` response to wait for. A cancellation racing with already-ended work does not rewrite that work's outcome. Acceptance of a provider stop/interrupt command is not, by itself, evidence that the work has stopped. The Agent reports cancellation from actual work-state or completion evidence, not merely from a successful command acknowledgement. If activity becomes unobservable, it reports `unknown` rather than inventing a cancelled outcome. The Client **SHOULD** optimistically mark the cancelled session's unfinished tool calls as cancelled, as specified for [v1 prompt cancellation](/protocol/v1/prompt-turn#cancellation) and [v2 work cancellation](/protocol/v2/prompt-lifecycle#cancellation), and a descendant's once that descendant reports `idle` with `stopReason: "cancelled"`. In v2, it **SHOULD** skip tool calls in that session's latest [`background`](./v2/background-work.mdx) list and tool calls that reference a listed terminal, since that work keeps running. It **SHOULD** still accept subsequent Agent updates for those calls. This local presentation is not a new v1 wire-level tool status. Cancellation does not close the child session or prevent the parent from assigning later work to it. Completing or failing one operation also does not close the session or automatically fail its parent. The Agent owns child resources. Closing the ordinary parent session cancels all of its active descendant work, background children included, and releases the associated active resources under the existing close contract. It does not erase child history or require a new terminal-state notification. Whether child runtimes can later be restored is left to the Agent. ### Pending permission and elicitation requests Optimistically updating a tool's display does not resolve its JSON-RPC requests. When the Client cancels a session's current work, it **MUST** respond to that session's pending `session/request_permission` requests with the `cancelled` outcome, following the existing cancellation rule. It **SHOULD** dismiss that session's elicitation controls and respond with the `cancel` action. The cancellation does not by itself resolve a descendant's pending requests. Once that descendant reports `idle` with `stopReason: "cancelled"`, the Client cleans them up as if it had cancelled the descendant directly; until then the user can still answer them. A descendant that keeps running therefore keeps its requests, and the Client never denies a tool use of work that continues. Closing the parent ends the work of all of its descendants, so the Client cleans up their requests together with the parent's. Generic [`$/cancel_request`](/protocol/v1/cancellation) remains optional. Agents may use it to cancel an abandoned child request, including when the Agent stops work on its own. Advertising subagent support does not add a requirement to implement that generic mechanism. If the Client learns that an interactive request's associated work has ended and the request no longer applies, it **SHOULD** dismiss the control and send the corresponding cancellation response. Idle alone is not a cancellation of unrelated background requests. Requests remain attributed to their original child session and **MUST NOT** move to the parent or a later operation. A late response still resolves its original request, but the Agent **MUST NOT** use it to restart cancelled or otherwise abandoned work, or to authorize a new assignment to the same child. A request **MUST NOT** receive more than one response. There is no new child-termination barrier that requires every outstanding request in a reusable session to resolve before reporting work state. ### Cost reporting without inferred aggregation Exposing child sessions does not make existing `usage_update.cost` values exclusive or additive. Cost reporting remains optional. An Agent may continue reporting the provider's cumulative cost for the parent session even when it includes child work or internal helper calls. Exposing subagents does not require changing that accounting scope, producing an exclusive breakdown, or discarding a useful inclusive total. Child costs remain optional and may overlap the parent's reported cost. Missing child cost is unknown, not zero. Agents **MUST NOT** fabricate an exclusive parent or child amount from incomplete token counts or an aggregate total. Clients **MUST NOT** infer a combined tree total by adding parent and child values, or infer exclusive costs by subtracting them, unless a separate accounting contract establishes their coverage and how any overlap is handled. Clients may display each session's latest reported cumulative value without claiming an accounting scope that has not been established. Successive cumulative updates and repeated messages to a session are not additional costs. For example, a parent's reported USD 1.20 may already include a child's USD 0.30. Both values can be shown, but the Client must not synthesize USD 1.50 as the combined cost from the session tree alone. A missing cost for another child does not invalidate the provider's USD 1.20 report. This RFD adds no cost-scope field or accounting negotiation. A future usage extension can define explicit inclusive/exclusive breakdowns where available. Amounts in different currencies must not be added without conversion under such an accounting contract. Context-window usage remains local to each session and is not summed across the tree. ### Subagents in ACP v2 The two versions use the same ownership and directed-message model, with these differences: * **Baseline support, no capability.** v2 Clients **MUST** understand `subagent_update`, apply child operation restrictions, understand directed message snapshots/chunks, and attribute requests and notifications to the correct sessions. Clients may choose not to render a dedicated subagent UI, but cannot merely ignore the announcement as an unknown update. The `subagents` Client capability is v1-only. * **Mirrored child work state.** V2 keeps `state_update` on the child's own stream and mirrors the same state in the parent association. V1 uses only the parent-carried snapshot. Both describe the child's ordinary foreground work, not a separate subagent lifecycle. * **Resume with replay.** Available child history is replayed best-effort through `session/resume` with `replayFrom: { "type": "start" }`, not `session/load`. * **Directories are informational.** v2 removes the Client filesystem and terminal methods, so a child's `cwd` and `additionalDirectories` have no Client-side root-set check or terminal default to drive. They use the same fields and inheritance rules and tell the Client where the child runs; the root set remains a boundary for the Agent's own tools, as for any v2 session. The restricted-session rules, cancellation flow, and connection-loss handling defined above also apply to v2. The [v2 prompt lifecycle](/protocol/v2/prompt-lifecycle) resolves `session/prompt` at acceptance and reports foreground work through `state_update`. Neither that response nor the parent's transition to `idle` implies that every child has finished. ## Shiny future > How will things play out once this feature exists? A Client can render a parent session with a live tree of concurrent workers. Selecting a worker shows its own plan, messages, tool calls, and status without mixing them into the main transcript. Where supported, the user can stop a runaway worker without discarding useful work from its siblings or parent. Agents that do not implement subagents remain unchanged. Agents that use subagents internally but do not want to expose them can continue flattening or summarizing their output in the parent session. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? This is a project rollout and validation plan, not a requirement for every implementation to use the named SDKs, providers, or integration techniques. 1. Add the v1 `SubagentCapabilities` marker and the `SubagentUpdate` association and `SubagentSessionCapabilities` types in both versions, including the optional `cwd` and `additionalDirectories` fields on `SubagentUpdate`. 2. Add `SessionMessage` and `SessionMessageChunk` update variants in both versions, using normal content, with optional sender and recipient session metadata and message references on `SessionMessage` for incoming and outgoing views. Add a `session` variant to `ToolCallContent` in both versions. 3. Mirror the v2 `StateUpdate` payload in v1 and embed it in the v1 association update. In v2, mirror ordinary child-session state notifications in the parent association as well. 4. Keep the additions behind `unstable_subagents` and regenerate schemas and reference documentation. 5. Ship SDK releases that carry the draft `subagents` capability and update types — or at minimum preserve them when deserializing and re-serializing — before adapter rollout. SDKs that strip the draft fields force temporary out-of-band negotiation bridges such as `_meta`-scoped capability flags. Such bridges are compatibility shims, not an alternative protocol, and are retired once SDK support ships. SDK preservation of the draft fields is an explicit prerequisite for the validation step below. 6. Support the freshness boundary for replayed child state and capabilities. For example, an SDK could offer an explicit responder or after-response hook for publishing current snapshots after replay completes. Non-replaying resume does not need such a hook, and other live child traffic need not be globally buffered. Any ordering mechanism should provide the required ordering rather than rely on arbitrary delays. 7. Update example Clients to route child events automatically, retain reusable session identities, and render session-directed messages distinctly from user-facing responses and tool calls. Enable or restore provider-side child delivery where that provider requires it. 8. Establish stable provider-to-ACP session identity, truthful interaction attribution, and cancellation of current work. Retain or reconstruct child history where practical, but do not make complete child transcripts a prerequisite for live exposure. 9. Exercise the [validation scenarios](#validation-scenarios) with captured native events, including reordered callbacks and reconnects. 10. Validate this revision against both Claude Code and Codex adapter mappings and a Client with concurrent-session UI before stabilization. Schema tests and the existence of provider APIs alone are not end-to-end validation. ### Provider integration notes The following inspected versions provide concrete inputs for adapters; they are not a claim that all versions or runtime modes have equivalent behavior, or that the existing adapters already implement this revision. * **Claude Agent SDK 0.3.280:** the [published declarations](https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.280/sdk.d.ts) expose forwarded child messages through `forwardSubagentText` and `parent_tool_use_id`, task lifecycle events, permission `agentID` and `toolUseID`, `stopTask(taskId)`, and child transcript APIs such as `listSubagents` and `getSubagentMessages`. Adapters may need to correlate these IDs where their scopes differ from ACP conversation identity. Permission callbacks can precede spawn metadata. Query cost totals may already include child and internal work. * **Codex 0.156.1:** thread/turn identifiers, thread status and approval/input wait flags, `turn/interrupt(threadId, turnId)`, and thread history support the corresponding mapping. The server [attaches listeners to newly created threads](https://github.com/openai/codex/blob/b412ff32c417f855c2b2d1581b77058eed87c84b/codex-rs/app-server/src/lib.rs#L1265-L1283); adapters should also check delivery for existing threads on reconnect. Per-thread token usage is not a monetary cost report. These integration examples should be checked against the adapter's pinned dependencies. For example, a provider's generic paused status does not necessarily mean `requires_action`, and acknowledging an interrupt is not a completed cancellation. Likewise, a decoder preserving a new field is not sufficient implementation of child routing or the replay freshness boundary. ### Validation scenarios * Send two assignments to the same child conversation: keep its ACP session ID, use distinct message IDs, and allow `running → idle → running`. * Mirror v2 child work state to the parent association. Verify that both streams converge on the same state and duplicate snapshots do not count work completion or usage twice. * Report child configuration after announcement, then change its model or reasoning level between assignments. Verify that complete snapshots replace the displayed configuration, missing values are not inherited from the parent, singleton selects and boolean options remain read-only, and reporting options never enables `session/set_config_option`. On reconnection, distinguish historical configuration from fresh snapshots. * Announce one child in the parent's directory and another in its own worktree, then move the first to a new worktree between assignments. Verify that the first child inherits the parent's directories until it moves, `additionalDirectories: []` stops inheriting the parent's extra directories, in v1 a terminal request without `cwd` uses the child's effective `cwd` and Client-mediated requests inside a worktree in a temporary directory pass the child's root-set check without extending the parent's or a sibling's root set. * Send messages to a parent and a sibling from a child's stream. Verify that each message has the correct sender, recipient, and content, and that the parent-child tree does not change. * Report the received view in the recipient's transcript, with its own message ID and a link to the sender. Verify that neither the Client nor the adapter invents an Agent-reported incoming entry from outgoing traffic alone. Clearly labeled UI projections remain possible, without duplicating the communication as an ordinary user message. * Stream an incoming view before its outgoing view's ID is known, then supply `senderMessageId` on the incoming view and `recipientMessageId` on the outgoing view with metadata-only upserts. Verify that a Client can go from either view to the other, including before it has rendered the other transcript, and that it does not link views by equal IDs alone. * Start a directed message with a chunk, interleave another message, and replace accumulated content with a whole snapshot. Start without participant metadata, add it later with a metadata-only upsert without replacing content, and keep streaming chunks. Verify that missing metadata remains an inter-session message rather than being attributed to a human or guessed sender. * Finish reporting a message before the child finishes processing it, and keep receiving child events after the parent's prompt response. * Deliver a child permission callback before spawn metadata, including a nested child: verify early truthful announcement or buffering, no guessed parent, and the unexposed-operation fallback when necessary. * Cancel a child and then an ancestor while interactions are pending: verify native work is targeted correctly, acknowledgement is not confused with completion, and late responses cannot authorize later assignments. * Cancel a parent while a child it waits on and a background child it does not wait on both have pending requests: verify that the waited-on child stops and reports a cancelled `idle` before the Client cleans up its requests, and that the background child may keep running with its request still answerable. * Replay after restarting the adapter with complete, partial, and unavailable child history. Preserve IDs and relationships for whatever is replayed, preserve historical senders and recipients without guessing ancestry, and do not infer an outcome from a gap. Verify that current work state and controls depend on post-response snapshots, not historical capabilities. An omitted current capability set must leave controls disabled. * Issue a live child request during replay after announcing its ancestor chain. Verify ordinary request handling without enabling historical controls, and that replay cannot overwrite or duplicate newer live transcript content. * Resume without history, including current announcements before the response. Verify that controls remain disabled until success, failed resume invalidates attempted live state, and routing-only ancestors are retained. No additional Client attach/subscribe request or universal after-response hook is required. * Lose a child's activity feed while ACP stays connected: report `unknown` without inventing an outcome, and accept later state for the same child. * Report an inclusive parent cost with missing or overlapping child costs: retain the parent report and do not synthesize a tree total or exclusive shares from the message traffic. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Is a subagent session read-only? Only from the Client's conversational perspective. The Client cannot prompt, queue, or steer it. The subagent may still read and write files, run terminal commands, and request permissions using the capabilities already negotiated on the ACP connection. Making all subagents workspace-read-only would prevent many coding use cases and should instead be an agent policy or a future sandbox capability. ### Do Claude Code and Codex support stopping individual subagents? Current Claude Code and Codex orchestration surfaces both have concepts for stopping or closing an individual worker. That does not mean every version, runtime mode, or ACP adapter can implement it, and other Agents may only support coarse parent-turn cancellation. Individual cancellation must therefore be a capability, not a protocol requirement implied by subagent support. The proposal uses a per-child capability because support may even vary within one Agent: a local worker might be interruptible while a delegated remote job is not. ### Why reuse `session/cancel` instead of adding `subagent/stop`? Once a child has a real ACP session ID, the existing session-scoped lifecycle methods already identify it unambiguously. Reusing them avoids two ways to perform the same operation. The subagent capability narrows where those methods are valid and defines the required cascade behavior. ### Why doesn't cancelling a parent stop every descendant? Agents already differ here. In Claude Code, a background subagent keeps running after the user interrupts the turn that started it: it runs in the background so that it can outlive that turn. A required full cascade would make such an Agent stop background work on every cancellation, which its users do not expect. Descendant work that the cancelled work is waiting on has no purpose once that work is cancelled, so it must still stop. Because the Client cannot tell in advance which descendants will stop, it acts on each one only after that child reports a cancelled `idle`. A Client that wants to stop a background child uses that child's `cancel` capability when the Agent advertises it. ### Why one `subagent_update` type instead of separate spawn and state notifications? The upsert announces an association and patches its capabilities without a separate create method. It also carries the parent's title and description for the child. Ordinary session updates handle the child's own conversation and, in v2, foreground work. Both versions carry a state snapshot on the association so the parent has roster information; v2 mirrors the child's ordinary notification. Neither version needs a second, permanently terminal subagent lifecycle. ### Why are there two `sessionId` fields in an association update? The fields have different scopes: `params.sessionId` is the parent whose stream receives the association update, while `params.update.sessionId` is the child being associated with it. The tagged `SessionUpdate` payload is flattened inside `update`, not into `params`, so these names do not collide. Directed messages instead use `senderSessionId` and `recipientSessionId` for their participants; the outer `sessionId` chooses the transcript being updated. See [Why session IDs appear in different places](#why-session-ids-appear-in-different-places). ### Why is `cancel` the only per-child capability? Stopping current work is a useful minimal control and maps to `session/cancel`. The Agent retains ownership of child resources; the Client does not need to attach, subscribe, or close each child merely to display it. The capability object leaves room for future controls without making those operations available implicitly. ### Why not subscribe to individual child streams? Selective delivery could reduce bandwidth and processing costs for large session trees, so it is worth revisiting. Clients can already choose which sessions to render or expand without changing event delivery. A future subscription proposal would need to distinguish transcript delivery from ownership announcements, capabilities, current work state, cancellation, and permission or elicitation requests. Hiding a transcript must not strand an interaction or make an unobserved child appear stopped. It would also need defined catch-up or snapshot behavior when a Client attaches, including gaps in retained history and ordering relative to live events. This RFD keeps automatic delivery and does not add attach/subscribe methods. ### Why remove the terminal `disconnected` state? The earlier draft correctly avoided inventing success, failure, or cancellation when the outcome was unknown. It unnecessarily made that uncertainty a permanent property of the child session. Connection availability and recorded operation outcomes are now separate: Clients show unconfirmed activity as unknown, and Agents may restore the same child without rewriting history or pretending to know what happened while disconnected. ### Why not model a subagent as a tool call? The two represent different things. A session owns a conversation; a tool call reports execution of a tool. An outgoing or incoming message should be renderable as ordinary content with a recipient or sender link, without requiring a tool-call card or a raw-input viewer. The directed-message updates provide that representation and support streaming. Actual tool operations can still be reported normally and can link to the sessions they operate on with `session` content, but their status does not define a child's lifetime or acknowledge that it processed a message. ### Why can both views of a message reference each other? A Client showing one transcript may need the other view's entry without having received or rendered it, for example to open a child's conversation at the message a parent sent. One reference would force that Client to search the other transcript first, so each view can name the other. Both are optional and can arrive in later updates, because an Agent may start streaming a view before it knows the other one's ID. Message IDs stay scoped to their transcript; requiring both views to share an ID would instead force the Agent to know the link before sending the first update of either view. ### Why do chunks carry only content? A message's identity, its participants and references, lives in one place: the `session_message` upsert, as message-level fields do for `agent_message`, whose chunks also carry only content. Identity on chunks would give the same fields two sources that can disagree, and would make a chunk patch message state even though its `_meta` does not. An Agent that learns the identity while streaming sends one metadata-only upsert, which needs no content. ### How does a Client get a subagent's initial task? From the incoming `session_message` in the child's transcript, as described in [Delegated tasks](#delegated-tasks). The first task is not a special case: it is the first session-directed message the child receives. Reporting it as a user message would attribute it to the human user, and storing it on `subagent_update` would conflate the child's current display metadata with its message history. ### Why report directories on the association rather than `session_info_update`? For ordinary sessions the Client chooses `cwd` and `additionalDirectories` during setup, and `session_info_update` deliberately omits them. Keeping that true for every session avoids a `session_info_update` field that is valid only for children. Like `title` and `description`, the directories are also roster information: a Client can show where each child runs from the parent's stream without collecting it from every child's stream. Configuration differs because `config_option_update` already reports it for every session. ### Why not report MCP servers or tools for a child? The Client supplies MCP server definitions for ordinary sessions, and those definitions can carry credentials in environment variables and headers. A child's tools may also come from sources inside the Agent that the Client cannot name. ACP does not report the available tools of an ordinary session either. Tool calls already show which tools a child actually uses. Reporting tool or server availability would be a separate proposal covering all sessions, not only children. The same applies to the child's system prompt: what the parent asks of a child appears in the session messages it sends. ### Why not allow prompting or steering a subagent? The parent Agent can message or reuse a child according to its runtime's semantics. This proposal does not expose the same control to the Client: direct user intervention may be unsupported or interfere with orchestration. A future per-child capability could opt into it without assuming every Agent can implement it. Some runtimes already let the user message a child directly. Claude Code, for example, accepts input on a subagent's transcript, and OpenCode's runtime can prompt a child session. The expected follow-up is a per-child `prompt` capability in `subagent_update.capabilities`, enabling `session/prompt` with the child's session ID. ### Do subagents have to be reusable? No. A one-shot child, created for one delegation and never given more work, is a valid and common use of this RFD. The Agent announces it, reports the incoming task and the child's traffic, and reports `idle` when it finishes. Later updates are optional. The RFD defines reusable sessions so that it does not limit the protocol to one-shot children. Agents whose runtimes reuse workers can keep a child's identity across assignments, and Agents whose runtimes do not can create a new child for each run. ### What do the association's title and description describe? They describe the child in its parent's view, so Clients can show multiple children directly from parent-session updates. `title` is a short display label; `description` supplies its role or purpose. The child's conversation may also have an ordinary session title, which does not replace these parent-owned labels. These fields are not the contents of the latest message sent to the child. Messages and operations retain their own content and history even when the parent revises the child's display metadata. There is no session-wide `task` field that rewrites earlier instructions. ### Is `session/fork` sufficient for subagents? No. Forking is initiated by the Client and creates a normal session derived from existing context. This RFD covers Agent-created sessions with a parent relationship and restricted Client controls. An Agent may use a fork internally to implement a subagent, but the wire semantics are different. ### What alternative approaches did you consider, and why did you settle on this one? * Put a `subagentId` on every existing update. This would duplicate routing information and require changing every update type. * Use only tool-call parent/child relationships. This cannot represent nested, independent session streams cleanly. * Treat children as unrestricted ACP sessions. This advertises methods that many agent-created workers cannot accept. * Add dedicated stop and close methods. Existing session methods already have the desired addressing and lifecycle semantics. * Use separate `subagent_spawned` and `subagent_state_update` notifications, as an earlier draft of this RFD did. Merged into one upsert-style update to match the v2 entity pattern. * Treat every completed task as the end of a child session. Rejected because Agents can reuse a child for later work. * Require child subscriptions or independent load/resume. Deferred: association already gives the Client automatic event delivery on the parent connection. Representing each child with a session ID reuses the most protocol machinery while the announcing update and positive capability allowlist capture the important difference from a user-facing session. ## Revision history * 2026-11-09: Stated that one-shot children, announced for a single delegation and never reused, conform to this RFD. Named a per-child `prompt` capability as the expected way to let Clients prompt a child in the future. Added a `session` variant to `ToolCallContent` so a tool call that spawns, waits on, or otherwise operates on a session can link to it. * 2026-11-09: Recommended reporting the task a parent gives a child, including the first one, as an incoming `session_message` in the child's transcript rather than a user message, so Clients can render it as communication between sessions. * 2026-10-30: In v2, optimistic cancellation skips tool calls in the session's `background` list, following the v2 Background Work RFD. * 2026-10-29: Removed the JSON-RPC batch rules, since ACP v2 no longer uses batches. * 2026-10-29: Added optional `cwd` and `additionalDirectories` to `subagent_update` so an Agent can report a child that runs outside its parent's workspace, such as in its own worktree. Unreported directories are inherited from the parent, and a child's root set is its own effective directories. Summarized how the rest of a child's session context is reported, and why MCP servers, tools, and system prompts are not. * 2026-10-27: Participant IDs and message references now follow the standard patch convention: `null` clears a stored value instead of leaving it unchanged. * 2026-10-22: Added optional `senderMessageId` on the incoming view and `recipientMessageId` on the outgoing view of a session-directed message, so a Client can go from either view to the other without inferring a link from equal IDs. Either can be supplied after the view starts streaming. Moved the participant IDs off `session_message_chunk`: chunks carry only content, and a message's participants and references arrive on `session_message` upserts. * 2026-10-13: In v2, a concrete top-level `_meta` object on `subagent_update` and `session_message` patches stored metadata by key, per [v2 Metadata Patches](/rfds/v2/meta-patches). v1 still replaces the whole object. * 2026-10-05: Limited the cancellation cascade to the descendant work that the cancelled work waits on, leaving other descendants, such as background children, to the Agent. Clients clean up a descendant's pending requests and tool calls only once it reports a cancelled `idle`. Closing a parent still ends all descendant work. * 2026-10-01: Added the `error` stop reason, with an optional JSON-RPC `error`, to the v1 idle snapshot so it keeps the v2 shape and a v1 child can report that its work failed, and preserved unrecognized v1 stop reasons as v2 does. v1's prompt response is unchanged. * 2026-09-24: Separated reusable session associations from tool-call operations, added whole and streamed session-directed messages with incoming and outgoing views, and distinguished parent-owned display metadata from the child's ordinary conversation metadata. Replaced the terminal lifecycle enum with v1 work-state snapshots and normal v2 state notifications. Made event delivery automatic, left runtime restoration to the Agent, retained ordinary optimistic cancellation without requiring generic request cancellation, and added nonterminal unknown activity and routing-only ancestor recovery. Clarified the distinct session ID roles, incorporated provider integration and validation requirements, and preserved provider-reported costs without inferred cross-session aggregation. Aligned cancellation with object capabilities, allowed messages back to parents and other known sessions, and made child-history replay explicitly best-effort while retaining live identity and ordering guarantees. * 2026-09-15: Merged `subagent_spawned` and `subagent_state_update` into a single upsert-style `subagent_update` following the v2 entity pattern, made `name`, `task`, and `capabilities` optional, added an explicit `running` state, removed the Agent-side capability and the per-child `close` capability, stopped implying that a child inherits the parent's execution context, and allowed SDKs to buffer updates for unannounced children. Added the same `subagent_update` to the v2 schema: capability-free, with v2 patch semantics and an open state enum. * 2026-08-31: Defined the Client-local `disconnected` state for unknown outcomes on a live connection, required pending permission and elicitation requests to resolve before the terminal lifecycle update with defined race handling, and made SDK preservation of the draft fields an explicit rollout prerequisite. * 2026-08-25: Defined child reconnection, replay, orphan, and disconnected lifecycle semantics. * 2026-08-19: Initial draft. # Tool Call Name Source: https://agentclientprotocol.com/rfds/tool-call-name Author(s): [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? Add an optional `name` field to tool calls in ACP v1 and v2. The field carries the programmatic name of the invoked tool so Clients can show users which tool is being used, in addition to the human-readable description of what that invocation is doing. ## Status quo > How do things work today and what problems does this cause? Why would we change things? Tool calls currently provide a `title` and `kind`, but neither identifies the invoked tool: * `title` is human-readable UI copy for a particular invocation, such as `Reading configuration file`. * `kind` is a coarse presentation category, such as `read` or `execute`, that helps a Client choose an icon or other generic treatment. Many different tools can share the same kind, and titles may be localized or generated from the tool input. Clients therefore cannot reliably show whether an Agent used `read_file`, `grep`, `run_command`, or another tool. Inferring the tool from `title` or `rawInput` would be brittle and implementation-specific. This is particularly helpful in an eval context as well, where you want to track metrics of various tool uses. ## What we propose to do about it > What are you proposing to improve the situation? Add `name` to the existing tool-call shapes. It is the programmatic identifier by which the Agent or model addressed the tool. For example: ```json theme={null} { "sessionUpdate": "tool_call", "toolCallId": "call_001", "name": "read_file", "title": "Reading configuration file", "kind": "read", "status": "pending" } ``` The corresponding v2 report uses the same field on its upsert shape: ```json theme={null} { "sessionUpdate": "tool_call_update", "toolCallId": "call_001", "name": "read_file", "title": "Reading configuration file", "kind": "read", "status": "pending" } ``` `name` is distinct from the existing fields: * `toolCallId` identifies one invocation within a session. * `name` identifies the tool being invoked and can be reused by many calls. * `title` describes this invocation in human-readable UI copy. * `kind` groups the tool into a coarse presentation category. Tool names are opaque strings. ACP does not define a naming or namespacing scheme. An Agent reporting an MCP or function call should use the programmatic name by which it exposes that tool; if the Agent qualifies or rewrites names, it reports that resulting name. ACP assigns no behavioral or authorization semantics to the spelling. Clients **MAY** show it as a secondary label or in tool-call details while continuing to use `title` as the primary description. Agents **SHOULD** include `name` in the first report for a tool call when it is available, and **SHOULD NOT** change it later except to correct previously reported metadata. ### Wire semantics The field is optional and nullable in every shape where it appears, but the effect of `null` follows each protocol version's existing update model: | Carrier | Omitted | `null` | String value | | - | - | - | - | | v1 `ToolCall` | No name is provided | Equivalent to omission | Records the tool name | | v1 `ToolCallUpdate` | Leaves the existing name unchanged | Equivalent to omission; leaves the existing name unchanged | Sets or replaces the existing name | | v2 `ToolCallUpdate` | Leaves the existing name unchanged | Explicitly clears the existing name | Sets or replaces the existing name | ACP v1 cannot explicitly clear a previously supplied tool name. For a new v2 `toolCallId`, omission and `null` both result in a tool call with no name. Because v1 permission requests carry a `ToolCallUpdate`, and v2 tool-call permission subjects carry the v2 `ToolCallUpdate`, Agents can also include `name` when asking permission without adding another permission-specific field. ## Shiny future > How will things will play out once this feature exists? Users can see both what an invocation is doing and which tool is doing it. A Client might render `Reading configuration file` as the main title, `read_file` as a secondary label, and a read icon selected from `kind: "read"`. Agents no longer need to encode the programmatic tool name into the title or use an implementation-specific `_meta` key. Clients can expose tool identity consistently in detailed views, permission UI, logs, and debugging tools. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? The optional `name` field is implemented in the stable v1 and v2 schema baselines and SDK types. v1 includes it on `ToolCall` and `ToolCallUpdateFields`; v2 includes it as a three-state patch on `ToolCallUpdate`. The protocol guides document the version-specific update and cross-version conversion semantics. ACP v2 as a whole remains behind its existing `unstable_protocol_v2` Rust feature while the v2 protocol is in Draft. Stabilizing this field does not stabilize the rest of v2. ### Compatibility and conversion The proposal is additive. Peers that do not know about `name` continue to use `title`, `kind`, and the remaining tool-call fields. No capability is required; an Agent can omit `name` whenever it is unavailable or inappropriate to expose. Cross-version adapters can preserve concrete names in both directions. An absent v1 name maps to an omitted v2 patch field. An omitted v2 field maps to an absent v1 update. A v2 `name: null` clear cannot be represented by v1, where `null` and omission both mean "leave unchanged" on an update. A strict adapter must report this case as unrepresentable. A deliberately lossy bridge may omit the clear, leaving the previous v1 name in place. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why use `name` instead of `toolName`? The field is already scoped to a tool-call object, so `toolName` would repeat that context. `name` also matches the terminology used by MCP tools and common function-calling APIs. ### Why is there no capability? `name` is optional display metadata and does not change how a tool call is identified, executed, or authorized. Clients that do not recognize the field can ignore it without changing protocol behavior, and Agents can omit it when the name is unavailable or inappropriate to expose. A capability would only indicate whether a Client might display the hint; it would not affect the correctness of the interaction. ### Why is this not part of `title`? `title` is user-facing copy about an invocation and may change as work progresses. `name` is the programmatic identity of the invoked tool. Keeping them separate lets Clients render either or both without parsing display text. ### Why is this not part of `kind`? `kind` intentionally has a small set of presentation categories. Many tools can be `read`, `edit`, `execute`, or `other`; expanding `kind` into a registry of exact tool names would prevent Clients from using it as a stable UI hint. ### What alternative approaches did you consider, and why did you settle on this one? **Put the name in `_meta`** - This works for coordinated implementations, but does not give interoperable Clients a standard field to display. **Derive the name from `title` or `rawInput`** - Those fields do not have a stable relationship to tool identity, so inference would be unreliable. **Use `toolName`** - More explicit in isolation, but redundant inside a tool call and inconsistent with MCP and function-call naming. ## Revision history * 2026-07-21: Initial draft. * 2026-09-14: Moved to Preview. * 2026-09-17: Moved to Completed and stabilized the v1 and v2 schema and SDK surfaces. # RFD Updates Source: https://agentclientprotocol.com/rfds/updates Lifecycle updates for ACP Requests for Dialog This page tracks lifecycle changes for ACP Requests for Dialog. For broader ACP announcements, see [Updates](/updates). **November 6, 2026** ## Client-Provided System Prompt RFD moves to Completed The Client-Provided System Prompt RFD has been stabilized and is now included in the protocol schemas and guides for ACP v1 and v2. See the [v1 guide](/protocol/v1/session-setup#system-prompt), the [v2 guide](/protocol/v2/session-setup#system-prompt), and the [RFD](/rfds/client-system-prompt) for delivery modes, lifecycle, and error semantics. **October 30, 2026** ## Client-Provided System Prompt RFD moves to Preview stage The Client-Provided System Prompt RFD has moved to Preview. Clients can send `systemPrompt` on session setup in `append` mode, or in `override` mode when the Agent advertises it. The protocol implementation covers ACP v1 and v2, and implementations have landed in the Claude Agent and Codex adapters. The feature remains unstable. Please review the [RFD](/rfds/client-system-prompt) and provide Agent/Client interoperability feedback before stabilization. **October 29, 2026** ## Delete in Diff RFD removed The Delete in Diff RFD has been removed. Its proposed `deleted` flag on v1 diffs was never added to the schema, and ACP v2 covers file deletions through the diff change operations in the [Diff File States RFD](/rfds/v2/diff-file-states). **October 28, 2026** ## Session Archive RFD moves to Draft stage The RFD for `session/archive` and `session/unarchive` methods, which let Clients reversibly hide sessions from default history and restore them later, has moved to Draft stage. Please review the [RFD](/rfds/session-archive) for more information and provide feedback on the list filter and active-session semantics. **October 26, 2026** ## Client-Set Session Titles RFD moves to Draft stage The RFD for a `session/set_title` method, which lets Clients set a session's title, has moved to Draft stage. Please review the [RFD](/rfds/session-set-title) and provide feedback. **October 26, 2026** ## Session Status RFD moves to Draft stage The RFD for a side-effect-free `session/status` method, which reports whether an Agent has a session in memory, knows it but has not loaded it, or does not know it at all, has moved to Draft stage. Please review the [RFD](/rfds/session-status) for more information and provide feedback on the status values and connection semantics. **October 12, 2026** ## Client-Provided System Prompt RFD moves to Draft stage The RFD for letting Clients provide session-scoped system prompt instructions in ACP v1 and v2 has moved to Draft stage. Please review the [RFD](/rfds/client-system-prompt) for more information and provide feedback on the delivery modes and session lifecycle semantics. **October 9, 2026** ## Session Notices RFD moves to Completed The Session Notices RFD has been stabilized and is now included in the protocol schemas and guides for ACP v1 and v2. See the [v1 guide](/protocol/v1/prompt-turn#session-notices), the [v2 guide](/protocol/v2/prompt-lifecycle#session-notices), and the [RFD](/rfds/session-notices) for delivery, presentation, and replay semantics. **October 6, 2026** ## Session Compaction RFD moves to Completed The Session Compaction RFD has been stabilized and is now included in the protocol schemas and guides for ACP v1 and v2. V1 delivery and replay still require the Client's `session.compaction` capability; v2 does not require a capability. See the [v1 guide](/protocol/v1/prompt-turn#session-compaction), the [v2 guide](/protocol/v2/prompt-lifecycle#session-compaction), and the [RFD](/rfds/session-compaction) for patch, ordering, and replay semantics. **September 30, 2026** ## Next Edit Suggestions RFD removed The Next Edit Suggestions (NES) RFD and its unstable implementation have been removed from ACP v1 and v2. This includes NES methods and capabilities, associated document-event notifications, and position-encoding negotiation. **September 30, 2026** ## Next Edit Suggestions RFD moves to To be removed The Next Edit Suggestions (NES) RFD moved to "To be removed" because the proposal was no longer being pursued. Its draft implementation was scheduled for removal. See the [removal update](#next-edit-suggestions-rfd-removed) for the subsequent cleanup. **September 24, 2026** ## Session Notices RFD moves to Preview stage The Session Notices RFD has moved to Preview. Agents can send live user-facing notices without adding conversation history, with Client-controlled presentation and dismissal. The protocol implementation covers ACP v1 and v2; v1 implementations have landed in Zed and the Claude Agent and Codex adapters. The feature remains unstable. Please review the [RFD](/rfds/session-notices) and provide Agent/Client interoperability feedback before stabilization. **September 23, 2026** ## Session Compaction RFD moves to Preview stage The Session Compaction RFD has moved to Preview. Agents can report ID-addressed context compaction lifecycle updates and optionally stream or provide retained summaries in ACP v1 and v2. The feature remains unstable. Please review the [RFD](/rfds/session-compaction), especially the [Preview validation targets](/rfds/session-compaction#preview-validation), and provide Agent/Client implementation feedback before the feature is stabilized. **September 17, 2026** ## Tool Call Name RFD moves to Completed The Tool Call Name RFD has been stabilized and is now part of the protocol. Agents can report an optional programmatic tool `name` alongside each human-readable tool-call title in ACP v1 and v2. The field is informational metadata and does not grant capabilities or authorization. Please review the [v1 tool-call documentation](/protocol/v1/tool-calls), the [v2 tool-call documentation](/protocol/v2/tool-calls), and the [RFD](/rfds/tool-call-name) for the version-specific update semantics. **September 14, 2026** ## Tool Call Name RFD moves to Preview stage The RFD for adding an optional programmatic `name` to tool calls in ACP v1 and v2 has moved to Preview stage. Please review the [RFD](/rfds/tool-call-name) for more information on the current proposal and provide feedback before the feature is stabilized. **August 20, 2026** ## Terminal Authentication RFD moves to Completed The Terminal Authentication RFD has been stabilized and is now part of the protocol. Clients can advertise terminal authentication support, run an Agent's configured interactive login flow, and reconnect after it succeeds. The v1 and v2 wire shapes are now included in the stable schemas and SDK types. Please review the [authentication documentation](/protocol/v1/authentication) and the [RFD](/rfds/auth-methods) for the version-specific capability and lifecycle semantics. **August 5, 2026** ## Session Notices RFD moves to Draft stage The RFD for fire-and-forget, Client-presented session notices in ACP v1 and v2 has moved to Draft stage. Please review the [RFD](/rfds/session-notices) for more information and provide feedback on the event and presentation semantics. **August 5, 2026** ## Session Compaction RFD moves to Draft stage The RFD for reporting ID-addressed context compaction lifecycle and optional retained summaries in ACP v1 and v2 has moved to Draft stage. Please review the [RFD](/rfds/session-compaction) for more information and provide feedback while the entity and replay semantics are refined. **July 27, 2026** ## Terminal Authentication RFD moves to Preview The Terminal Authentication RFD has moved to Preview. Clients can run an Agent's interactive login flow in a terminal and reconnect after it succeeds. The proposal now focuses on terminal authentication. The experimental `env_var` method has been removed as an explicit SDK and schema variant. Please review the [RFD](/rfds/auth-methods) for the version-specific wire shapes and lifecycle semantics. **July 24, 2026** ## Elicitation RFD moves to Completed The RFD for structured user input through `elicitation/create` has been stabilized and is now part of the protocol. Agents can request form-based structured input or URL-based out-of-band interactions, and Clients advertise each mode they support explicitly. Please review the [documentation](/protocol/v1/elicitation) for more information. **July 21, 2026** ## auth/status RFD moves to Draft stage The RFD for allowing clients to query an agent's current authentication state has moved to Draft stage. Please review the [RFD](/rfds/get-auth-state) for more information and provide feedback as work on the implementation begins. **July 21, 2026** ## Tool Call Name RFD moves to Draft stage The RFD for adding an optional programmatic `name` to tool calls in ACP v1 and v2 has moved to Draft stage. Please review the [RFD](/rfds/tool-call-name) for more information and provide feedback while the draft implementation is exercised. **July 9, 2026** ## Elicitation RFD moves to Preview stage The RFD for structured user input through `elicitation/create` has been moved to Preview stage. Please review the [RFD](/rfds/elicitation) for more information on the current proposal and provide feedback before the feature is stabilized. **July 6, 2026** ## Boolean Config Option RFD moves to Completed The RFD for boolean session configuration options has been stabilized and is now part of the protocol. Agents can expose simple on/off toggles with `type: "boolean"` config options, and Clients opt in on v1 by advertising the `session.configOptions.boolean` capability. Please review the [documentation](/protocol/v1/session-config-options#boolean-config-options) for more information. **July 2, 2026** ## Agent Telemetry Export RFD removed The Agent Telemetry Export RFD has been removed. Its design relied on clients injecting OpenTelemetry environment variables when launching agent subprocesses, which doesn't translate to the new remote transports where agents aren't launched by the client. Since the approach required no changes to the protocol itself, clients and agents that want this setup can adopt standard [OpenTelemetry SDK environment variable configuration](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/) directly. **July 2, 2026** ## Active RFD stage added The RFD lifecycle now includes an Active stage between Draft and Preview. Active RFDs are the proposals that core maintainers or a working group are currently spending bandwidth on. **June 30, 2026** ## Boolean Config Option RFD moves to Preview stage The RFD for adding boolean session configuration options has been moved to Preview stage. Please review the [RFD](/rfds/boolean-config-option) for more information on the current proposal and provide feedback before the feature is stabilized. **June 29, 2026** ## Request Cancellation RFD moves to Completed The RFD for `$/cancel_request` protocol-level request cancellation has been stabilized and is now part of the protocol. Either side can send this notification to request cancellation of an outstanding JSON-RPC request by ID. Please review the [documentation](/protocol/v1/cancellation) for more information. **June 25, 2026** ## Rust SDK based on SACP RFD moves to Completed The RFD for basing the Rust SDK on SACP has been completed with the 1.0 SDK releases. The Rust SDK is available as [`agent-client-protocol` v1.0.0](https://crates.io/crates/agent-client-protocol/1.0.0), and the TypeScript SDK reached the same milestone with [`@agentclientprotocol/sdk` v1.0.0](https://www.npmjs.com/package/@agentclientprotocol/sdk/v/1.0.0), showing that the SDK design goals apply beyond Rust. **June 24, 2026** ## model\_config Category RFD moves to Completed The RFD for the `model_config` session configuration option category has been stabilized and is now a part of the protocol. Agents can use `model_config` for model-related parameters such as context size or speed/quality trade-offs. Please review the [documentation](/protocol/v1/session-config-options#option-categories) for more information. **June 24, 2026** ## Request Cancellation RFD moves to Preview stage The RFD for adding `$/cancel_request` protocol-level request cancellation has been moved to Preview stage. Please review the [RFD](/rfds/request-cancellation) for more information on the current proposal and provide feedback before the feature is stabilized. **June 22, 2026** ## model\_config Category RFD moves to Preview stage The RFD for the `model_config` session configuration option category has been moved to Preview stage. Please review the [RFD](/rfds/model-config-category) for more information on the current proposal and provide feedback before the feature is stabilized. **June 5, 2026** ## Message ID RFD moves to Completed The RFD for adding agent-generated `messageId` fields to streamed message chunks has been stabilized and is now part of the protocol. In v1, message IDs are optional on message chunks for compatibility; in v2, they are required. Please review the [documentation](/protocol/v1/prompt-turn#message-ids) for more information. **June 5, 2026** ## Session Context Size and Cost RFD moves to Completed The RFD for `usage_update` session notifications has been stabilized and is now a part of the protocol. Agents can report session-level context window size and optional cumulative cost through `session/update`. Please review the [documentation](/protocol/v1/prompt-turn#session-usage-updates) for more information. **June 5, 2026** ## session/delete RFD moves to Completed The RFD for allowing clients to delete a given session has been stabilized and is now a part of the protocol. Please review the [documentation](/protocol/v1/session-delete) for more information. **June 3, 2026** ## \_meta Propagation RFD moves to Completed The RFD for documenting `_meta` propagation conventions for correlation metadata has been completed and is now part of the protocol documentation. Please review the [documentation](/protocol/v1/extensibility#the-_meta-field) for more information. **June 3, 2026** ## Message ID RFD moves to Preview stage for v1 The v1 portion of the RFD for adding message IDs to streamed message chunks has been moved to Preview stage. Please review the [RFD](/rfds/message-id) for more information on the current proposal and provide feedback before the v1 behavior is stabilized. **June 3, 2026** ## Session Usage RFD moves to Preview stage The RFD for adding `usage_update` session notifications for context window size and cumulative session cost has been moved to Preview stage. Please review the [RFD](/rfds/session-usage) for more information on the current proposal and provide feedback before the feature is stabilized. **June 2, 2026** ## v2 Plan Variants RFD moves to Draft stage The RFD for making item-based `plan_update` the default v2 plan shape has been moved to Draft stage. Please review the [RFD](/rfds/v2/plan-variants) for more information on replacing the old v1 `plan` update in v2 while the broader Plan Operations RFD continues. **June 2, 2026** ## End-Turn Token Usage RFD moves to Draft stage The end-turn token usage portions of the original Session Usage RFD have been split into a separate Draft RFD for further design work. Please review the [RFD](/rfds/end-turn-token-usage) for more information on the current proposal and provide feedback. **June 2, 2026** ## session/delete RFD moves to Preview stage The RFD for allowing clients to delete a given session has been moved to Preview stage. Please review the [RFD](/rfds/session-delete) for more information on the current proposal and provide feedback before the feature is stabilized. **June 1, 2026** ## Unstable Session Model API removed The never-stabilized `session/set_model` API and related session model response fields have been removed from the protocol artifacts. Agents should continue to expose model selection through [Session Config Options](/rfds/session-config-options). **June 1, 2026** ## Additional Directories RFD moves to Completed The RFD for allowing clients to specify additional workspace roots for session lifecycle requests has been stabilized and is now a part of the protocol. Please review the [documentation](/protocol/v1/session-setup#additional-workspace-roots) for more information. **May 27, 2026** ## v2 Enum Variant Extension RFD moves to Draft stage The RFD for reserving `_`-prefixed enum variants for extensions while preserving non-underscore variants for future ACP versions has been moved to Draft stage. Please review the [RFD](/rfds/v2/enum-variant-extension) for more information on the current proposal and provide feedback as work on v2 continues. **May 27, 2026** ## Plan Operations Support RFD moves to Draft stage The RFD for adding `plan_update` and `plan_removed` session update types has been moved to Draft stage. Please review the [RFD](/rfds/plan-operations) for more information on the current proposal and provide feedback as work on the implementation begins. **May 22, 2026** ## Logout Method RFD moves to Completed The RFD for the `logout` method has been stabilized and is now a part of the protocol. Please review the [documentation](/protocol/v1/authentication#logging-out) for more information. **May 21, 2026** ## Additional Directories RFD moves to Preview stage The RFD for allowing clients to specify additional workspace roots for session lifecycle requests has been moved to Preview stage. Please review the [RFD](/rfds/additional-directories) for more information on the current proposal and provide feedback before the feature is stabilized. **May 17, 2026** ## Logout Method RFD moves to Preview stage The RFD for adding a `logout` method to the protocol has been moved to Preview stage. Please review the [RFD](/rfds/logout-method) for more information on the current proposal and provide feedback before the feature is stabilized. **May 12, 2026** ## Rust SDK based on SACP RFD moves to Preview stage The RFD for basing the Rust SDK on SACP has been moved to Preview stage now that the initial crate import has been upstreamed to [agentclientprotocol/rust-sdk](https://github.com/agentclientprotocol/rust-sdk). Please review the [RFD](/rfds/rust-sdk-v1) for more information on the current proposal and provide feedback before the SDK is stabilized as 1.0. **May 7, 2026** ## model\_config Category RFD moves to Draft The RFD for the `model_config` category been moved to Draft stage. Please review the [RFD](/rfds/model-config-category) for more information on the current proposal and provide feedback before the feature is stabilized. **April 23, 2026** ## v2 Prompting RFD moves to Draft The RFD for how the prompt lifecycle will work in v2 of the protocol been moved to Draft stage. Please review the [RFD](/rfds/v2/prompt) for more information on the current proposal and provide feedback before the feature is stabilized. **April 23, 2026** ## session/close RFD moves to Completed The RFD for the `session/close` method has been stabilized and is now a part of the protocol. Please review the [documentation](/protocol/v1/session-setup#closing-active-sessions) for more information. **April 22, 2026** ## session/resume RFD moves to Completed The RFD for the `session/resume` method has been stabilized and is now a part of the protocol. Please review the [documentation](/protocol/v1/session-setup#resuming-sessions) for more information. **April 22, 2026** ## Streamable HTTP & WebSocket Transport RFD moves to Draft stage The RFD for standardizing a remote ACP transport based on MCP Streamable HTTP with a WebSocket upgrade has been moved to Draft stage. Please review the [RFD](/rfds/streamable-http-websocket-transport) for more information on the current proposal and provide feedback as work on the implementation begins. **April 14, 2026** ## session/resume RFD moves to Preview stage The RFD for adding a `session/resume` method to the protocol has been moved to Preview stage. Please review the [RFD](/rfds/session-resume) for more information on the current proposal and provide feedback before the feature is stabilized. **April 14, 2026** ## session/close RFD moves to Preview stage The RFD for allowing agents to close a given session has been moved to Preview stage. Please review the [RFD](/rfds/session-close) for more information on the current proposal and provide feedback before the feature is stabilized. **March 27, 2026** ## Custom LLM Endpoint RFD moves to Draft stage The RFD for allowing clients to specify custom provider configuration has been moved to Draft stage. Please review the [RFD](/rfds/custom-llm-endpoint) for more information on the current proposal and provide feedback as work on the implementation begins. **March 24, 2026** ## Additional Directories RFD moves to Draft stage The RFD for allowing clients to specify additional directories for the agent to access has been moved to Draft stage. Please review the [RFD](/rfds/additional-directories) for more information on the current proposal and provide feedback as work on the implementation begins. **March 9, 2026** ## ACP Registry RFD moves to Completed The RFD for the initial version of the ACP Registry has been completed. Please review the [documentation](/get-started/registry) for more information. ## session\_info\_update Notification RFD moves to Completed The RFD for the session\_info\_update notification has been stabilized and is now a part of the protocol. Please review the [documentation](/protocol/v1/session-list#updating-session-metadata) for more information. ## session/list RFD moves to Completed The RFD for the session/list method has been stabilized and is now a part of the protocol. Please review the [documentation](/protocol/v1/session-list) for more information. **February 24, 2026** ## Next Edit Suggestions RFD moves to Draft stage The RFD for allowing agents to provide next edit suggestions moved to Draft stage. It was subsequently removed; see the [removal update](#next-edit-suggestions-rfd-removed). ## session/close RFD moves to Draft stage The RFD for allowing agents to close a given session has been moved to Draft stage. Please review the [RFD](/rfds/session-close) for more information on the current proposal and provide feedback as work on the implementation begins. ## Elicitation RFD moves to Draft stage The RFD for allowing agents to elicit user input has been moved to Draft stage. Please review the [RFD](/rfds/elicitation) for more information on the current proposal and provide feedback as work on the implementation begins. ## Boolean Config Option RFD moves to Draft stage The RFD for adding boolean config options to the protocol has been moved to Draft stage. Please review the [RFD](/rfds/boolean-config-option) for more information on the current proposal and provide feedback as work on the implementation begins. **February 20, 2026** ## Delete in Diff RFD moves to Draft stage The RFD for indicating whether a diff resulted in a file deletion has been moved to Draft stage. (This RFD was later removed — see the October 29, 2026 update.) **February 18, 2026** ## Message ID RFD moves to Draft stage The RFD for adding message ids to the protocol has been moved to Draft stage. Please review the [RFD](/rfds/message-id) for more information on the current proposal and provide feedback as work on the implementation begins. **February 18, 2026** ## session/list RFD moves to Preview stage The RFD for the session/list method has been moved to Preview stage. Please review the [RFD](/rfds/session-list) for more information on the current proposal and provide feedback before the feature is stabilized. ## session\_info\_update RFD moves to Preview stage The RFD for the session\_info\_update notification has been moved to Preview stage. Please review the [RFD](/rfds/session-info-update) for more information on the current proposal and provide feedback before the feature is stabilized. **February 10, 2026** ## ACP Registry RFD moves to Preview stage The RFD for the ACP Registry has been moved to Preview stage. Please review the [RFD](/rfds/acp-agent-registry) for more information on the current proposal and provide feedback before the feature is stabilized. **February 4, 2026** ## Session Config Options RFD moves to Completed The RFD for adding more generic Session Config Options to the protocol has been stabilized and is now a part of the protocol. Please review the [documentation](/protocol/v1/session-config-options) for more information. **February 4, 2026** ## session/delete moves to Draft stage The RFD for allowing clients to delete a given session has been moved to Draft stage. Please review the [RFD](/rfds/session-delete) for more information on the current proposal and provide feedback as work on the implementation begins. ## Logout method moves to Draft stage The RFD for allowing clients to logout from an agent connection has been moved to Draft stage. Please review the [RFD](/rfds/logout-method) for more information on the current proposal and provide feedback as work on the implementation begins. **January 15, 2026** ## Rust SDK based on SACP RFD moves to Draft stage The RFD for basing the Rust SDK on SACP has been moved to Draft stage. Please review the [RFD](/rfds/rust-sdk-v1) for more information on the current proposal and provide feedback as work on the implementation begins. **January 15, 2026** ## Session Config Options RFD moves to Preview stage The RFD for adding more generic Session Config Options to the protocol has been moved to Preview stage. Please review the [RFD](/rfds/session-config-options) for more information on the current proposal and provide feedback before the feature is stabilized. **January 14, 2026** ## Authentication Methods RFD moves to Draft stage The RFD for creating additional types of authentication methods has been moved to Draft stage. Please review the [RFD](/rfds/auth-methods) for more information on the current proposal and provide feedback as work on the implementation begins. **January 1, 2026** ## Agent Registry RFD moves to Draft stage The RFD for creating an Agent Registry has been moved to Draft stage. Please review the [RFD](/rfds/acp-agent-registry) for more information on the current proposal and provide feedback as work on the implementation begins. ## Session Usage RFD moves to Draft stage The RFD for adding a new usage\_update variant on the session/update notification and usage field on prompt responses in the protocol has been moved to Draft stage. Please review the [RFD](/rfds/session-usage) for more information on the current proposal and provide feedback as work on the implementation begins. **December 31, 2025** ## Proxy Chains RFD moves to Draft stage The RFD for adding proxy chain functionality in the protocol has been moved to Draft stage. Please review the [RFD](/rfds/proxy-chains) for more information on the current proposal and provide feedback as work on the implementation begins. **December 11, 2025** ## Agent Telemetry Export RFD moves to Draft stage The RFD for providing more guidance on how agents should export telemetry has been moved to Draft stage. (This RFD was later removed — see the July 2, 2026 update.) **December 3, 2025** ## session\_info\_update notification RFD moves to Draft stage The RFD for adding a new session\_info\_update variant on the session/update notification in the protocol has been moved to Draft stage. Please review the [RFD](/rfds/session-info-update) for more information on the current proposal and provide feedback as work on the implementation begins. ## \_meta Propagation RFD moves to Draft stage The RFD for providing more guidance on how the \_meta parameter should be used within the protocol has been moved to Draft stage. Please review the [RFD](/rfds/meta-propagation) for more information on the current proposal and provide feedback as work on the implementation begins. **November 26, 2025** ## session/resume RFD moves to Draft stage The RFD for adding a session/resume method to the protocol has been moved to Draft stage. Please review the [RFD](/rfds/session-resume) for more information on the current proposal and provide feedback as work on the implementation begins. **November 20, 2025** ## \$/cancelRequest RFD moves to Draft stage The RFD for adding a \$/cancelRequest method to the protocol has been moved to Draft stage. Please review the [RFD](/rfds/request-cancellation) for more information on the current proposal and provide feedback as work on the implementation begins. ## session/fork RFD moves to Draft stage The RFD for adding a session/fork method to the protocol has been moved to Draft stage. Please review the [RFD](/rfds/session-fork) for more information on the current proposal and provide feedback as work on the implementation begins. **November 3, 2025** ## Session Config Options RFD moves to Draft stage The RFD for adding more generic Session Config Options to the protocol has been moved to Draft stage. Please review the [RFD](/rfds/session-config-options) for more information on the current proposal and provide feedback as work on the implementation begins. **October 31, 2025** ## session/list RFD moves to Draft stage The RFD for adding a session/list method to the protocol has been moved to Draft stage. Please review the [RFD](/rfds/session-list) for more information on the current proposal and provide feedback as work on the implementation begins. # v2 Background Work Source: https://agentclientprotocol.com/rfds/v2/background-work Author(s): [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? ACP v2 already separates foreground work from background activity: `state_update` reports whether the session is `running`, `requires_action`, or `idle`, and background activity may continue while the session is `idle`. What it does not tell a Client is *whether* anything is still running in the background, *what* it is, or whether the Client can stop it. This RFD reuses the entities ACP already has instead of adding a new one: * **Terminals and tool calls can outlive the foreground work that started them.** A backgrounded shell is a [terminal](./terminal-output.mdx) that keeps running after control returns to the model. A watcher or a scheduled wakeup is a tool call that stays `pending` or `in_progress` after the session becomes `idle`. * **Terminals and tool calls can be cancelled individually.** Either can advertise `capabilities.cancel`, and the Client cancels it with a new `terminal/cancel` or `tool_call/cancel` request, without cancelling the session's foreground work. * **State snapshots list the background work.** Every `state_update` can carry a `background` list referencing the terminals, tool calls, and subagent sessions that are running independently of foreground work. Clients use it to show that something is still running, to warn before closing, and to tell background work apart from stale tool calls and terminals. ## Status quo > How do things work today and what problems does this cause? Why would we change things? Coding agents now routinely leave work running after they finish responding: * **Claude Code / Claude Agent SDK:** * `Bash` with `run_in_background`, Ctrl+B, or a command that hits its timeout keeps running after the turn. * Subagents run in the background by default. * `Monitor` watches a script or WebSocket. * `Workflow` runs local or remote multi-agent scripts. A workflow can be paused, which stops its agents but keeps its journal so it can be resumed later. * `ScheduleWakeup` and `CronCreate` start new turns later. * The SDK reports these as tasks (`task_started`, `task_updated`, `task_notification`) and sends the full live set in `background_tasks_changed`. Task statuses include `paused`. * The SDK also reports housekeeping that Claude Code starts on its own, such as memory consolidation, the auto-mode scan, and auto-started WebSocket watchers, and marks those tasks `ambient` so hosts leave them out of activity indicators. Work the model requests, including `Monitor`, is not ambient. * **Codex:** * Unified-exec commands keep running as background terminals after the turn, and collab subagents can outlive the root turn. * `ThreadStatus` has no flag for background terminals, so a thread reports `idle` while terminals run. * Codex has experimental `thread/backgroundTerminals/list`, `/terminate`, and `/clean` requests, and its TUI has `/ps` and `/stop` for them. * **Others:** Gemini CLI (`is_background` shells), Cursor (`is_background` terminal commands), and Cline ("Proceed While Running") have similar features. opencode's session status only has `idle`, `busy`, and `retry`. ACP v2 says this activity may exist ([Foreground and Background Work](/protocol/v2/prompt-lifecycle#foreground-and-background-work)) and shows a detached tool call reporting progress while the session stays `idle`. It leaves the rest undefined: * **Clients can't tell whether the session is quiet.** `idle` means ready for a new prompt, not "nothing is running". Clients can't safely show a session as done, close it to save resources, or warn the user that closing will stop a dev server. * **Unfinished tool calls are ambiguous.** Agents often leave stale `pending` or `in_progress` tool calls behind, so many Clients mark every unfinished tool call as finished when work ends. That cleanup is wrong for a tool call that is still running in the background, and without that cleanup stale tool calls stay unfinished. * **Background work can't be stopped individually.** v2 terminals are display-only by design. `session/cancel` only targets the session's current work, and agents differ on whether it stops background work. Only subagents can be cancelled one at a time. * **Close and resume are underspecified.** `session/close` cancels "any ongoing work", but nothing says Clients will learn what was stopped. After `session/resume`, the Client gets a foreground snapshot but no record of background work that is still running. Adapters are working around this today. Both `claude-agent-acp` and `codex-acp` implement a private extension (`async_task_spawned`, `async_task_state_update`, `_session/async_task/stop`) that only one Client negotiates, so other Clients see nothing. That extension also adds another entity alongside tool calls, terminals, and subagents, with its own ids, statuses, and output path, for work that already has a tool call or terminal. ## What we propose to do about it > What are you proposing to improve the situation? ### Background work is terminals, tool calls, and subagents Background work is session-owned work that is running independently of the session's foreground work. In v2 it is represented by entities the Client already tracks: * **Terminals.** A process that keeps running after its tool call returns control to the model, such as a backgrounded shell or dev server, is a [terminal](./terminal-output.mdx). It is live until its `terminal_update` reports `exitStatus`. The tool call that started it keeps referencing the terminal so the Client can show its output in place, and reports status as the agent's own tool lifecycle does: it may complete once the process has been handed off, as Claude Code's Bash tool does, or stay `in_progress` until the process exits, as Codex's command items do. Either way, the terminal is what is listed. While a terminal is listed, the Agent **SHOULD** keep its output current with `terminal_output_chunk` or replacement snapshots whenever it can read the process output. An Agent that can't read the output may report only the terminal's command and, later, its `exitStatus`. Output is not a liveness signal: a Client **MUST NOT** treat a terminal as hung or exited because its output is missing or stale. Only the `background` list and `exitStatus` say whether it is still running. * **Tool calls.** Work that continues without a process of its own, such as a watcher, a workflow, or a scheduled wakeup, keeps reporting status on the same `toolCallId`. Its output stays in tool call content. * **Subagent sessions.** A background child keeps reporting through its [subagent](../subagents.mdx) association and `state`. Terminals, tool calls, and subagents may continue after the session reports `idle`. Their updates do not change the foreground state, as already specified. No new entity type is added. Anything an agent runs in the background is a process, work started by a tool call, or a subagent. Work without a process stays on the tool call that started it. When the Agent knows that a tool call's work continues after the call returns control to the model, it **SHOULD** keep that tool call `pending`, `in_progress`, or `paused` and list it, instead of giving it a final status. Some work has no such tool call. No tool call started it, such as a task that a hook started, or the Agent learned of the work only after its tool call reached a final status. The Agent **MAY** start a tool call of its own for such work, with a title that describes the work, and list it. It sends that tool call like any other, before the first list that names it, even while the session is `idle`. A final status is never reopened. The Agent starts a new tool call instead. **Background work is work the user can reason about.** It is something the user or the model started and that the user may want to stop or leave to finish. Internal housekeeping that the agent starts on its own, such as memory consolidation or an auto-started watcher, is not background work in this sense. The Agent **SHOULD NOT** list it, because a Client could only show it as unexplained activity or warn about it before close. If housekeeping needs to be visible, the Agent represents it as a tool call and lists it like any other work. ### Tool call statuses for background work Today `pending` means the tool call "hasn't started running yet because the input is either streaming or awaiting approval". This RFD generalizes it to "hasn't started running yet", with scheduling as another example reason. It also adds a `paused` status, for work that has started, is not running now, and will not continue until something resumes it: | Status | Meaning | Background examples | | - | - | - | | `pending` | Live, but not started yet | A scheduled wakeup waiting to fire; a cron job waiting for its next run | | `in_progress` | Actively running | A monitor watching a log or socket; a running workflow | | `paused` | Started, suspended until resumed | A paused workflow whose agents are stopped but whose state is kept | | final | `completed`, `failed`, or `cancelled`; no further changes | - | Clients **SHOULD** show `in_progress` as active, for example with a spinner, `pending` as waiting or scheduled, and `paused` as paused. `paused` is to a tool call what `idle` is to a session: the work still exists and can continue, but nothing is happening now. Status transitions: * Statuses never go back to `pending`. When a scheduled tool call fires, the work it triggers is new foreground work, not the tool call running: * A scheduled wakeup goes `pending` → `completed` when it fires. * A recurring cron job stays `pending` until the job is deleted or the session closes, then becomes `completed` or `cancelled`. * `in_progress` and `paused` may alternate any number of times. A paused tool call reaches a final status when it is cancelled, fails, or is discarded. * How work is paused and resumed is up to the Agent, for example a tool the model calls. This RFD does not add Client-initiated pause or resume. `paused` is a new `ToolCallStatus` variant. Clients that predate it see an unknown status through the existing `Other` fallback and can show it as unfinished. ### Cancellable tool calls `tool_call_update` gains an optional `capabilities` field with the same shape and patch rules as [subagent capabilities](../subagents.mdx): ```json theme={null} { "sessionUpdate": "tool_call_update", "toolCallId": "call_012", "title": "Watch deploy logs", "kind": "other", "status": "in_progress", "capabilities": { "cancel": {} } } ``` * `capabilities` is a nullable patch: omitted leaves it unchanged, `null` clears it, and an object replaces the whole previous value. * `cancel` is an optional, nullable capability object. Omitted or `null` means unsupported, and `{}` advertises support. It may carry `_meta`. A `pending` or `paused` tool call may advertise it too, for example to delete a scheduled job or discard a paused workflow. * An agent **SHOULD** clear or stop advertising `cancel` once the tool call reaches a final status. The Client cancels one tool call with a new `tool_call/cancel` request: ```json theme={null} { "jsonrpc": "2.0", "id": 7, "method": "tool_call/cancel", "params": { "sessionId": "sess_abc123", "toolCallId": "call_012" } } ``` * The Client **MUST NOT** send it unless the tool call currently advertises `capabilities.cancel`. * The Agent responds with an empty result once it has accepted the cancellation. The response does not mean the work has stopped. The Agent confirms that with a `tool_call_update` to a final status, normally `cancelled`, and may send `completed` or `failed` if the work finished first. * The Agent responds with `-32602` (Invalid params) if the tool call is unknown, already final, or not cancellable. * Cancelling a tool call does not change the foreground state by itself. The Agent decides what, if anything, to tell the model about it. This works for foreground tool calls too. A user can stop one long-running step without cancelling the rest of the agent's work. ### Cancellable terminals [Terminals](./terminal-output.mdx) are display-only today. This RFD adds one opt-in control: `terminal_update` gains an optional `capabilities` field with the same shape and patch rules as tool call capabilities. ```json theme={null} { "sessionUpdate": "terminal_update", "terminalId": "term_003", "command": "npm run dev", "cwd": "/workspace/project", "capabilities": { "cancel": {} } } ``` * `capabilities` and `cancel` follow the same rules as on tool calls. A terminal has no status, so the Agent **SHOULD** clear or stop advertising `cancel` once it reports `exitStatus`. The Client stops the process with a new `terminal/cancel` request: ```json theme={null} { "jsonrpc": "2.0", "id": 8, "method": "terminal/cancel", "params": { "sessionId": "sess_abc123", "terminalId": "term_003" } } ``` * The Client **MUST NOT** send it unless the terminal currently advertises `capabilities.cancel`. * The Agent responds with an empty result once it has accepted the cancellation. The response does not mean the process has stopped. The Agent confirms that with a `terminal_update` that sets `exitStatus`, for example with the signal used to stop it. * The Agent responds with `-32602` (Invalid params) if the terminal is unknown, has already exited, or is not cancellable. * Cancellation stops the process. It does not release the terminal: its output remains available for display and replay. * Cancelling a terminal does not change the foreground state or the status of any tool call that references it. If foreground work is waiting on the process, the Agent reports the tool call's outcome as it would for any other process exit. Input, resize, and other interactive control remain out of scope. ### The `background` list on state snapshots `running`, `requires_action`, and `idle` state updates gain an optional `background` field listing the work that is currently running independently of foreground work: ```json theme={null} { "sessionUpdate": "state_update", "state": "idle", "stopReason": "end_turn", "background": [ { "type": "terminal", "terminalId": "term_003" }, { "type": "tool_call", "toolCallId": "call_012" }, { "type": "tool_call", "toolCallId": "call_019" }, { "type": "subagent", "sessionId": "sess_child_4" } ] } ``` Rules for the field: * **It is a snapshot.** Each `state_update` is a complete snapshot, so `background` is too. A concrete list replaces the previous one, and `[]` means no background work is running. * **Omitted or `null` means the agent is not reporting background work.** It does not mean "nothing is running". An agent that reports background work **MUST** include `background` on every `state_update` for the session. If a later snapshot omits it anyway, or it is malformed, the Client treats background work as unknown until a list is reported again: it does not keep the previous list, consider the session quiet, or treat unfinished tool calls or running terminals as abandoned. * **The agent re-sends the state when the list changes.** When background work starts or ends, the Agent **SHOULD** send a repeated `state_update` with the current state and the updated list. A repeated snapshot is not a state transition ([State Transitions](/protocol/v2/prompt-lifecycle#state-transitions)), and a repeated `idle` without a new stop reason is not a new completion. * **Items are announced before they are listed and finalized before they are removed.** The Agent **MUST** send a `terminal_update` for a terminal, a `tool_call` or `tool_call_update` for a tool call, or a `subagent_update` for a child, before the first snapshot that lists it. When a terminal exits or a tool call ends, the Agent **MUST** send its `exitStatus` or final status before the snapshot that removes it from the list, so a Client never treats finished work as abandoned. * **Known follow-up work is reported with the removal.** When the end of background work starts new foreground work, for example a follow-up response to a finished background task, and the Agent knows this when it removes the item, the Agent **SHOULD** report `running` in the same snapshot that removes the item, or earlier. An Agent that only learns of the follow-up later, for example because the underlying agent decides after the work ends, reports `running` when that work starts. Clients cover that gap with the grace period below. * **Items reference existing entities.** `terminal` items reference a terminal by `terminalId` in this session. `tool_call` items reference a tool call by `toolCallId` in this session. `subagent` items reference a child session associated with this session through `subagent_update`. The list is extensible through the usual enum variant extension rules. * **Unknown items still count.** An item with an unknown `type` does not invalidate the list. It still means background work is running, even when the Client cannot show what it is, so a list of only unknown items is not empty. * **Paused and pending tool calls stay listed.** A `pending` or `paused` tool call is live background work: closing the session discards it, and the Client should not treat it as abandoned. * **Only background work is listed.** A terminal, tool call, or child session that foreground work is currently waiting on is foreground work and is not listed. Work moves into the list when it detaches, for example when a shell is backgrounded mid-turn and its terminal is listed. * **A background child is listed while it has anything running.** Subagent sessions are reusable, and `idle` does not end them. A detached child is listed while its state is not `idle`, or while its own `background` list is non-empty or not reported. An `idle` child with no background work of its own is not listed, even though it remains associated. * **Each piece of work is listed once.** Process-backed work is listed as its terminal. The Agent **MUST NOT** also list a tool call whose only live work is a listed terminal, so a Client counting items never shows one shell as two tasks. What the Client learns from the list: * **Whether the session is quiet.** The session has nothing running when the state is `idle` and `background` is `[]`. When `background` only contains `pending` or `paused` tool calls, the session is idle with work scheduled or suspended, and nothing is running right now. Because listed children stay listed while their own background work runs, this also covers descendants. Quiet describes the session at that snapshot, not a promise that it will stay quiet. An Agent may not know ahead of time that finished work will start a follow-up. A Client that frees resources when a session becomes quiet **SHOULD** wait a short grace period after the snapshot that empties the list. * **What closing will stop.** The Client can warn before `session/close`, for example "Closing will stop 2 background tasks". * **Which unfinished tool calls and terminals are still live.** A Client **MAY** treat a `pending`, `in_progress`, or `paused` tool call, or a terminal without `exitStatus`, that is not in the latest reported `background` list as abandoned once the session is `idle`. A tool call that references a listed terminal is live, even though it is not listed itself. A Client **MUST NOT** treat anything as abandoned when `background` is not reported. ### Cancellation, close, and resume **`session/cancel` cancels foreground work only.** Work in the latest `background` list is not part of the session's current work. This matches what Claude Code and Codex already do, and what the subagents RFD specifies for background children. * When the Client preemptively marks non-finished tool calls as `cancelled` after sending `session/cancel`, it **SHOULD** skip tool calls in the latest `background` list and tool calls that reference a listed terminal. * Pending permission requests for listed work stay open. Today the Client **MUST** answer every pending permission request in the session with `cancelled` on `session/cancel`. Only the Agent knows which work a request belongs to, so this RFD moves that job to the Agent, which is how [elicitations](/protocol/v2/elicitation#session-cancellation) already work. The Agent stops waiting for the permission requests of the cancelled foreground work and **SHOULD** cancel each of them with `$/cancel_request`. The Client **MAY** answer a request it knows belongs to the cancelled work with `cancelled` without waiting. * A permission request for listed work **SHOULD** reference the listed item in `subject`, by `toolCallId` or `terminalId`, and the Agent **MUST** list that work before sending the request. The Client uses this for display. It does not decide which requests to cancel. * Requests from a background subagent arrive under the child's session id, so `session/cancel` on the parent does not affect them. * When foreground work fails with the `error` stop reason, the unfinished tool calls the Agent gives a final status are those of the failed work. Listed background terminals and tool calls, and tool calls that reference a listed terminal, keep running. * Background work is stopped individually with `terminal/cancel`, `tool_call/cancel`, or by cancelling the subagent's session, or all at once with `session/close`. **`session/close` stops all background work.** "Any ongoing work" in [Closing Active Sessions](/protocol/v2/session-setup#closing-active-sessions) includes everything in the `background` list. * After a successful close, the Client **SHOULD** treat every listed tool call, and every tool call that references a listed terminal, that has not reported a final status as `cancelled`, and every listed terminal that has not reported `exitStatus` as exited with no known exit status. Before responding, the Agent **MUST** cancel every pending permission request scoped to the session with `$/cancel_request`. * The Agent **MAY** send final updates for listed work before responding, but doesn't have to. This matches the [subagents RFD](../subagents.mdx), where closing a parent cancels background children without requiring new notifications for them. * Work that is deliberately not owned by the session and survives its close, such as a durable cron job saved in the project, is out of scope and is not listed. **`session/fork` doesn't copy background work.** A forked session starts with no background work, even if the source session has some. Unfinished tool calls and running terminals copied into the fork's history are not live, and the fork's state snapshots report `background: []` until the fork starts its own background work. **`session/resume` restores the list.** The resume snapshot required by [Current-State Synchronization](/protocol/v2/session-setup#current-state-synchronization) carries `background` like any other snapshot. * Before that snapshot, the Agent **MUST** send a current `terminal_update` for each listed terminal, a current `tool_call_update` for each listed tool call, and a current `subagent_update` for each listed child, that the requested replay did not already deliver at its current state. When no replay was requested, this means sending all of them, so a Client with no history still knows what each item is. ## Shiny future > How will things will play out once this feature exists? A user starts a dev server, asks for a long test run in the background, and schedules a check-in for later. Claude Code also consolidates its memory in the background, but that housekeeping is not listed. When the agent finishes responding, the Client shows the session as idle with "1 running, 1 scheduled" next to it. The dev server's tool call shows its live terminal with a stop button. The background tests finish while the session is idle, and their terminal reports its exit status without the session leaving `idle`. When the user closes the session, the Client warns that the dev server and the scheduled check-in will be stopped. When they resume the session from another Client, the list of background work and the current state of each item come back with it. Adapters drop their private async-task extensions. Every Client sees the same background work through terminals, tool calls, and subagents it already renders. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? ### Schema * **`ToolCallStatus::Pending`:** update the doc comment to "hasn't started running yet", listing streaming input, pending approval, and scheduling as examples. * **`ToolCallStatus::Paused`:** add a variant for work that has started and is suspended until resumed. Older v2 Clients receive it through the existing `Other` fallback. * **`ToolCallUpdate.capabilities`:** add `MaybeUndefined`. `ToolCallCapabilities` has `cancel: Option` and `_meta`, mirroring `SubagentSessionCapabilities`. It is display-only metadata, so a malformed value falls back to unsupported (`DefaultOnError`). * **`tool_call/cancel`:** add `CancelToolCallRequest { session_id, tool_call_id, _meta }` and `CancelToolCallResponse { _meta }`, client-to-agent. The trait method is `cancel_tool_call` and the method names entry is `tool_call_cancel`. * **`TerminalUpdate.capabilities`:** add `MaybeUndefined`, with `cancel: Option` and `_meta`, handled like `ToolCallCapabilities`. * **`terminal/cancel`:** add `CancelTerminalRequest { session_id, terminal_id, _meta }` and `CancelTerminalResponse { _meta }`, client-to-agent. The trait method is `cancel_terminal` and the method names entry is `terminal_cancel`. This is separate from the v1 Client terminal methods, which v2 removes. * **`background` on state updates:** add `background: Option>` to `RunningStateUpdate`, `RequiresActionStateUpdate`, and `IdleStateUpdate`, and to `UnknownStateUpdate` under `unstable_subagents`. An Agent that can't tell what its foreground work is doing may still know what is running in the background. * `BackgroundWork` is an internally tagged enum on `type`: `Terminal { terminal_id, _meta }`, `ToolCall { tool_call_id, _meta }`, `Subagent { session_id, _meta }`, and an `Other` fallback that rejects known discriminators. * The Client acts on this list when it cleans up tool calls and terminals and warns before close. Unknown variants are handled by the `Other` fallback and do not invalidate the list. They still indicate background work, even when the Client cannot interpret their details. If an item with a recognized type fails validation, the entire `background` field is treated as unreported. That way a damaged list never makes running work look abandoned. * **Subagents:** `SubagentUpdate.state` mirrors the child's `StateUpdate`, so the child's own `background` list shows up there too. No separate change is needed. ### Documentation * `prompt-lifecycle.mdx`: in Foreground and Background Work, describe terminals, tool calls, and subagents as the representation of background work, and add the `background` list to Session States. In Cancellation, say that `session/cancel` does not stop listed work and that Clients skip it when they preemptively mark tool calls as cancelled. * `tool-calls.mdx`: the generalized `pending` definition, the `paused` status, tool calls that outlive foreground work, `capabilities`, and `tool_call/cancel`. In the terminal section, terminals that outlive their tool call, keeping their output current, terminal `capabilities`, and `terminal/cancel`. * `tool-calls.mdx`, in Requesting Permission: a request for background work references the listed item in `subject`. * [Terminal Output RFD](./terminal-output.mdx): note that terminals are display-only except for the opt-in cancellation added here. * `tool-calls.mdx` and `cancellation.mdx`: on `session/cancel`, the Agent cancels pending permission requests for the cancelled foreground work with `$/cancel_request`. Clients no longer answer every pending permission request in the session. * `session-setup.mdx`: what `session/close` does with listed work, how resume restores the list, and that `session/fork` doesn't copy it. * `migration.mdx`: mention the `background` list where it describes `idle` and background activity, and that `session/cancel` no longer cancels permission requests for background work. * [Subagents RFD](../subagents.mdx): the Client's optimistic cancellation of a cancelled session's unfinished tool calls skips tool calls in that session's `background` list. * Each change also goes into the matching `docs/protocol/v2/draft/` page. ### Adapters | Work | `claude-agent-acp` | `codex-acp` | | - | - | - | | Background shell | The Bash tool call completes when the command is backgrounded, as it does today. List its terminal until the SDK task ends, then send `exitStatus`. Claude Code reports no exit code, so the status is empty. The SDK only writes background output to the task's `output_file`, so the adapter reads new output from that file and sends it as chunks. Cancel calls `stopTask`. | The `commandExecution` tool call stays `in_progress` until Codex completes the item, as it does today. List its terminal while the process is in `thread/backgroundTerminals/list`. Codex already streams the process output as deltas. Cancel calls `/terminate`. | | Background subagent | Existing subagent association, listed while detached. | Existing subagent association, listed while detached. | | `Monitor`, `Workflow`, `mcp_task` | Keep the launching tool call `in_progress` until the task ends, and report `paused` while a workflow is paused. Cancel calls `stopTask`. | - | | `ScheduleWakeup`, non-durable `CronCreate` | Keep the tool call `pending` until it fires or is removed. | - | | Building `background` | From `background_tasks_changed`, which already sends the full live set, skipping entries marked `ambient`. | From `thread/backgroundTerminals/list` and collab agent state. Codex sends no exit events for background terminals, so this has to poll. | Both adapters can then drop their private `async_task_*` updates in favor of this, and should send final updates for listed work on `session/close`. Neither does today. claude-agent-acp also has to declare the SDK's `perTaskStopAffordance` whenever it reports `background`. Without it, the SDK kills background tasks when the turn is interrupted, which would break the rule that `session/cancel` leaves listed work running. Today the adapter only declares it for Clients that use the RFD form of subagents. ### Phases 1. Land the schema changes behind `unstable_protocol_v2` with draft docs. 2. Implement in `claude-agent-acp` and `codex-acp`, and in at least one Client. 3. Adjust from that experience before v2 is stabilized. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why not a single "background activity" boolean on the idle state? A boolean answers "is anything running?", but not what is running, whether it can be stopped, or which unfinished tool calls and terminals are still live. The list costs little more and answers all of those. A Client that only wants the boolean can check whether the list is empty. ### Why not a new background task entity? Claude's SDK and the adapters' private extension both model background work as tasks. In ACP almost every such task already has an entity: a terminal for a process, or the tool call that started it, with a title, kind, status, and content. A separate task entity would duplicate that status and output, and Clients would have to merge the two. Background subagents already have their own entity. Making terminals and tool calls cancellable and letting them outlive foreground work covers the same cases without another entity. ### Why list the terminal instead of the launching tool call? Agents disagree on the launching tool call's status. Claude Code's Bash tool returns as soon as a command is backgrounded, and later `TaskOutput` and `TaskStop` tool calls act on the same process by task id. claude-agent-acp therefore completes the Bash tool call and keeps its terminal open until the task ends. Codex keeps the command item open until the process exits and folds later stdin into the same item, so codex-acp keeps the tool call `in_progress`. Requiring either behavior would make one adapter report a status its agent doesn't have. The terminal is the same in both: it has its own identity and is live until it reports `exitStatus`. Listing it describes the running process without asking the tool call to stand in for it, and a tool call that references a listed terminal is never treated as abandoned. Tool calls are still listed for work without a process, such as a monitor, a workflow, or a scheduled wakeup. ### Why does `terminal/cancel` say "cancel" instead of "kill"? Every other per-item stop in ACP is a cancellation: `session/cancel` for a subagent, `tool_call/cancel`, and `capabilities.cancel`. Using the same word lets a Client drive one stop control from the same capability on every kind of item. "Cancel" also leaves the mechanism to the Agent, which may stop the process gracefully before forcing it, and the `exitStatus` reports what actually happened. It also avoids reusing v1's `terminal/kill`, which goes in the other direction, from Agent to Client, for a terminal the Client owns. ### Doesn't this make terminals more than a display surface? Only by one opt-in control. An Agent advertises `cancel` only for terminals it can stop, and Clients that ignore the capability see the same display-only terminals as before. Input, resize, and other interactive control remain out of scope. ### Why put the list on `state_update` instead of a separate update? The state snapshot is already the session-level summary that Clients track, is already re-sent on resume, and may already be repeated with updated information. Putting the list there means a single update tells the Client both whether the agent is busy and whether anything is still running, with no extra resume rules. ### Why can't Clients work out background work from tool call and terminal statuses alone? They could if every agent reliably finalized every tool call and terminal. In practice, stale `pending` and `in_progress` tool calls are common, and Clients clean them up when work ends. Once tool calls and terminals can legitimately outlive foreground work, Clients need the agent to say which unfinished ones are still live. ### Why are `terminal/cancel` and `tool_call/cancel` requests instead of notifications like `session/cancel`? The Client needs to know whether the cancellation was accepted. For example, the work may already be finished, or may not be cancellable. A request lets the Agent reject it with `-32602`. The terminal's `exitStatus` or the tool call's status update still confirms that the work actually stopped. ### Why doesn't `session/cancel` stop background work? Users background work so that it survives the current turn, and agents already behave this way: Claude Code background commands survive an interrupt, Codex `turn/interrupt` leaves background terminals running, and the subagents RFD lets background children continue. Stopping it is a separate, explicit action through `terminal/cancel`, `tool_call/cancel`, or `session/close`. ### What about work that outlives the session? A durable cron job saved in the project, or a remote agent that keeps running in the cloud, is not stopped by `session/close`, so it doesn't belong in a list Clients use to warn about what closing will stop. Reporting work that isn't owned by a session is out of scope here. ### Should an agent that only writes output to a file use a tool call instead of a terminal? No. The Claude Agent SDK writes background shell output to a file instead of streaming it, but the adapter can read that file as it grows and send the new bytes as `terminal_output_chunk`. The process is still a process: it has a command, a working directory, byte output, and an exit status, and it is the thing `terminal/cancel` stops. A tool call would lose the byte-faithful display and replay the terminal already provides. An agent that truly cannot read the output can still report the terminal with its command and exit status. ### Why is there no `ambient` flag on list items? The Claude Agent SDK marks some tasks `ambient` so hosts leave them out of activity indicators. Those are tasks Claude Code starts on its own, such as memory consolidation, the auto-mode scan, skill fork workers, and auto-started WebSocket watchers. Tasks the model requests, including `Monitor`, are not ambient. The list exists for work the user can reason about: something the user or the model started that the user may want to stop or leave to finish, and that closing the session would stop. Housekeeping fits none of that, so it is left out of the list instead of being listed with a flag that every Client must remember to check. If an agent wants housekeeping to be visible, it reports it as a tool call. ### Why add `paused` instead of using `pending` or `_meta`? `pending` means work that will start without anyone acting on it, and statuses never go back to it. Paused work has already run, keeps its state, and will not continue until something resumes it. Claude Code pauses workflows this way. A paused item also needs different treatment from a running one: a Client can show the session as not busy while still warning that closing will discard the paused work. Putting the status in `_meta` would hide that from every Client that does not know the agent's extension. This RFD does not add Client-initiated pause or resume. If agents expose those controls, they can be added later as `pause` and `resume` capabilities next to `cancel`. ### Do we need a "time of next run" for scheduled tool calls? Possibly. Agents can put it in `_meta` until there is demand for a standard `scheduledFor` field. ### Should the list say whether finishing the work will start a new agent turn? Claude Code, for example, starts a follow-up turn when a background task finishes. That would help a Client decide whether to keep the session open. It is left out because adapters can't reliably know it ahead of time. Instead, two ordering rules cover the race between the list emptying and a follow-up turn starting. When the Agent does know that new foreground work is starting, it reports `running` in the snapshot that removes the item, not after an empty `idle` snapshot. When it doesn't, Clients that release resources on a quiet session wait a short grace period first. ### What about work that has no tool call, or whose tool call already finished? Where it can, the Agent keeps the launching tool call open instead. When it knows at the tool result that the work goes on, it keeps that call `in_progress` and lists it, as `claude-agent-acp` does for `Monitor`, `Workflow`, and backgrounded MCP calls. The work then stays where it started in the transcript. When there is no such call, the Agent starts a tool call of its own. Claude Code has both cases: a hook can start a task without any tool call, and an MCP call can return, with its final status, before the task it started is reported. The launching tool call can't be listed then, because a final status can't change. Reopening a final tool call was considered and rejected. Clients rely on `completed`, `failed`, and `cancelled` being final when they clean up unfinished tool calls and stop showing progress. The call did finish: its result went back to the model, and the task it started has a lifetime of its own. This is also why a backgrounded process is listed as its terminal. Reopening would also not cover work that no tool call started. Subagents are different. A child session's `idle` was never final, and it corresponds to a `paused` tool call, not a `completed` one. If Clients want to show which tool call started an agent-started tool call, a reference to it can be added later. Until then, Agents can put it in `_meta`. A new item type with its own title and `cancel` would duplicate what a tool call already has, and Clients would need a second way to show and stop work. An agent-started tool call reuses both, and `tool_call/cancel` works on it like on any other tool call. The cost is that the tool call appears in the session's history where the Agent started it, not in the turn that the work came from. Clients already show tool call updates that arrive while the session is `idle`, from background tool calls. An item with an unknown `type`, such as a vendor-specific task item, still counts as background work, but the Client can neither name nor cancel it. An agent-started tool call is the better choice. ### Is there a v1 form? Not in this RFD. The `background` list belongs on the session-level `state_update`, which only v2 defines. Tool call `capabilities` and `tool_call/cancel` are additive and could be proposed for v1 separately. Terminal cancellation has no v1 equivalent, because v1 terminals are owned by the Client. Until then, v1 Clients rely on adapter-specific extensions. ## Revision history * 2026-11-09: An Agent that knows a tool call's work continues in the background keeps that tool call open and lists it. Background work without a tool call to report it on, or whose tool call already has a final status, is reported on a tool call the Agent starts itself. Final statuses stay final. This replaces vendor-specific list items such as the earlier `_claude/task` in `claude-agent-acp`. The tool call and prompt lifecycle pages say that an Agent may report tool calls the model did not request, and that work continuing after a final status gets a new tool call. * 2026-11-02: The rule that reports follow-up work with the removal applies only when the Agent knows of the follow-up at that point. An Agent that learns of it later, as `claude-agent-acp` does when Claude Code starts a follow-up turn after a background task ends, may send `idle` with the updated list and then `running`, and Clients rely on the grace period. * 2026-11-02: On `session/cancel`, the Agent cancels the permission requests of the cancelled foreground work with `$/cancel_request` instead of the Client choosing them by `subject`. `session/close` cancels every pending permission request the same way. * 2026-10-30: Phase 1 landed: the schema changes are in the v2 schema, with the item types named `BackgroundTerminal`, `BackgroundToolCall`, `BackgroundSubagent`, and `OtherBackgroundWork` and the cancel capability types pluralized to `ToolCallCancelCapabilities` and `TerminalCancelCapabilities` to match the other capability types, and the protocol docs describe the `background` list, `paused`, and both cancel methods. * 2026-10-27: Added a `paused` tool call status. Defined background work as work the user can reason about, so agent-internal housekeeping is not listed. Unknown item types still count as background work. Agents keep listed terminals' output current. Permission requests for background work reference the listed item, and `session/cancel` answers every other request. Noted that claude-agent-acp must declare `perTaskStopAffordance`. * 2026-10-26: Terminals are background work in their own right. A backgrounded process is listed as its terminal, whether its launching tool call completes or stays `in_progress`, and terminals can advertise `capabilities.cancel` and be stopped with `terminal/cancel`. Added ordering rules: items are announced before they are listed, final statuses come before removal, and follow-up work reports `running` with the removal. Defined when background subagents are listed, how Clients handle a list that stops being reported, and a grace period before releasing quiet sessions. Added a v1 FAQ. * 2026-10-21: Initial draft. # v2 Client Filesystem and Terminal Execution Surface Source: https://agentclientprotocol.com/rfds/v2/client-filesystem-terminal-capabilities Author(s): [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? ACP v2 will remove the standard Client filesystem and terminal execution surface. Specifically, v2 removes `clientCapabilities.fs`, the top-level `clientCapabilities.terminal` field, the Client filesystem methods, the Client terminal execution methods, and the inherited terminal tool-call content that refers to a Client-created terminal. This surface was intended to let Agents ask Clients to read or write files and run commands in a Client-managed terminal. In practice, it has not been widely adopted by both Clients and Agents, and many Agents are moving toward their own sandboxing and execution configuration instead. ## Status quo > How do things work today and what problems does this cause? Why would we change things? In v1, Clients can advertise filesystem access with: ```json theme={null} { "clientCapabilities": { "fs": { "readTextFile": true, "writeTextFile": true }, "terminal": true } } ``` Agents then use those fields to decide whether `fs/read_text_file`, `fs/write_text_file`, and `terminal/*` methods are available. Agents can also embed terminal output in tool calls using `ToolCallContent` with `type: "terminal"`. However, this hasn't been widely adopted. Both because not many clients outside of IDEs could even offer these, and even then, IDE support has been mixed. Also, this requires the Agent tools to handle both methods, and in practice, most stuck to their standard implementations. ## What we propose to do about it > What are you proposing to improve the situation? Remove the following standard v2 Client capability fields: * `clientCapabilities.fs` * `clientCapabilities.terminal` Remove the following standard v2 Client methods: * `fs/read_text_file` * `fs/write_text_file` * `terminal/create` * `terminal/output` * `terminal/release` * `terminal/wait_for_exit` * `terminal/kill` Remove the v1 Client-owned terminal tool-call content semantics as well. Without standard Client terminal methods, that content type no longer has a standard producer or lifetime model. The separate [Terminal Output](./terminal-output.mdx) RFD defines a new Agent-owned, display-only terminal model instead. As this was always opt-in anyway, it should require minimal changes on the agent side, as they just no longer have to check these capabilities. This does not remove `capabilities.auth.terminal`. That field belongs to the authentication methods proposal and only indicates whether a Client can run an Agent's terminal authentication flow for the user. ## Shiny future > How will things play out once this feature exists? ACP v2 has less Client-side surface for behavior that is not seeing broad interoperable use. If clients want to offer specialized tooling in these areas, they can already expose a special MCP server to the agent to provide access. We will look at exploring configuration for Agent sandboxing and filesystem access in the future. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? * Remove `fs` and top-level `terminal` from the v2 `ClientCapabilities` schema. * Remove the v2 `FileSystemCapabilities` schema type because it is no longer referenced. * Remove the v2 filesystem and terminal request/response structs, method-name constants, RPC enum variants, and generated method metadata. * Replace the inherited Client-owned terminal content with the Agent-owned display reference defined by the Terminal Output RFD. * Keep v1 unchanged. * An adapter normalizing a v1 initialize request for v2 must reject advertised `fs` support or top-level `terminal: true` instead of silently dropping them. * An adapter normalizing a v2 initialize request for v1 maps filesystem and terminal execution support to unsupported. * Cross-version adapters must reject removed filesystem and terminal method variants or terminal tool-call content unless they implement the missing behavior explicitly. Although v1 and v2 terminal references have the same fields, their ownership and lifetime semantics are incompatible. * Update v2 initialization, overview, tool-call, and schema docs so Agents do not check these v1 capability fields or call these v1 methods for v2 connections. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Does this remove terminal authentication? No. Terminal authentication is represented by v2 `capabilities.auth.terminal`, not by the v1 top-level `clientCapabilities.terminal` execution capability. This RFD only removes the top-level terminal execution capability. ### Does this remove terminal display? No. It removes Client execution and control. The [Terminal Output](./terminal-output.mdx) RFD adds a separate Agent-owned, display-only stream for command output. ## Revision history * 2026-07-14: Linked the Agent-owned Terminal Output replacement and clarified the incompatible ownership models. * 2026-06-02: Initial draft # v2 Diff File States Source: https://agentclientprotocol.com/rfds/v2/diff-file-states Author(s): [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? ACP v2 should replace the v1 `Diff` shape's ambiguous `oldText` / `newText` fields with a structured diff content shape that can represent text patches, non-text file changes, and file-level operations such as add, delete, modify, move, and copy. Every diff should carry structured file-change metadata. It can also carry renderable Git `--patch` text in an optional top-level `patch` field. ## Status quo > How do things work today and what problems does this cause? Why would we change things? ACP v1 represents a diff as a path plus old and new text: ```json theme={null} { "type": "diff", "path": "/home/user/project/src/config.json", "oldText": "{\n \"debug\": false\n}", "newText": "{\n \"debug\": true\n}" } ``` That shape has several problems: * `newText: ""` cannot distinguish a deleted file from an empty file without an extra flag. * Moves and copies have no direct representation. * Binary files, symlinks, and directory entries do not have useful `oldText` and `newText` values. * Clients have to reconstruct or parse a diff to render changes. * The protocol cannot express whether a file path was added, deleted, modified, moved, or copied. An earlier v1 proposal ([#441](https://github.com/agentclientprotocol/agent-client-protocol/pull/441)) would have added a `deleted` flag as a stop-gap for deletes, but v2 can use a cleaner breaking shape instead of adding more flags to the v1 structure. ## What we propose to do about it > What are you proposing to improve the situation? ACP v2 should make `ToolCallContent` diffs carry a required `changes` array and an optional `patch` object. Use `patch` for changes that have useful renderable patch text: ```json theme={null} { "type": "diff", "changes": [ { "operation": "modify", "path": "/home/user/project/src/config.json", "fileType": "text", "mimeType": "application/json" } ], "patch": { "format": "git_patch", "text": "diff --git /home/user/project/src/config.json /home/user/project/src/config.json\n--- /home/user/project/src/config.json\n+++ /home/user/project/src/config.json\n@@ -1,3 +1,3 @@\n {\n- \"debug\": false\n+ \"debug\": true\n }\n" } } ``` `changes` is authoritative for affected paths and operations. `patch`, when present, provides renderable text for some or all of those changes and MUST be consistent with `changes`. The patch format should be `git_patch`: one or more `diff --git` sections in Git's [`--patch` (`-p`) text format](https://git-scm.com/docs/diff-generate-patch). Unlike Git, which writes paths relative to the repository root, every path MUST be absolute, including in `rename from`, `rename to`, `copy from`, and `copy to` lines, and MUST NOT have a prefix such as Git's default `a/` and `b/`. Otherwise paths follow Git: `/dev/null` names the missing side of an added or deleted file in the `---` and `+++` lines, and paths with unusual characters are quoted as Git quotes them. Surrounding commit metadata and email envelopes MUST NOT be included. Agents SHOULD provide `patch` whenever feasible. Clients MUST handle diffs where `patch` is omitted or `null`. Omit `patch` when patch text is not useful: ```json theme={null} { "type": "diff", "changes": [ { "operation": "modify", "path": "/home/user/project/assets/logo.png", "fileType": "binary", "mimeType": "image/png" } ] } ``` Omitted and `null` `patch` values are equivalent and mean no renderable patch text was provided. The initial operation set should be: * `add` * `delete` * `modify` * `move` * `copy` `add`, `delete`, and `modify` use `path`. `move` and `copy` use `oldPath` and `path`. All paths in protocol payloads are absolute. The optional `fileType` field should describe the file entry when known: * `text` * `binary` * `directory` * `symlink` The optional `mimeType` field should carry a MIME type when known. Omitted and `null` values for `fileType` and `mimeType` mean the value is unknown. ## Shiny future > How will things play out once this feature exists? Clients can render text diffs without needing to synthesize patch text, and can show file-level summaries without parsing patch syntax. Agents can report binary updates, symlink changes, deletes, moves, and copies without forcing those cases through text-only fields. The v2 diff surface is also easier for SDKs to model because operations are explicit enum variants rather than inferred states from optional text fields. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? 1. Replace the v2 `Diff` struct's old text fields with a required `changes` array. 2. Add an optional `patch` field with `format` and `text`. 3. Use `git_patch` as the ACP-defined patch format, and document that Agents SHOULD provide it whenever feasible. 4. Add structured `DiffChange` operation variants for add, delete, modify, move, and copy, with path fields owned by each operation variant. 5. Add optional `fileType` and `mimeType` fields for non-text and unknown file content. 6. Preserve custom or future operations where the receiver can safely store, replay, forward, or display a generic summary. 7. Update generated schema and v2 protocol docs. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### What does `git_patch` mean? Text changes use unified hunks; Git headers can also describe file operations. This is more specific than a plain unified diff and contains only patch sections, not surrounding commit metadata or email envelopes. The format is broadly supported and can describe multiple files. ACP can add other patch formats later. ### How does a `git_patch` write paths? ACP paths are absolute, so this is the one place `git_patch` departs from what Git writes: Git's paths are relative to the repository root. Without the `a/` and `b/` prefixes, every path in the patch, including `rename from`, `rename to`, `copy from`, and `copy to` lines, is the absolute path itself, so receivers can match it to `changes` without guessing whether a leading component is a prefix. Everything else stays as Git writes it, including `/dev/null` for the missing side of an add or delete and quoting of unusual paths, to keep the text close to what Git patch parsers expect. Agents using Git can get most of the way by setting `$ROOT` to the repository root and running `git diff --src-prefix="$ROOT/" --dst-prefix="$ROOT/"`. Git never prefixes `rename from`, `rename to`, `copy from`, or `copy to` paths, so those still need the repository root prepended. The result is not meant for `git apply`, which rejects absolute paths. ### Why is `patch` top-level instead of attached to individual changes? Git `--patch` text can describe several files and several operation kinds at once. Keeping `patch` top-level makes it renderable context for the whole diff content item, while `changes` remains the structured source for paths and operations. ### Should patch text be restricted to some operation variants? No. Git `--patch` text can represent adds, deletes, modifies, moves/renames, copies, and some binary changes. If an Agent has useful patch text for a set of changes, it can include `patch`; otherwise it can omit it. ### Why is `patch` optional if Agents SHOULD provide it? Some changes have no useful patch text, especially same-path binary updates and symlink target changes. Patch generation can also fail or be unavailable in a given Agent implementation. Keeping `patch` optional lets clients rely on structured `changes`, while the SHOULD encourages better rendering when patch text is practical. ### What kind of `modify` does not have a patch? Mostly in-place non-text updates, such as a binary file update at the same path or a symlink target change. Text modifications should normally use `patch` so clients have renderable text. ### Why include both patch text and structured changes? Patch text gives clients an immediate baseline rendering path. Structured changes give clients operation and path metadata without requiring patch parsing, which matters for summaries, file trees, permissions, and non-text indicators. ## Revision history * 2026-10-12: Specify that every `git_patch` path, including rename and copy headers, is absolute with no `a/` or `b/` prefix, and otherwise follows Git, including `/dev/null` and path quoting * 2026-07-20: Define `git_patch` as Git `--patch` text and rename `patch.diff` to `patch.text` * 2026-07-02: Initial draft # v2 Enum Variant Extension Source: https://agentclientprotocol.com/rfds/v2/enum-variant-extension Author(s): [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? ACP v2 should make enum-like protocol values forward-compatible when a receiver has a safe fallback. Values beginning with `_` are reserved for implementation-specific extensions. Values that do not begin with `_` are reserved for ACP itself, including future ACP variants. This gives extensions a dedicated namespace without making older clients and agents reject additive informational protocol changes. ## Status quo > How do things work today and what problems does this cause? Why would we change things? ACP already uses `_` as the extension namespace for custom methods and session config categories. Session config categories also preserve unknown category strings, so older clients can handle newer categories gracefully. Most other string enum protocol fields are closed in the generated schema. Examples include roles, status values, stop reasons, and permission option kinds. SDKs and validators generated from those schemas can reject a message only because a newer ACP version added a variant the older implementation does not understand. That strictness is useful when the value controls whether a request can be fulfilled correctly. It is unnecessarily disruptive for notifications, display metadata, and other informational fields. A client can often ignore, preserve, forward, or display a generic fallback for an unknown session update, tool status, plan entry status, or UI hint. Without a shared namespace rule, extension authors also have no safe place to experiment with custom values without risking collisions with future ACP variants. ## What we propose to do about it > What are you proposing to improve the situation? ACP v2 should define one enum extension rule for ACP-owned values when the receiving side has an acceptable fallback: * Values beginning with `_` are reserved for implementation-specific extensions. * Values that do not begin with `_` are reserved for ACP. * Future ACP versions may add non-underscore values without treating that as an extension collision. * Extensions MUST NOT define custom non-underscore values. * Implementations MUST NOT treat an unknown non-underscore value as a custom extension. * Implementations SHOULD preserve unknown values when storing, replaying, proxying, or forwarding protocol data. * Implementations that cannot act on an unknown value SHOULD degrade gracefully according to the field's semantics. This applies to ACP-owned enum-like values where fallback behavior is acceptable. It does not apply to JSON-RPC fixed constants such as `"2.0"`, numeric code spaces such as JSON-RPC error codes, user-supplied elicitation option values such as `enum` or `oneOf` constants, or discriminators that are core to fulfilling a request. Elicitation schema annotations such as string `format` values can still be open because an implementation can safely treat an unknown format as an annotation. Tagged unions use string discriminator fields too. When ACP v2 opens one of these unions, it must preserve both the discriminator and the unknown object payload. The same `_` namespace rule applies. Raw fallbacks are appropriate for notification-style and display-data payloads that can be stored, replayed, proxied, forwarded, ignored, or rendered with a generic UI. Tagged unions that are core to request handling, such as transport selectors, can stay closed or be opened. If open, a receiver that cannot fulfill a request without understanding the variant rejects it with `-32602`, and an unknown variant in a response, such as an elicitation action, falls back to the most conservative known behavior. Permission outcomes can be opened when unknown outcomes are handled conservatively and never treated as approval. ## Shiny future > How will things play out once this feature exists? Adding a new ACP variant for an informational or notification-like field will not automatically make older v2 validators reject otherwise well-formed messages. Older implementations can preserve and forward data they do not understand, or fall back to generic display behavior when that is enough. Extensions get a clear rule: use `_`-prefixed values such as `_com.example/feature` for custom variants, and leave every non-underscore spelling available for ACP. Capabilities are still available when a sender needs to know whether the receiver can act on a value. This proposal makes the wire format tolerant first; capabilities can still gate behavior when behavior matters. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? The v2 Rust schema types should encode this convention directly where fallback behavior is safe: * String enum definitions list known values explicitly and include a fallback variant that captures the unknown string. * Notification-style and display-data tagged unions can add a raw fallback variant that captures the discriminator string and unknown payload object. * Raw tagged-union fallbacks must not hide malformed known variants. If a known discriminator is present but its payload is invalid, deserialization must still fail. * Untagged shape unions can add raw fallbacks only when there is a reliable discriminator field to distinguish a future/custom variant from a malformed known shape. * Core control-flow discriminators may remain closed when there is no safe fallback behavior. * SDKs should expose fallback variants that carry unknown values rather than silently discarding them. * Conversion from v2 to v1 should fail when an unknown v2 value cannot be represented in v1 without data loss. * v1 schemas remain unchanged. The fallback variant's Rust doc comment should document the `_` extension rule and the future-ACP reservation rule, so generated docs and schemas follow the type source of truth. This proposal does not require identical runtime behavior for every unknown value. Some fields can be ignored, some can be displayed generically, some can be preserved only for replay or proxying, and some should still fail because the receiver cannot safely continue. The cross-cutting rule is that `_` means extension-owned, non-underscore means ACP-owned, and parsers and validators should not fail solely because a value is unknown when that field has a defined fallback path. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why not reserve all unknown values for custom extensions? That would block ACP from adding future standard variants without risking collisions with implementations that already claimed those names. Reserving non-underscore values for ACP gives the protocol room to grow while still giving extensions a predictable namespace. ### Does this make every enum extensible? No. This proposal opens values only when the receiver has a safe fallback. If understanding the variant is required for correctness, the enum should remain closed or be gated by capability negotiation. ### Why not use capabilities for every new variant? Capabilities are still useful when a sender needs to know whether the receiver can act on a variant. They do not solve parsing, validation, storage, replay, or proxying problems. The enum extension rule makes the wire format tolerant first; capabilities can still gate behavior when needed. ### Does this mean implementations must understand every unknown variant? No. Implementations should preserve unknown values when practical and degrade gracefully according to the field's semantics. This proposal is about forward compatibility and namespace ownership, not requiring old software to implement future behavior. ## Revision history 2026-05-27: Initial draft # v2 Message Updates and Chunks Source: https://agentclientprotocol.com/rfds/v2/message-updates Author(s): [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? ACP v2 should support both whole-message updates and streamed message chunks for user messages, agent messages, and agent thoughts. Whole-message updates are upserts keyed by message type and `messageId`, while chunks append content to the message with the matching `messageId`. ## Status quo > How do things work today and what problems does this cause? Why would we change things? ACP v1 primarily reports user, agent, and thought messages as chunks: ```json theme={null} { "sessionUpdate": "agent_message_chunk", "messageId": "msg_agent_c42b9", "content": { "type": "text", "text": "Analyzing..." } } ``` Chunks are a natural fit for streaming model output, but they are awkward for session replay, accepted user-message acknowledgments, and cases where the Agent already has the whole message available. Also, there is no way for an agent to *redact* content from a message if needed due to guardrail APIs. The v2 prompt lifecycle also needs a clear way for Agents to acknowledge or replay accepted user messages. The [Message ID RFD](../message-id.mdx) keeps message IDs agent-owned, so the Agent needs a session update that can provide both the accepted user-message content and its `messageId`. ## What we propose to do about it > What are you proposing to improve the situation? ACP v2 should define whole-message session updates: * `user_message` * `agent_message` * `agent_thought` Each whole-message update is an upsert keyed by its message type and `messageId`. IDs are unique per type, so a user message, an agent message, and an agent thought may share an ID without affecting each other. A field that refers to a message must also identify its type. For each update: * `messageId` is required. * `content` and `_meta` are patch fields. * An omitted patch field leaves the previous value unchanged. * `null` explicitly clears or unsets the field. * Any concrete value replaces the previous value. * `content` is replaced as a whole array, not appended. * `[]` and `null` both clear `content`. * A `_meta` object patches the stored metadata by top-level key instead of replacing it, as defined by [Metadata Patches](./meta-patches.mdx). * For a new `messageId`, omitted `content` starts empty. The matching chunk updates remain: * `user_message_chunk` * `agent_message_chunk` * `agent_thought_chunk` Chunks append their single `content` item to the current content of the message with the matching `messageId`. The [Prompt Lifecycle RFD](./prompt.mdx#correlate-prompts-with-accepted-user-messages) explores acknowledging user-message insertion by returning its agent-generated `messageId` in the prompt response. Live updates and chunks for that user message would use the same ID, as would replay if the agent retains the message. Retaining the message is optional; live-only messages, including locally handled commands, need not appear in later history. The response confirms insertion and establishes the submitting client's association with the message; the corresponding updates report its content and placement. They describe the same insertion, but clients must tolerate updates arriving before or after the response. No additional correlation field or metadata-only update is required for live streaming. When replay reconstructs a message from its beginning using chunks, the Agent must first send the corresponding `user_message`, `agent_message`, or `agent_thought` update with the same ID and `content: []` to clear retained content before appending the replayed chunks. This rule applies to all message types. A metadata-only update would leave retained content unchanged and duplicate it during replay. A full-content message update can instead replace the retained content directly. ### Interaction between updates and chunks Clients apply message updates and chunks in the order they are received for each message, identified by its type and `messageId`. If a message update includes `content`, that content array replaces all content currently stored for the message, including content accumulated from earlier chunks: ```json theme={null} [ { "sessionUpdate": "agent_message_chunk", "messageId": "m1", "content": { "type": "text", "text": "A" } }, { "sessionUpdate": "agent_message_chunk", "messageId": "m1", "content": { "type": "text", "text": "B" } }, { "sessionUpdate": "agent_message", "messageId": "m1", "content": [{ "type": "text", "text": "C" }] } ] ``` After this sequence, the message content is `[C]`. If chunks arrive after a message update, they append to the update's current content: ```json theme={null} [ { "sessionUpdate": "agent_message", "messageId": "m1", "content": [{ "type": "text", "text": "A" }] }, { "sessionUpdate": "agent_message_chunk", "messageId": "m1", "content": { "type": "text", "text": "B" } } ] ``` After this sequence, the message content is `[A, B]`. If a message update omits `content`, it does not change the current content. This lets Agents update `_meta` or future optional fields without resending the whole content array: ```json theme={null} { "sessionUpdate": "agent_message", "messageId": "m1", "_meta": { "source": "replay" } } ``` ## Shiny future > How will things play out once this feature exists? Agents can choose the reporting style that matches the data they have: * use whole-message updates for replay, accepted user messages, and already-complete model output; * use chunks for streaming output; * combine both when an Agent needs to seed content and then stream more, or correct/replace content after streaming. The upsert shape also leaves room for future message-level fields, such as annotations or provenance, without forcing Agents to resend content for metadata-only updates. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? 1. Add the `user_message`, `agent_message`, and `agent_thought` session update variants to v2. 2. Require `messageId` on whole-message updates and chunks. 3. Represent `content` and `_meta` as three-state patch fields so omitted, `null`, and concrete values can be distinguished. 4. Document ordering semantics between whole-message updates and chunks in the protocol docs. 5. A stateful adapter may convert a content-bearing whole-message update to v1 by fanning out one v1 chunk per content block only when it knows the v1 side has not already received content for that `messageId`; v1 has no way to replace earlier chunks. Patch-only updates, `content: null`, `content: []`, and `_meta: null` cannot be represented by v1 chunks and must not be silently dropped. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why are message updates upserts instead of required full snapshots? Upserts let Agents update `_meta` or future optional message fields without resending the whole content array. ### Why does `content` replace instead of append? Appending is already represented by chunks. A whole-message update needs to be able to replay, correct, or replace the current content for a message. Making `content` a replacement array gives each update type a distinct behavior: message updates replace fields, chunks append content. ### What happens when a message update arrives before any chunks? The Client creates or updates the message for that `messageId`. Later chunks with the same `messageId` append to the current content. ### What happens when chunks arrive before a message update? The Client appends those chunks to the message for that `messageId`. A later message update with `content` replaces the accumulated content. ## Revision history * 2026-10-29: Omitted `content` on a new message starts empty, rather than using Client defaults. * 2026-10-29: Messages are keyed by type and `messageId`, since IDs are unique per message type. * 2026-10-13: A top-level `_meta` object now patches stored metadata by key, per [Metadata Patches](./meta-patches.mdx). * 2026-06-09: Initial draft. # v2 Metadata Patches Source: https://agentclientprotocol.com/rfds/v2/meta-patches Author(s): [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? ACP v2 upsert updates should apply their top-level `_meta` as a patch one level down. Omitted `_meta` leaves the stored metadata unchanged and `null` clears it, as today. A `_meta` object patches the stored metadata by top-level key instead of replacing it: an omitted key is unchanged, a key set to `null` is removed, and any other value replaces that key whole. ## Status quo > How do things work today and what problems does this cause? Why would we change things? v2 upserts such as [`tool_call_update`](./tool-call-updates.mdx), [`terminal_update`](./terminal-output.mdx), and [message updates](./message-updates.mdx) treat `_meta` like every other patch field: omission leaves it unchanged, `null` clears it, and a concrete object replaces the whole stored object. Unlike the other patch fields, `_meta` has more than one writer. Its keys are usually namespaced by the extension that owns them, such as `com.example/debugMode`, and some are shared conventions such as W3C trace context. Replacing the whole object makes every writer responsible for every other writer's keys: * An Agent that sends different keys on different reports loses the earlier keys at each later report. v1 gave no rule for keeping a `tool_call_update`'s `_meta`, so v1 Agents that do this lose data after migrating, and the v2 migration guide had to tell them to resend every key on every report. * An intermediary, such as a proxy, that adds its own key to an update the Agent sent without `_meta` turns "unchanged" into "replace" and erases the Agent's stored metadata. To avoid that, it must track the stored metadata of every entity it forwards and resend the merged object. * Changing one key requires resending all of the others. ## What we propose to do about it > What are you proposing to improve the situation? For the top-level `_meta` of v2 upsert updates: * Omitted `_meta` leaves the stored metadata unchanged. * `_meta: null` clears all stored metadata. * A `_meta` object patches the stored metadata by top-level key: * Keys the object omits keep their stored values, so `_meta: {}` changes nothing. * A key set to `null` is removed. Removing a key that is not stored does nothing. * Any other value replaces that key's stored value whole. Clients **MUST NOT** merge nested objects, and a `null` nested inside the value is ordinary data. * A key set to `null` never holds stored data, including on the first update for an entity. * Stored metadata with no keys is the same as no metadata. This is the three-state rule the update already applies to its own fields, applied one level down. It matches [JSON Merge Patch (RFC 7386)](https://www.rfc-editor.org/rfc/rfc7386) applied only to the top level of `_meta`. A JSON Merge Patch library merges nested objects recursively, so implementations cannot use one unmodified. The rule applies to the top-level `_meta` of: * `tool_call_update`, including the `toolCall` of a `session/request_permission` `tool_call` subject * `terminal_update` * `user_message`, `agent_message`, and `agent_thought` * `session_info_update` * `compaction_update` * the draft-only `subagent_update` and `session_message` It does not apply to `_meta` anywhere else: requests, responses, notification params, chunks, content items, terminal output snapshots, exit status, command permission subjects, and other nested objects keep their current meaning, where the metadata describes only the object that carries it. Data about a single notification rather than the entity belongs in the `session/update` notification's `params._meta`. For example, if a tool call's stored `_meta` is: ```json theme={null} { "com.example/progress": 0.5, "org.example/review": { "state": "pending" } } ``` and a later update sends: ```json theme={null} { "sessionUpdate": "tool_call_update", "toolCallId": "call_001", "_meta": { "com.example/progress": null, "org.example/review": { "reviewer": "sam" }, "net.example/route": "edge" } } ``` the stored `_meta` becomes: ```json theme={null} { "org.example/review": { "reviewer": "sam" }, "net.example/route": "edge" } ``` ### Replay and resynchronization An object is no longer a complete snapshot of an entity's metadata, so replay needs explicit rules: * Replay applies metadata patches exactly as live delivery does, in receive order for each entity, and never resets metadata implicitly. An update that replaces another field, such as a message update with `content`, leaves the `_meta` keys it does not mention. * Replaying the original updates in order reproduces the stored metadata, provided their removals are kept. * To send an entity's current metadata when the Client may already hold some, the Agent removes stale keys. It either sets each one to `null` alongside the current keys, or sends `_meta: null` and then the current object in a later update. The second form is not atomic, so the Client may briefly hold no metadata. * When the current metadata is empty, the Agent sends `_meta: null`, not `{}`. * When the Client is known to hold no metadata for the entity, the current object alone is enough. * Intermediaries that combine updates **MUST** keep removals and clears. Replacing a clear followed by an object with just that object is wrong when earlier metadata may exist. ## Shiny future > How will things play out once this feature exists? Each extension owns its top-level keys. It can set, replace, or remove them without knowing which other keys exist, and each update to its own key replaces that key's value in a single step. Proxies and other intermediaries can annotate forwarded updates without tracking entity state. Agents can change one key without resending the rest, and sending different keys on different reports no longer loses data. The cost is that replay and resynchronization must remove stale keys explicitly, and replacing all metadata in one update requires knowing which keys to remove. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? 1. Keep the schema shape. These upserts already represent `_meta` as a three-state field, and a `_meta` object can already carry `null` values. 2. Define the rule, including replay, once in the v2 Extensibility page under [Metadata Patches](/protocol/v2/draft/extensibility#metadata-patches), and reference it from the tool call, terminal, message, session info, compaction, and session replay docs, the schema field descriptions, and the migration guide. 3. Add `apply_meta_update` to the Rust v2 schema module and use it in `ToolCallUpdate::apply_update` and `TerminalUpdate::apply_update`. 4. Leave v1 unchanged, including the v1 `session_message`, `subagent_update`, and `compaction_update` updates that replace `_meta` as a whole. ### Conformance cases SDKs that store entity state should cover at least these cases: | Stored `_meta` | Incoming `_meta` | Result | | - | - | - | | `{"a": 1, "b": 2}` | omitted | `{"a": 1, "b": 2}` | | `{"a": 1, "b": 2}` | `null` | no metadata | | `{"a": 1, "b": 2}` | `{}` | `{"a": 1, "b": 2}` | | `{"a": 1, "b": 2}` | `{"a": 3}` | `{"a": 3, "b": 2}` | | `{"a": 1, "b": 2}` | `{"a": null}` | `{"b": 2}` | | no metadata | `{"a": null}` | no metadata | | `{"a": {"x": 1, "y": 2}}` | `{"a": {"x": 3}}` | `{"a": {"x": 3}}` | | `{"a": [1, 2]}` | `{"a": [3]}` | `{"a": [3]}` | | no metadata | `{"a": {"x": null}}` | `{"a": {"x": null}}` | They should also cover unknown keys, a clear followed by an object, and replay over stale metadata. ### Compatibility When converting v1 to v2, a v1 `_meta` object can be forwarded as is when the v1 source defines no replacement rule, as with `tool_call_update` and `session_info_update`; its keys now merge with earlier ones, and a key set to `null` becomes a removal, the closest v2 equivalent of storing `null`. Where v1 replaces `_meta` as a whole, an adapter that must preserve that behavior needs the previously forwarded keys so it can send `null` for each key that disappeared. Alternatively, it can send `_meta: null` before the new object. When converting v2 to v1, a v1 receiver may replace the whole stored object and may store `null` values literally. A stateful adapter can keep the merged metadata for each entity and send the complete merged object. A stateless adapter cannot represent key-level patches and must document that it is lossy for `_meta`. Within v2, an implementation must not copy metadata that is not a patch, such as a `session/list` entry's `_meta`, into a patch unchanged: its `null` key values would become removals. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why not merge nested objects too? The top-level key is the unit of ownership. Below it, the extension that owns the key defines what its value means. A recursive merge would impose merge semantics on values the protocol otherwise treats as opaque, prevent an extension from replacing its own object in one update, and make `null` inside an extension's value mean removal. Stopping at the top level isolates writers from each other while leaving each value to its owner. ### Why can't a key store a literal `null`? `null` is the removal signal, so storing it would require a second representation of removal. This is the same trade-off `rawInput` and `rawOutput` already make on tool calls, and the one JSON Merge Patch makes. An extension that needs a distinct empty value can use `false`, `{}`, or a value of its own. ### How does a sender replace all metadata at once? It sets each key it wants to remove to `null` alongside the new keys in a single update. The original sender usually knows which keys it sent earlier. Otherwise it can send `_meta: null` followed by an update with the new object, accepting that the Client briefly has no metadata. ### Why not keep whole replacement and ask writers to resend every key? That works only when a single writer controls every key and remembers them all. `_meta` is shared by extensions and intermediaries that do not know each other's keys, which is why it was the one patch field that needed a warning in the migration guide. ### Does this resolve conflicts between writers? No. It keeps writers of different keys from erasing each other's data. Two writers of the same key still depend on receive order, and `_meta: null` still clears every key. ### Why isn't `plan_update` included? `plan_update` replaces a plan's entries as a whole, and its `_meta` does not distinguish omission from `null`. Whether that metadata belongs to the plan or only to the notification is a separate decision. Making it a retained patch would need its own change. ### Does this change `params._meta` on `session/update`? No. Notification-level metadata is not stored with an entity and is not a patch. It remains the place for data about a single notification, such as trace context. ## Revision history * 2026-10-13: Initial draft. # ACP v2 Proposal Source: https://agentclientprotocol.com/rfds/v2/overview Author(s): [@benbrandt](https://github.com/benbrandt) This is a tracking RFD for the collection of RFDs that require breaking changes to the protocol and should make up ACP v2. ## Elevator pitch > What are you proposing to change? With ACP, we aim to move fast while keeping breaking changes to a minimum. However, we've gotten to a point where there are enough changes we would like to do that would benefit from some core redesigns that will allow for extending the protocol with new features more easily. We've also managed to add new features that have led to learnings that would benefit from consolidation and alignment in other areas of the protocol to smooth things out and make things more consistent. ## Status quo > How do things work today and what problems does this cause? Why would we change things? We have had a fairly successful time adding new features via new capabilities and adding in new features in a non-breaking way. But some of the learnings we have made will require breaking changes, and it feels like there are enough of these built up, or RFDs we are stuck due to required changes that now is a good time to do so. ## What we propose to do about it > What are you proposing to improve the situation? ### Current Active RFDs Current RFDs with active maintainer focus that are targeting the v2 release: * [New Prompt Lifecycle](./prompt.mdx) * [Enum Variant Extension](./enum-variant-extension.mdx) * [Client Filesystem and Terminal Execution Surface](./client-filesystem-terminal-capabilities.mdx) * [Plan Variants](./plan-variants.mdx) * [Tool Call Updates](./tool-call-updates.mdx) * [Message Updates and Chunks](./message-updates.mdx) * [Permission Requests](./permission-requests.mdx) * [Required Session Methods](./required-session-methods.mdx) * [Session Resume Replay](./session-resume-replay.mdx) * [Diff File States](./diff-file-states.mdx) * [Terminal Output](./terminal-output.mdx) * [Metadata Patches](./meta-patches.mdx) * [Background Work](./background-work.mdx) These RFDs define v2's breaking changes, and they are the scope of the v2 Preview. Other RFDs, such as [Remote Transports](../streamable-http-websocket-transport.mdx), add new transports, methods, or capabilities without changing existing messages, so they don't block v2. A transport can add its own requirements, such as reconnection, keepalive, or stream resumption, without changing the core protocol. Other RFDs will progress separately and are not dependent on breaking changes (specifically the new prompt lifecycle) and can land in either or both v1 and v2. ### v2 Changes This list tracks every breaking change in v2. Smaller changes without their own RFD are recorded here and in the [migration guide](/protocol/v2/migration). * Remove the dedicated session modes API from v2. This includes the `modes` session response fields, `session/set_mode`, `current_mode_update`, and the `SessionMode*` types. * Agents should expose mode-like and model-related state through [Session Config Options](../session-config-options.mdx) instead of dedicated mode or model selector APIs. * Remove the v1 Client filesystem and terminal execution surface from v2. This includes `clientCapabilities.fs`, the top-level `clientCapabilities.terminal` field, `fs/*` methods, `terminal/*` methods, and the Client-owned semantics of v1 terminal tool-call content. Terminal authentication remains separate under `capabilities.auth.terminal`. * Add [Agent-owned, display-only terminal output](./terminal-output.mdx). Tool calls reference terminals by `terminalId`; terminal upserts carry `command`, absolute `cwd`, replay snapshots, and exit status; terminal output chunks append independently base64-encoded bytes. The display surface is baseline v2 and does not add Client execution or control methods. * Make [plan variants](./plan-variants.mdx) the default v2 plan shape by replacing the old `plan` session update with item-based `plan_update`. * Replace the v1 split between `tool_call` and `tool_call_update` with a single [tool-call update](./tool-call-updates.mdx) upsert shape keyed by `toolCallId`. * Add [tool-call content chunks](./tool-call-updates.mdx) so Agents can stream individual `ToolCallContent` items that append to a tool call. * Replace the v1 `Diff` `oldText` / `newText` shape with [diff file states](./diff-file-states.mdx): optional Git `--patch` text (`git_patch`) plus structured file operations for add, delete, modify, move, copy, and non-text changes. * Make [permission requests](./permission-requests.mdx) carry a required prompt `title` and optional extensible `subject` tagged union. Tool-call permissions use `subject.type: "tool_call"` with the same `ToolCallUpdate` payload shape as session updates, command permissions use `subject.type: "command"` with the command, required absolute working directory, and optional display associations, and subject-less permissions rely on the common prompt fields. * Add [whole-message updates](./message-updates.mdx) for `user_message`, `agent_message`, and `agent_thought` alongside streamed chunks. Message updates are upserts keyed by `messageId`; their `content` arrays replace current message content, while chunks append to the current content. * Apply the top-level `_meta` of upsert updates as a [metadata patch](./meta-patches.mdx): omission leaves it unchanged, `null` clears it, and an object patches stored metadata by top-level key, where a key set to `null` is removed and any other value replaces that key whole. * Require [message IDs](../message-id.mdx) on streamed message chunks. * Acknowledge [prompt insertion](./prompt.mdx) by returning the inserted user message's `messageId` from `session/prompt`, without waiting for foreground work to finish. Live user-message updates use the same ID; retention remains optional. Prompts sent during active work are inserted or held in order, not rejected. * Report foreground activity with [`state_update`](./prompt.mdx) (`running`, `idle`, `requires_action`), and move the stop reason from the `session/prompt` response to the idle update. * Report [failures after prompt insertion](./prompt.mdx#report-failures-after-insertion) by ending foreground work with an idle `state_update` whose `stopReason` is `error`, carrying an optional JSON-RPC error object. A JSON-RPC error on `session/prompt` always means the message was not inserted. * Do not use JSON-RPC 2.0 batches. Each transport message is a single request, notification, or response, and receivers reject an array with `-32600`, as MCP does since 2025-06-18. * Make [enums and tagged unions open](./enum-variant-extension.mdx) where a safe fallback exists: `_`-prefixed values are for extensions, and other unknown values are reserved for future ACP versions. * Add the `cancelled` status for tool calls and plan entries. * Add [background work](./background-work.mdx): a `paused` tool call status, opt-in `capabilities.cancel` on tool calls and terminals with `tool_call/cancel` and `terminal/cancel`, and a `background` list on state snapshots. * Allow initial `configOptions` and `availableCommands` in `session/new` and `session/resume` responses, and add `type` discriminators to commands (`command`) and command input (`text`). * Reject `initialize` with `-32022` (Unsupported protocol version) when no supported version is at or below the requested one, with the requested and supported versions in the error data. * Require a `type` discriminator on `session/set_config_option` values, and rename the config option `group` field to `groupId`. * Make `usage_update.cost` a patch field: omitted leaves it unchanged and `null` clears it. * Make `mcpServers` optional on session setup requests. * Clean up capability naming and organization: * Use a single `capabilities` field in both `initialize` params and results, replacing the v1-style `clientCapabilities` and `agentCapabilities` fields. * Require implementation metadata in both `initialize` params and results with a single role-agnostic `info` field, replacing the v1-style `clientInfo` and `agentInfo` fields so agent-to-agent and other symmetric ACP connections do not need role-specific field names. * Group authentication methods under `auth/*`: v2 uses `auth/login` and `auth/logout` instead of v1's top-level `authenticate` and `logout` method names. An Agent that returns a non-empty `authMethods` list advertises the authentication surface and **MUST** implement both methods; if the field is omitted or empty, Clients **MUST NOT** call either method. There is no `capabilities.auth.logout` support marker, and `capabilities.auth` remains orthogonal for authentication-related extensions. The generated request and response type names follow the grouped method naming as `LoginAuthRequest` / `LoginAuthResponse` and `LogoutAuthRequest` / `LogoutAuthResponse`. * Rename the authentication method descriptor's `id` to `methodId`, make its `type` discriminator required, and advertise Client support for `terminal` methods with a `capabilities.auth.terminal` object marker. * Use concise capability group names such as `session` and `auth`, replacing names like `sessionCapabilities`. * Make `session` optional so Agents that only expose non-session method surfaces can omit it. * Require the baseline session lifecycle methods when `session` is present: `session/new`, `session/list`, `session/resume`, `session/close`, `session/prompt`, `session/cancel`, and `session/update`. * Remove `session/load` from v2. `session/resume` handles both no-replay resume and full replay by using the optional `replayFrom` cursor from the [Session Resume Replay](./session-resume-replay.mdx) RFD. * Move optional session-scoped capability groups under `session`, including `prompt` and `mcp` as `session.prompt` and `session.mcp`. * Represent support markers as capability objects instead of booleans. Supplying `{}` means supported, while omission or `null` means unsupported. Booleans remain appropriate for actual data or configuration inside an already-advertised capability. * Align MCP server transports with the current MCP transport model: * Remove the deprecated HTTP+SSE MCP transport from v2. * Make stdio an explicit `session.mcp.stdio` capability so Agents that cannot launch local subprocesses can opt out. * Require MCP server configurations to include a `type` discriminator, including `type: "stdio"`, so unknown future transports can be preserved as extension/future variants. * Keep HTTP as the remote MCP server transport capability. * Unify ID naming and typing across the v2 schema. Protocol fields should use domain-specific ID names such as `messageId`, `toolCallId`, `planId`, `terminalId`, `configId`, and `methodId` rather than a generic `id` whenever the field identifies a protocol entity or references another resource. ### RFDs to be Written Changes under consideration that still need to be drafted or moved to draft: * MCP: revamp MCP server support, including tool timeouts and more lifecycle methods ## Shiny future > How will things play out once this feature exists? There is a lot of work to do, especially on the SDK side, to support both versions, but it is likely that we should be able to allow Agents specifically to target v2 APIs and gracefully fall back to v1 messages for v1 clients, to avoid huge support issues. However, once all of this work is in place, it should be much easier to make additional breaking changes in the future when necessary, we've been kind of letting this build up given the effort required for the entire ecosystem, but the ACP maintainers will be charting a course forward to make this as smooth as possible! ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? ### v2 + v1 Schema publishing I created the initial [draft of the v2 schema](https://github.com/agentclientprotocol/agent-client-protocol/pull/1099) as a direct duplicate of v1. The side-by-side Rust types still make the schema differences explicit as v2 evolves. The Rust schema does not provide cross-version conversion. Even initialize-request normalization depends on SDK routing policy, while many v2 lifecycle and update semantics require state that a schema-level conversion cannot supply. SDKs supporting both versions should expose explicit versioned implementations or build a purpose-specific adapter at their runtime boundary. Once we have more pieces in place, we can start publishing both schemas to assist SDK developers to start figuring out how to support this. **This should be done in an opt-in, off by default, clearly labeled unstable way for SDK consumers**. There will likely be bumps as we figure out the necessary plumbing and we shouldn't be shipping v2 in production without feature flags prior to a more stable release as we align all of the necessary pieces. ### SDK Support With the needed breaking changes, as much as possible I am targeting having a consistent API surface for Agents, since they will want to target v2 APIs but still support v1 clients. Because of how the version negotiation works, if we can achieve the same thing for clients that will be great, but if not, they will at least be provided clear version entry points. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ## Revision history * 2026-10-30: Added the v2 Background Work changes to the change list now that they are in the v2 schema. * 2026-10-30: Added the config option `type`/`groupId` changes and the `usage_update.cost` patch semantics to the change list. * 2026-10-29: Scoped the v2 Preview to the RFDs with breaking changes. Remote Transports and other additive work no longer block v2, and transport-specific reliability requirements belong to each transport. * 2026-10-29: Dropped JSON-RPC batches from v2, following MCP. * 2026-10-29: Reconciled the v2 change list with the migration guide, adding open enums, `state_update`, `cancelled` statuses, setup-response commands, `-32022`, optional `mcpServers`, and the auth method descriptor changes. ID examples now use stable fields only. * 2026-10-27: The v2 Background Work RFD now adds a `paused` tool call status, leaves agent-internal housekeeping out of the `background` list, and defines how permission requests for background work are identified. * 2026-10-26: The v2 Background Work RFD now lists background terminals, adds opt-in `terminal/cancel`, and defines ordering rules and background subagent listing. * 2026-10-21: Added the v2 Background Work RFD for tool calls that outlive foreground work, individual tool-call cancellation, and a `background` list on state snapshots. * 2026-10-13: Added the v2 Metadata Patches RFD so a top-level `_meta` object on an upsert patches stored metadata by key instead of replacing it. * 2026-10-01: Recorded that failures after prompt insertion end foreground work with an `error` stop reason that carries an optional JSON-RPC error. * 2026-10-12: Specified that every `git_patch` path, including rename and copy headers, is absolute with no `a/` or `b/` prefix, and otherwise follows Git, including `/dev/null` and path quoting. * 2026-09-30: Removed NES-specific capability and optional-session examples; `session` remains optional for Agents exposing non-session method surfaces. * 2026-07-20: Clarified `git_patch` and renamed its payload from `diff` to `text`. * 2026-07-20: Clarified that `idle` means ready for a new prompt while background updates may continue; steering and queueing remain separate concerns. * 2026-07-20: Scoped the v2 authentication surface to Agents that return one or more valid `authMethods`; those Agents must implement both `auth/login` and `auth/logout`, while omission or an empty array means Clients must not call either method. * 2026-07-14: Added the v2 Terminal Output RFD for Agent-owned, display-only terminal output. * 2026-07-02: Added the v2 Diff File States RFD for renderable git patches, structured file operations, and non-text file changes. * 2026-07-02: Moved the v2 RFD collection to Active. * 2026-07-02: Added the v2 Permission Requests RFD for required permission titles, optional structured subjects, and tool-call permission subjects. * 2026-07-02: Added the v2 Session Resume Replay RFD and recorded that `session/resume` replaces `session/load` in v2 by using optional `replayFrom` cursors. * 2026-07-02: Added the v2 Required Session Methods RFD and recorded that `session/list`, `session/resume`, and `session/close` are baseline when `session` is present. * 2026-06-30: Recorded the v2 ID unification principle: prefer domain-specific ID field names. * 2026-06-25: Recorded the v2 initialize information cleanup: required role-agnostic `info` in both params and results, replacing `clientInfo` and `agentInfo`. * 2026-06-25: Recorded the v2 authentication method cleanup: grouped `auth/login` and `auth/logout` method names replace v1's top-level `authenticate` and capability-gated `logout`, with matching generated type names for login and logout auth requests and responses. * 2026-06-09: Added tool-call content chunks for streaming individual `ToolCallContent` items. * 2026-06-09: Added the v2 Message Updates and Chunks RFD to define whole-message upserts alongside streamed message chunks. * 2026-06-08: Added the v2 Tool Call Updates RFD to make `tool_call_update` the single upsert-style tool-call session update. * 2026-06-05: Recorded the v2 capability cleanup: unified initialize capability fields, optional `session` support for NES-only agents, session-scoped `prompt` and `mcp` capabilities, object-shaped support markers, explicit `session.mcp.stdio`, removal of deprecated MCP SSE transport, and tagged MCP server transport configs. * 2026-06-02: Recorded the v2 decision to follow JSON-RPC 2.0 batch request and notification behavior. * 2026-06-02: Recorded the v2 decision to remove Client filesystem and terminal execution capabilities, methods, and Client-owned terminal tool-call content. * 2026-06-02: Added the v2 Plan Variants RFD to make item-based `plan_update` the default v2 plan shape. * 2026-06-01: Recorded that model selection should remain represented by session config options instead of a dedicated selector API. * 2026-05-28: Recorded the v2 decision to remove session modes in favor of session config options * 2026-05-06: Initial draft # v2 Permission Requests Source: https://agentclientprotocol.com/rfds/v2/permission-requests Author(s): [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? ACP v2 should make `session/request_permission` extensible beyond tool calls by giving every permission prompt a required `title` and optional structured `subject` context. Tool-call permissions use `subject.type: "tool_call"`, command permissions use `subject.type: "command"`, and permission requests that are not tied to a structured subject omit `subject`. Permission prompt copy should live in common `title` and `description` fields rather than in subject-specific data. ## Status quo > How do things work today and what problems does this cause? Why would we change things? In v1, permission requests are tied directly to a `toolCall` field. This works for tool execution approvals, but it makes the method harder to extend to other approval-like decisions. It also tempts agents to put permission prompt text into `ToolCallUpdate.title` or `ToolCallUpdate.content`. In v2, those fields are patch state for the displayed tool call. Using them for permission-only UI copy can accidentally change the tool call shown elsewhere. ## What we propose to do about it > What are you proposing to improve the situation? `RequestPermissionRequest` should have these common fields: * `sessionId` * `title` * `description` * `options` * `subject` * `_meta` `title` is required and is the minimum user-visible prompt text. `description` is optional explanatory text. Omitted and `null` descriptions are equivalent and mean no extra detail was provided. `subject` is optional structured context and uses a tagged union when present: ```json theme={null} { "title": "Approve file edit?", "description": "Allow the agent to edit src/main.rs?", "subject": { "type": "tool_call", "toolCall": { "toolCallId": "call_001" } } } ``` Command permissions carry a self-contained description of the proposed execution: ```json theme={null} { "title": "Run the test suite?", "subject": { "type": "command", "command": "cargo test", "cwd": "/workspace/project", "toolCallId": "call_001", "terminalId": "term_001" } } ``` For a command subject, `command` and `cwd` are required, and `cwd` **MUST** be absolute. `toolCallId`, `terminalId`, and `_meta` are optional and nullable; omission and `null` are equivalent and mean the value was not provided. The IDs associate the request with displayed state when known; they do not change that state. The command describes what the Agent wants permission to execute and never asks the Client to execute it. ```json theme={null} { "title": "Continue with elevated permissions?" } ``` Omitted and `null` subjects are equivalent and mean no structured subject was provided. A missing subject is not a separate subject variant. Unknown future subject types should be preserved by clients that proxy, store, replay, or forward permission requests. Clients that cannot understand the subject should show a generic permission prompt or decline according to policy. ## Shiny future > How will things play out once this feature exists? Agents can request permission for tool calls without conflating permission UI text with tool-call state. Command approvals can show the exact command and working directory without hiding them in generic tool-call input. Agents can also request permission for operations that have no structured subject, and future structured subjects can be added without changing the common permission request fields. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? 1. Replace the v1-style top-level `toolCall` request field in v2 with an optional `subject` tagged union. 2. Add the `tool_call` subject variant. 3. Add the `command` subject variant with a required command and absolute working directory plus optional associations. 4. Add common required `title` and optional `description` fields. 5. Keep `options` as the required list of choices the user can select. 6. Preserve unknown subject variants while keeping known subject payloads distinct from unknown fallback variants. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why require `title`? The title is the minimum text a client can display when asking the user to choose an option. Requiring it keeps subject-less permission requests usable without requiring clients to synthesize prompt copy. ### Why make `subject` optional? Some permission requests are valid without a structured target. In those cases, `title`, `description`, and `options` are the permission request, while `subject` is additional context for clients that can render a richer prompt. ### Why not flatten subject fields into the request? `title`, `description`, and `options` describe the permission prompt. `subject` describes what the permission is about. Keeping the subject nested avoids collisions between common request fields and future subject-specific fields. ### Why not use `ToolCallUpdate.title` or `ToolCallUpdate.content` for permission copy? Those fields patch the displayed tool call. Permission-only prompt copy belongs in the common `title` and `description` fields so a permission request does not accidentally replace tool-call title or content. It's quite common to have a reason you want to display for the permission request itself without updating the persisted tool call for the rest of the session. ## Revision history * 2026-07-14: Added the command permission subject for Agent-executed commands. * 2026-07-02: Initial draft # v2 Plan Variants Source: https://agentclientprotocol.com/rfds/v2/plan-variants Author(s): [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? ACP v2 should make the extensible `plan_update` shape the default plan notification, remove the old v1 `sessionUpdate: "plan"` shape from the v2 schema, and keep the rest of the plan operations work in the unstable plan-operations surface while that RFD continues. For now, v2 should stabilize only the item-based plan content variant: ```json theme={null} { "sessionUpdate": "plan_update", "plan": { "type": "items", "planId": "plan-1", "entries": [ { "content": "Step 1", "priority": "high", "status": "pending" } ] } } ``` The markdown, file, and removal pieces from [Plan Operations Support](/rfds/plan-operations) remain behind the unstable plan-operations feature while that RFD continues. V2 does not need a separate `plan` runtime handshake for those unstable operations. ## Status quo > How do things work today and what problems does this cause? Why would we change things? The v1 plan update is a flattened session update: ```json theme={null} { "sessionUpdate": "plan", "entries": [{ "content": "Step 1", "priority": "high", "status": "pending" }] } ``` This shape has no stable place for a plan ID or a content discriminator. Adding either field to the same `plan` variant would create a mixed old/new shape and make future plan formats harder to add cleanly. The Plan Operations RFD already introduced a more extensible tagged shape through `plan_update`, plus markdown, file, and removal operations. Those pieces are still useful, but v2 does not need to wait on them to adopt the extensible baseline. ## What we propose to do about it > What are you proposing to improve the situation? ACP v2 should: * Remove the old `sessionUpdate: "plan"` variant from the v2 schema. * Add `sessionUpdate: "plan_update"` to the default v2 schema. * Stabilize only the `plan.type: "items"` content variant for now. * Keep unknown plan content variants parseable and preservable using the [v2 enum variant extension](/rfds/v2/enum-variant-extension) rules. * Require every plan content variant, including unknown future/custom variants, to carry a `planId`. * Remove `ClientCapabilities.plan` from v2. * Keep `markdown`, `file`, and `plan_removed` behind `unstable_plan_operations` until the Plan Operations RFD settles. The stable v2 `plan_update` shape does not require a capability. The unstable plan operations remain gated by the draft unstable protocol surface, not by a v2 `plan` field. ### Compatibility This RFD doesn't define v1↔v2 conversions. Implementations that bridge versions follow the migration guide's advice on [adapters](/protocol/v2/migration#share-application-logic-not-wire-shapes). ## Shiny future > How will things play out once this feature exists? The v2 schema has a single extensible place for plan content from the start. ACP can later promote markdown, file-backed, removal, or other plan operations without introducing another incompatible plan update shape. Clients that only understand item-based plans can still preserve or display unknown plan content generically, while extensions get the `_`-prefixed namespace defined by the enum variant extension RFD. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? 1. Make `PlanUpdate`, `PlanUpdateContent`, `PlanItems`, and `PlanId` part of the default v2 Rust schema source. 2. Remove `PlanCapabilities` from the v2 Rust schema source. 3. Leave `PlanFile`, `PlanMarkdown`, and `PlanRemoved` behind `unstable_plan_operations`. 4. Remove `SessionUpdate::Plan` from the v2 schema and make `SessionUpdate::PlanUpdate` the default plan variant. 5. Require `planId` on unknown `PlanUpdateContent` fallback payloads. 6. Regenerate v2 schema docs so the default v2 surface shows only the item-based tagged plan shape. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why not wait for the Plan Operations RFD to complete? The item-based tagged shape is enough to make v2 extensible and remove the old flattened plan variant. The rest of the Plan Operations RFD can continue behind the unstable feature flag. V2 does not need `plan` because those operations are either part of the draft unstable protocol surface or absent from the stable schema. ## Revision history * 2026-10-29: Removed the FAQ about a `main` plan ID for v1 conversion, since this RFD leaves conversion to adapters. * 2026-10-27: Dropped the step that kept `sessionUpdate: "plan"` rejected. Like other removed v1 variants, it is treated as an unknown v2 update. * 2026-06-02: Initial draft # v2 Prompt Lifecycle Source: https://agentclientprotocol.com/rfds/v2/prompt Author(s): [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? For v2 of the protocol wire format, I am proposing a change in the lifecycle of the prompt request, allowing for more dynamic session updates from the agent, and unlocking new capabilities in the process. Once a session is created, the agent will be able to send session updates at any point in time, and prompt requests will last until the user message is inserted into the conversation, not until the end of the turn. As I'll go into later, this not only removes some current awkwardness around the prompt request lifecycle, but also provides a more flexible foundation to add features like queued messages and multi-client replay. This can even allow the agent to initiate an interaction in a session rather than requiring it to wait for a user prompt, which is becoming increasingly important for background tasks and agents which may send updates before or after a "turn" is over since its runtime might be different than the main conversation. This sketch explores returning an agent-generated `messageId` in the prompt response. For `session/prompt`, acceptance means insertion of the user message into the ACP conversation. The same ID identifies that message in live updates and, if retained, later replay, so clients that receive the response can correlate their submissions without introducing a second identifier. Insertion is distinct from processing completion and does not require persistent history. Because the response no longer spans the turn, it can no longer report failures that happen during it. A failure after insertion instead ends foreground work with an `error` stop reason on the idle `state_update`, carrying the same JSON-RPC error object a v1 prompt error response carries. ## Status quo > How do things work today and what problems does this cause? Why would we change things? Currently, the protocol kind of assumes that all turns will be initiated by a client and ended by an agent, with a series of session update notifications in-between. While in many cases this is enough, it is becoming clear that this model is not flexible enough. It is not clear how to model queued messages for instance: would these create a new turn request lifecycle? Or fit into the existing one? What if the agent wants to submit some text at the start of a session *before* the user prompts? Or a status update? Also, if an agent finishes its turn, wants to wait for the next user action, but has a background subagent or task running, can it only submit updates about that status after the user prompts again? When replaying a session, the prompt request can be turned into a user message notification, but what about the end of turn response? If you call load during a currently running session, how do you know that the turn is done? Some clients handle these out-of-turn updates more gracefully than others. But it is a constant point of confusion in discussions and issues. Decoupling the prompt response from session updates also leaves a correlation gap: when the agent reports an accepted user message, how does the submitting client know which pending prompt it belongs to? Matching by content or arrival order is unreliable when users submit identical prompts, multiple clients share a session, or insertion is delayed. The same problem appears after reconnecting if the agent accepted a prompt but the client never received its response. In the spirit of allowing as much flexibility in the protocol for new paradigms and designs to emerge in the prompt lifecycle, I think imposing fewer restrictions in the protocol, whether explicitly described or just implicitly inferred because of vague wording, on when participants can make session updates will allow for more dynamic sessions, as well as make it easier to extend to new use cases in the future. ## What we propose to do about it > What are you proposing to improve the situation? ### Change the `session/prompt` response `session/prompt` is still a request, but its response lifecycle will change. For this method, **acceptance means insertion**: the agent has added the user message to its ACP conversation, with a `messageId` and a position relative to other messages. Receiving the request, assigning an ID, or holding the input for later insertion is not acceptance. The agent **MUST** respond successfully once the user message has been inserted, without waiting for foreground processing to finish. It **MUST NOT** send a successful response before insertion. The proposed successful response **MUST** include the inserted message's `messageId` as a non-null string; omission and explicit `null` are both invalid. A request rejected before insertion uses a JSON-RPC error response instead. Insertion is a logical conversation event, not a durable-storage guarantee or a claim that the model has consumed the input. Locally handled commands follow the same rule by inserting a live-only user message into the ACP conversation, without requiring a persisted transcript entry. ```json theme={null} { "jsonrpc": "2.0", "id": "req_12345", "result": { "messageId": "mess_456def" } } ``` This extends the [Message ID RFD](/rfds/message-id) without changing ID ownership: the agent still generates opaque message IDs, but now returns the accepted user message's ID to the submitting client as well as including it in session updates. No client-generated `promptId` is added to the request or updates. The response confirms insertion and establishes the submitting client's association with the message. The corresponding message updates report its content and placement; `state_update` notifications report foreground work. These are reports of insertion and processing, not separate acceptance and insertion phases. ### Correlate prompts with accepted user messages The JSON-RPC request ID links a response to the client's submission. The returned `messageId` then links that submission to session updates and replay: | Field | Identifies | Generated by | | - | - | - | | JSON-RPC `id` | One request/response exchange | The request sender | | `messageId` | The accepted logical user message | The agent | The working assumption is **one accepted submission, one logical ACP user message**. The agent **MUST** assign a distinct `messageId` to each accepted submission, even when its content is identical to another submission. IDs are unique among user messages within the session and **MUST NOT** be reused for a different submission. Agent messages and thoughts have their own ID spaces, so the same string may also identify one of those. The agent **MUST** use the returned ID for all updates and chunks for that user message. The response and the user-message update describe the same insertion, but clients **MUST** tolerate those updates arriving before or after the response. On receiving the response, the submitting client can associate its local pending input with `(sessionId, messageId)`, reconciling with an already-received message rather than creating a second canonical message. Only the submitting client has the request/response association. Other clients identify the message by `messageId` without needing the original request. Neither content equality nor notification arrival order should be used to infer which client submitted a message. An adapter can use an underlying agent's user-message echo or insertion event as evidence of insertion and respond with the message's ID while processing continues. It may use a private per-submission token to match that event to the outstanding request; this does not require a new field in ACP. An ID assigned in advance is not by itself evidence of insertion. The returned ID may be native to the underlying agent or adapter-owned, provided updates and replay preserve it consistently. ### Additional Agent `session/update` notification types Because `session/update`s can more freely flow from the agent, and we lost the ability to pass end\_turn, errors, and other information from the prompt response, we need to provide the agent with the affordance for a few more notification types. #### User message reported to clients The prompt response acknowledges insertion. The agent **MUST** report each inserted user message through `user_message` or `user_message_chunk` updates, using the same `messageId`. These updates establish its content and placement in the client-visible conversation, not a guarantee that the agent stored it for later replay. Clients may send `session/prompt` while foreground work is active. Agents do not reject a prompt only because work is active: they insert it right away or hold it and insert held prompts in the order received, and a held prompt's response stays pending until insertion. See [Prompts During Active Work](/protocol/v2/prompt-lifecycle#prompts-during-active-work). Capabilities for explicit queueing or steering are left to a later RFD. The question then turns to what makes up this notification. Which brings us to: **Who owns the user message id?** The [Message ID RFD](/rfds/message-id) defines that the agent owns message IDs. The client sends the prompt without a message ID, and the agent returns the ID when acknowledging insertion. The corresponding user-message update reports the agent-owned content and placement under that same ID. The response does not add content to the conversation a second time; it establishes the submitting client's association with the inserted message. My current proposal is that this would look like the client sending the following message: ```json theme={null} { "jsonrpc": "2.0", "id": "req_12345", "method": "session/prompt", "params": { "sessionId": "sess_789xyz", "prompt": [ { "type": "text", "text": "What's the capital of France?" } ] } } ``` And the Agent responds with: ```json theme={null} { "jsonrpc": "2.0", "id": "req_12345", "result": { "messageId": "mess_456def" } } ``` And reports the user message with the notification: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_789xyz", "update": { "sessionUpdate": "user_message", "messageId": "mess_456def", "content": [ { "type": "text", "text": "What's the capital of France?" } ] } } } ``` The submitting client uses the response's `messageId` to reconcile its optimistic message with the agent-reported message. If the notification arrives first, the response later establishes that association. Other clients simply render the message under the same ID. The response does not determine the message's position in the feed. This is a new message type as well. Not a `user_message_chunk` but just a `user_message` that allows for sending the entire message at once. The [Message Updates and Chunks](./message-updates.mdx) RFD defines the corresponding whole-message update and streamed-chunk patterns for user messages, agent messages, and agent thoughts. ##### Correlation and replay Live correlation and history retention are separate: * The response and all updates for the accepted user message **MUST** use the same `messageId`. * Agents are **NOT REQUIRED** to persist every accepted input or retain it for any minimum period. A message may be live-only, or later omitted under the agent's history-retention policy. * If an agent retains and replays that same message within the session, it **MUST** reuse the returned `messageId`, including after reconnecting or restarting. This is an identity guarantee for retained messages, not a requirement to retain them. Clients **MUST NOT** assume that every acknowledged message will appear after resuming a session. Adapters do not need a separate permanent transcript for messages their underlying runtime does not retain, or to reconstruct cleared or discarded messages solely for correlation. This does not change v1's replay rules. A client that received the response and retained its `(sessionId, messageId)` association can recognize the message if it is replayed. It requests retained history with `session/resume` and `replayFrom: { "type": "start" }`, as described in the [Session Resume Replay RFD](./session-resume-replay.mdx). Omitting `replayFrom` resumes without replay. **A lost response remains an ambiguous outcome.** The agent may have accepted the input, but the client does not know its ID. Replay can restore retained conversation history, but cannot reliably associate a message with that uncertain submission. Clients must not guess from content or order, or assume retrying cannot create a second submission. A client-generated correlation token could address this limitation for retained messages separately. A successful response confirms that the message was inserted. Its absence from later replay does not contradict that acknowledgment: the message may have been live-only or may no longer be retained. Imported or non-ACP messages continue to use agent-generated message IDs without a corresponding prompt response. ##### Streaming user messages The agent can stream a newly inserted user message using `user_message_chunk` updates with the returned `messageId`. No metadata-only `user_message` update is required just to establish correlation, and the chunk schema remains unchanged: ```json theme={null} { "sessionUpdate": "user_message_chunk", "messageId": "mess_456def", "content": { "type": "text", "text": "What's the capital of France?" } } ``` When replay reconstructs a user message from its beginning using chunks, the agent **MUST** first send a `user_message` update with `content: []`. This clears any content the client already holds for that `messageId`, preventing the replayed chunks from being appended to an earlier copy: ```json theme={null} { "sessionUpdate": "user_message", "messageId": "mess_456def", "content": [] } ``` The agent then sends the message's chunks. Alternatively, a full-content `user_message` update replaces the retained content directly. A metadata-only update does not clear content and is not sufficient for restarting the message's content from the beginning. These rules use the existing message-upsert semantics without an implicit client-side reset. When reconciling an optimistic message, clients should not append streamed content to their local copy of the submitted prompt; the agent's content stream is authoritative. #### `state_update` notification This would be a notification from the agent to indicate that it's current status has changed, such as the "turn" has ended, carrying information like `stopReason` and `usage` data for that turn. **Running**, to indicate that a turn has begun. Important now that turns aren't tied necessarily to prompts: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_789xyz", "update": { "sessionUpdate": "state_update", "state": "running" } } } ``` **Idle**, whenever the agent is done, with optional data on why: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_789xyz", "update": { "sessionUpdate": "state_update", "state": "idle", "stopReason": "end_turn" } } } ``` **Requires Action**, for when the agent is trying to run, but needs to wait on user input to continue, it isn't just idle: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_789xyz", "update": { "sessionUpdate": "state_update", "state": "requires_action" } } } ``` We could explore adding which permission or elicitation it is waiting on if we wanted to make it clearer if we wanted. #### Foreground state contract The v2 [Session States](/protocol/v2/prompt-lifecycle#session-states) guide defines the normative transition table and provides lifecycle examples. States are snapshots of aggregate foreground activity, not events for individual requests: * A new session defaults to idle until a state update reports otherwise. Resume sends a current-state snapshot after any history replay and before its response, even without replay. * Starting foreground work reports an active state, including `requires_action` directly if it starts blocked. Reporting later user-action waits is recommended. Once reported, resuming progress reports `running` and ending work reports `idle`. Repeated snapshots are idempotent. * Permissions and elicitations for independent background activity do not themselves change an idle foreground state. With concurrent requests, a response changes state only if aggregate foreground activity changes. * Completed foreground intervals have an idle boundary. Completing an individual prompt or command while other foreground activity continues needs no boundary. Local commands handled from idle still report an active state and `idle`, even without model work. * Session cancellation resolves pending session-scoped permissions and ends active foreground work with `idle(cancelled)`. Agents should cancel individual elicitations that the affected work no longer needs, not every elicitation scoped to the session. Prompts the agent has not inserted, including held prompts, are answered with `-32800`. After cancellation completes, agents should ignore late answers rather than resume cancelled work. Repeated or resume snapshots do not cause new cancellations. Cancelling idle work needs no additional completion update. These rules use the existing wire types. Normal completion stop reasons remain recommended. The cancellation stop reason is required. ### Report failures after insertion In v1, `session/prompt` lasts until the end of the turn, so its error response can report a failure at any point: an expired credential, a provider outage, an exhausted quota. Once the response arrives at insertion, that channel is gone, and a failure after insertion has to end foreground work through the same `state_update` that reports every other outcome. When foreground work ends because of a failure after the user message was inserted, the Agent **MUST** report `idle` and **SHOULD** include the `error` stop reason and failure details. An Agent that knows it is idle but cannot determine why the work stopped may omit the stop reason; Clients still recognize that foreground work ended without inferring success or failure: ```json theme={null} { "jsonrpc": "2.0", "method": "session/update", "params": { "sessionId": "sess_789xyz", "update": { "sessionUpdate": "state_update", "state": "idle", "stopReason": "error", "error": { "code": -32000, "message": "Authentication required" } } } } ``` * `stopReason: "error"` means foreground work ended because something failed, not because it finished, reached a limit, was refused, or was cancelled. It applies to any foreground work, including work no prompt started; the insertion rule below is specific to `session/prompt`. * `error` is a field of the `error` stop reason, sitting beside `stopReason` on the idle update. It is optional and nullable; omission and `null` are equivalent: the Agent supplied no error details. When present, it is a JSON-RPC error object, with required `code` and `message` and optional `data`. The Agent **SHOULD** include it, and Clients may show `message` to the user. * `error` exists only on the `error` stop reason, the same way `stopReason` exists only on the `idle` state. Beside any other stop reason it is an unknown field. To express this, stop reasons become a union tagged by `stopReason` and flattened into the idle `state_update`, so a stop reason can carry fields of its own. The existing stop reasons have none, and their wire format is unchanged. Once the user message is inserted, the Agent **MUST NOT** report a later failure as an error response to `session/prompt`, even if it has not sent the response yet. The request succeeds with the inserted `messageId`, and the failure ends foreground work as above. A JSON-RPC error on `session/prompt` therefore always means the message was not inserted. This includes request cancellation: a `$/cancel_request` or internal cancellation answers `session/prompt` with `-32800` only before insertion. Afterwards the request still succeeds with the `messageId`, and the work is stopped with `session/cancel`. `error` uses the same codes as JSON-RPC error responses, so Clients can handle them the same way. For example, `-32000` (authentication required) can prompt the user to authenticate before sending another prompt. More specific categories, such as rate limits, an exhausted context window, or an overloaded provider, can be added later as codes or as structured `data` without changing this shape. As with every stop reason, the idle update follows all updates for the work that ended. Before sending it, the Agent **SHOULD** give each tool call that the failed work left unfinished a terminal status, using `failed` for calls that did not complete. A failure does not undo the insertion or any side effects the work already had, such as tools that ran. Sending the prompt again submits a new message; see [Does returning `messageId` make retrying safe?](#does-returning-messageid-make-retrying-safe). The `error` stop reason is only for failures that end foreground work: | Situation | How it is reported | | - | - | | Rejected before the user message is inserted | JSON-RPC error response to `session/prompt` | | Request cancelled after the user message is inserted | Success response with the `messageId`; the work is stopped with `session/cancel` | | Fails after insertion, and foreground work stops | Idle `state_update` with `stopReason: "error"` and `error` | | Fails, and work continues (a retried request, a failed tool) | A [`notice`](/rfds/session-notices) or a tool call with status `failed`; the state does not change | | Work is cancelled, even if aborting raises errors | Idle `state_update` with `stopReason: "cancelled"`, as the cancellation rules already require | | Background activity fails while the Agent is `idle` | Not a stop reason, since no foreground work ended | | The Agent process exits or the connection is lost | Detected by the Client; no update can report it | A v2 Client that predates the `error` stop reason handles it like any unknown stop reason: foreground work has ended, and it shows a generic stopped state. It does not need `error` to know that the work ended. Because the error is part of the idle snapshot, anything that carries that snapshot carries the failure too, including an exposed subagent's `subagent_update.state` and the current-state snapshot sent on resume. v1's `session/prompt` is unchanged; it already reports these failures as an error response. The one v1 surface that carries this idle snapshot, the draft [subagent](/rfds/subagents#current-work-state) `subagent_update.state`, gains the same `error` stop reason, because a v1 child has no prompt response that could report its failure. ## Shiny future > How will things play out once this feature exists? This isn't a huge schema change, but it is a fundamental behavior change in the protocol that I believe: * Provides agents with much more flexibility in how they want to update a client about a given session * Solves some concrete pain points in the current model (i.e. how to integrate prompts into session replay and multi-client replays, message IDs, etc) * Lets clients that received a prompt response reconcile optimistic submissions with live or replayed user messages without content matching or assuming a particular arrival order Ultimately, after months of using the current model, I am quite excited for what these small tweaks can unlock, and also how we can build on top of this in the future! ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? Overall, this isn't a huge lift on schema definition, but it is a large, **breaking** change in behavior which means we can only stabilize in protocol version 2. The v2 schema and guides define the insertion-receipt response. The implementation checklist is: 1. Add a required non-null `messageId` to `PromptResponse`, reusing the existing `MessageId` type. Leave `PromptRequest`, `UserMessage`, `ContentChunk`, and v1 unchanged; do not introduce `PromptId`. 2. Update the prompt lifecycle and session replay guides with insertion as the acknowledgment point, distinct from processing completion; response/update ordering; optional retention; stable IDs when retained messages are replayed; and the content reset when replaying chunks from the beginning. 3. Add serialization and schema coverage for valid response IDs and rejection of missing, `null`, or non-string IDs. 4. Exercise an ID assigned before insertion without an early successful response, notifications before and after the response, identical prompts with distinct IDs, submissions from multiple clients, retained associations across replay, imported messages without prompt responses, and both full-content and streamed updates. Include a locally handled command reported live but omitted from later replay, and a retained command replayed with the same ID without re-executing it. Cover the lost-response limitation rather than promising recovery, and verify that streamed replay does not duplicate retained content. 5. Make `StopReason` a union tagged by `stopReason` and flattened into the idle `state_update`, keeping the existing values' wire format and the tolerance for omitted, `null`, malformed, and unknown stop reasons. Add an `error` variant with an optional, nullable `error` field, reusing the existing `Error` type. Document the failure rules in the prompt lifecycle guide's stop reasons and cancellation sections. 6. Add serialization and schema coverage for the idle update with an `error`, without one, and with `error: null`, and verify that an `error` beside another stop reason is treated as an unknown field. Exercise a failure after insertion but before the response is sent: the response still succeeds and the idle update reports the failure. 7. Update examples and generated artifacts, then run `npm run generate` and `npm run check`. The schema and serialization tests establish the wire shape. Adapters still need to implement and validate insertion timing, live reporting for local commands, replay identity for retained messages, and reporting failures after insertion. The [foreground state contract](#foreground-state-contract) defines current-state synchronization on resume and gives guidance for cancellation races. Adapters and conformance suites should exercise the guide's traces, including concurrent requests and late answers. Those rules are separate from the insertion receipt's identity and do not require another prompt ID. Explicit queueing and steering capabilities, sender identity, safe retries, and submission idempotency guarantees remain outside this change. Depending on how the rest of v2 testing goes, we can either: 1. Make this an opt-in "future-flag" capability on v1 so people can experiment, but it would be an unstable feature regardless. 2. We establish a preview/beta flow for v2 We definitely need 2 regardless, and can likely handle this in a similar "unstable" manner as we do for current unstabilized features. It's likely timing will work out that we can just do it that way. If for some reason the timing doesn't work out, we can start experimenting with an unstable capability or some `_meta` flag. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? I've hopefully addressed all of the questions and concerns for what motivated this above, but happy to engage with others on this. ### Does `messageId` identify the client or user? No. It identifies a logical message. The submitting client recognizes its own message through the request/response association, not by parsing the message ID. Sender attribution and authorization remain separate concerns. ### Does the returned ID identify a turn or the agent's response? No. It identifies the accepted user message. A prompt may contribute to work already in progress, and agents may produce output without a prompt. Agent messages and tool calls retain their own IDs; `state_update` remains session-scoped. ### Does returning `messageId` make retrying safe? No. The ID is an acknowledgment, not a client-supplied idempotency key. A retry can be accepted as a distinct submission with a different ID, including after a lost response. This proposal does not promise automatic deduplication or exactly-once processing. ### Do locally handled commands need persistent history? No. Some local control commands complete without the runtime recording the submitted input. The adapter inserts a live-only user message for the command into the ACP conversation, assigns its `messageId`, and reports that insertion through the response and the user-message update. This is the command's insertion point; it does not require a runtime insertion event that will never arrive or a permanent transcript entry. The command may be absent from later history replay. If the agent does retain and replay it, it uses the same ID and reports the message without executing the command again. Returning a `messageId` promises live correlation, not archival storage. ### What alternative approaches did you consider, and why did you settle on this one? #### Client-generated correlation token A client-generated `promptId` on the request, preserved with the accepted input and its replayed user message, could identify a submission even if the response is lost. It could also identify pending input before the agent assigns a history-message ID. This is separate from letting the client choose the canonical `messageId`. That alternative adds a second identifier, a uniqueness requirement across clients, and a mapping between submissions and history messages. It would still need to define that mapping if several submissions could become one ACP history message, and would not by itself define queue lifecycle or safe retries. The returned-ID approach is the simpler candidate when one submission remains one logical ACP message and its ID is returned on insertion. A client-generated correlation token remains an option if reliable lost-response recovery or a separate submission lifecycle becomes a requirement; it could be combined with a returned `messageId`. #### Require acknowledgment before insertion An earlier response would acknowledge receipt or reservation rather than insertion, and could require agents to reserve an ID before their runtime creates the message. This RFD instead keeps the prompt request pending until insertion or rejection. If a future queueing design needs an earlier receipt, that is a separate acknowledgment from the insertion response defined here. #### Reuse the JSON-RPC request ID JSON-RPC IDs already associate the response with the submitting request. They are not suitable as persisted message identities: different clients or connections can reuse the same ID, and proxies may rewrite it. Returning the agent-owned `messageId` keeps these responsibilities separate. #### Let the client choose the canonical message ID The Message ID RFD rejected client-generated IDs as canonical message identities because they introduce multiple sources of IDs and require shared collision-avoidance rules. Returning an agent-generated ID preserves agent ownership while still giving the submitting client a correlation handle. #### Prompt as a notification Early discussions revolved around having this be a bidirectional stream of notifications on the session. While this felt very symmetrical and appealing, it ran into several problems in practice: 1. Clients only really had one type of notification that made sense to emit on the session: user messages 2. The Agent would still need to replay that message to show where it got accepted within the message history 3. We would then need a notification-based way of emitting errors for invalid prompts that would need to be tied to fire-and-forget notifications. Given that the agent is ultimately the owner of the session history, it makes sense that it is the sole notifier of the session, because it is the source of truth. By having all client interactions on the session remain requests, albeit much shorter-lived ones in theory, we still have a semantically meaningful way to communicate errors and when and how a given request was incorporated into the session. #### Report failures after insertion with a `failed` state `state` says whether the agent can accept a prompt now, and after a failure it can: it is idle. How the work ended belongs with the stop reason. A new state would also leave existing v2 clients unable to tell that foreground work ended: a client that doesn't know `failed` can only present it generically, which says nothing about whether the agent is still working. An unknown stop reason always arrives on an `idle` update, so the client still knows the work ended. #### Report failures after insertion with a separate error update An `error` update followed by `idle` gives clients two signals that must agree. The protocol would need rules for an error with no idle after it and for which idle an error belongs to, and the error would not be part of the state snapshot that `subagent_update.state` mirrors. Putting the error on the idle update avoids those rules. #### Report failures after insertion with an error-severity notice Notices are for user-facing information. Clients may ignore them, and they must not report fatal errors or change session state. That contract fits failures the agent recovers from, not one that ends the work. #### Put `error` beside the stop reason with a cross-field rule Keeping `stopReason` a plain string and adding `error` as a sibling field produces the same wire format, but the schema cannot say that `error` belongs to one stop reason. The protocol would need a prose rule that Agents send `error` only with `stopReason: "error"` and that Clients ignore it otherwise, and every implementation would have to enforce it by hand. Making `error` a field of the `error` stop reason states the rule in the schema, the same way `stopReason` belongs to the `idle` state. #### Define a new error type for failures after insertion Reusing the JSON-RPC error object keeps failures before and after insertion in one shape, lets clients reuse the code handling they already have, and lets v1 and v2 bridges convert in both directions without losing information. Finer categories can be added later as codes or in `data`. Codex's app-server makes the same split. A failed turn ends with `turn/completed` whose status is `failed` and whose details are in `turn.error`, while a separate `error` notification with `willRetry` reports transient errors that don't end the turn, which `notice` covers here. ## Revision history 2026-10-29: Message IDs are unique per message type, not across the session. Prompts sent during active work are inserted or held in order rather than rejected, and held prompts get `-32800` on cancel. 2026-04-13: Initial draft 2026-04-22: Move from bidirectional notification approach to a change in the prompt request lifecycle 2026-10-01: Report failures after insertion with an `error` stop reason that carries an optional JSON-RPC error # v2 Required Session Methods Source: https://agentclientprotocol.com/rfds/v2/required-session-methods Author(s): [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? For ACP v2, Agents that advertise the `session` capability should be required to support the core session lifecycle methods: `session/list`, `session/resume`, and `session/close`. These methods should no longer have individual v2 capability markers. The presence of `capabilities.session` should be enough for Clients to rely on the baseline session surface. ## Status quo > How do things work today and what problems does this cause? Why would we change things? In v1, several session lifecycle methods were added as optional capabilities: `loadSession`, `sessionCapabilities.list`, `sessionCapabilities.resume`, and `sessionCapabilities.close`. For v2, we can set a cleaner baseline. If an Agent supports sessions, it should support the lifecycle operations needed to create, discover, reconnect, replay, prompt, cancel, update, and close them. In practice, almost all agents, especially the most popular ones, already support these, and we know from users that they don't want to interact without these capabilities. ## What we propose to do about it > What are you proposing to improve the situation? When an Agent includes `capabilities.session` in its v2 `initialize` response, the Agent **MUST** support these baseline session methods: * `session/new` * `session/list` * `session/resume` * `session/close` * `session/prompt` * `session/cancel` * `session/update` The v2 schema should remove the optional `session.list`, `session.resume`, and `session.close` capability fields. The [Session Resume Replay](./session-resume-replay.mdx) RFD removes `session/load` from v2 and folds history replay into `session/resume`. The remaining optional session capabilities continue to represent optional features: * `session.prompt` advertises prompt content extensions beyond the baseline. * `session.mcp` advertises supported MCP server transports. * `session.delete` advertises support for deleting sessions from future `session/list` results. * `session.additionalDirectories` advertises support for extra workspace roots on supported session lifecycle requests. * `session.fork` remains an unstable optional capability while the Session Fork RFD is in progress. Agents must support `session/set_config_option` for any session where they advertise config options. ## Shiny future > How will things play out once this feature exists? Clients targeting v2 can treat `capabilities.session` as the single signal for the baseline session surface. This makes session history, reconnection, replay, and cleanup flows simpler to implement and less surprising for users. Agents that do not support sessions can still omit `capabilities.session` entirely. This preserves support for Agents that only expose non-session method surfaces. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? 1. Remove the v2 `session.load`, `session.list`, `session.resume`, and `session.close` capability fields and their generated support-marker types. 2. Update the v2 docs to describe these methods as baseline whenever `capabilities.session` is present. 3. Update the v2 overview RFD and initialization docs to call out the required session lifecycle methods. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Does this make sessions required for every v2 Agent? No. `capabilities.session` remains optional. This RFD only defines the baseline methods required once an Agent chooses to advertise the session surface. ### Why is `session/delete` still optional? `session/delete` removes a persisted session from future list results. That is a separate storage-management operation, not part of the minimal lifecycle needed. ## Revision history * 2026-07-02: Initial draft. # v2 Session Resume Replay Source: https://agentclientprotocol.com/rfds/v2/session-resume-replay Author(s): [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? ACP v2 should unify `session/load` and `session/resume` into a single `session/resume` method. Clients that need replay can set a `replayFrom` cursor on `session/resume`; clients that omit `replayFrom` get the current resume behavior without history replay. ## Status quo > How do things work today and what problems does this cause? Why would we change things? In v1, `session/load` and `session/resume` are separate methods. They restore the same existing session context, reconnect MCP servers, and accept the same workspace parameters. The main behavioral difference is replay: * `session/load` replays previous conversation history before responding. * `session/resume` restores the session without replaying previous history. Keeping both methods in v2 preserves a distinction that is better represented as an option on one restore operation. It also forces capability and transport docs to explain two methods when the client is choosing between replay modes. ## What we propose to do about it > What are you proposing to improve the situation? Remove `session/load` from the v2 method surface and keep `session/resume`. `ResumeSessionRequest` gains an optional `replayFrom` field. Omitted `replayFrom` and `replayFrom: null` are equivalent: the Agent resumes without replaying previous conversation history. The initial replay cursor is: ```json theme={null} { "type": "start" } ``` `replayFrom: { "type": "start" }` means the Agent replays all retained conversation history through `session/update` notifications before responding to the `session/resume` request. The schema accepts custom and future cursor types for preservation by intermediaries. An Agent that does not support the supplied cursor type **MUST** reject `session/resume` with `-32602` (Invalid params), rather than substituting another cursor or resuming without replay. Malformed cursors also result in `-32602`. This does not require the Agent to retain every inserted user message. Live-only or discarded messages may be absent; retained user messages must preserve the ID returned on insertion, as defined by the [Prompt Lifecycle RFD](./prompt.mdx#correlation-and-replay). Replay uses the same updates as live delivery. The Agent can send each entity's updates or only its current state, such as a terminal `output` snapshot instead of every chunk. Agents **SHOULD** preserve agent and thought message IDs, `toolCallId`, `terminalId`, and `planId` across replay when possible, but Clients cannot assume stability across reconnects or Agent restarts. Full replay should rebuild messages, tool calls, terminals, and plans rather than merge them into existing state solely by ID. The empty-content primer for chunked replay initializes or clears content only under the ID used in that replay; it does not reconcile messages previously delivered under different IDs. Replay cursors are inclusive: replay includes the position identified by the cursor. Future cursors that identify a message would replay that message before continuing with later history. ## Shiny future > How will things will play out once this feature exists? Clients always reconnect to existing sessions through `session/resume`. They choose replay behavior by setting or omitting `replayFrom`, rather than choosing between two different restore methods. This leaves room for future replay cursors, such as replaying from a specific message, checkpoint, or server-provided cursor, without adding more session restore methods. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? 1. Remove `session/load`, `LoadSessionRequest`, and `LoadSessionResponse` from the v2 schema. 2. Add `replayFrom` to `ResumeSessionRequest` as an optional tagged union. 3. Add the initial `replayFrom` variant `{ "type": "start" }`. Replay applies top-level `_meta` as a [metadata patch](./meta-patches.mdx), as live delivery does, and does not reset it. When the Client may already hold metadata for an entity, the Agent removes stale keys by setting them to `null`, or sends `_meta: null` before the current object. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Is `replayFrom` required? No. The field is optional. Omitted and `null` both mean no history replay. ### Why use an object instead of a string? An object leaves room for future cursor forms that need fields. The initial `start` form has no fields beyond `type`. ## Revision history * 2026-10-28: Replay may send current state instead of every update, and covers tool calls, terminals, and plans, not only messages. * 2026-10-13: Replay applies top-level `_meta` as a key-level patch, per [Metadata Patches](./meta-patches.mdx). * 2026-07-02: Initial draft. # v2 Terminal Output Source: https://agentclientprotocol.com/rfds/v2/terminal-output Author(s): [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? ACP v2 should provide a standard way for Agents to report display-only terminal output. A tool call can reference an Agent-owned terminal by `terminalId`, while separate session updates describe that terminal, replace its stored output for replay, append live output bytes, and report its exit status. This is a presentation surface, not a Client execution API. It does not let the Client write input, resize, interrupt, wait on, or release the Agent's process. The only control is opt-in cancellation, defined by [Background Work](./background-work.mdx): an Agent may let the Client stop a terminal's process with `terminal/cancel`. ## Status quo > How do things work today and what problems does this cause? Why would we change things? ACP v1 terminal content refers to a terminal created and owned by the Client through `terminal/create`. That ownership model does not fit Agents that execute commands in their own sandbox and only need to report the resulting output. Several implementations therefore use the v1 terminal content shape with implementation-specific `_meta` fields for terminal creation, output, and exit. This has demonstrated demand for a rich terminal display, but it leaves capability negotiation, ownership, replay, byte handling, and update ordering outside the protocol. ACP v2 removes the Client-owned terminal execution surface. It still needs a distinct, standard model for byte-faithful command output that can be streamed live and reconstructed during session replay. ## What we propose to do about it > What are you proposing to improve the situation? ### Ownership and identity The Agent owns every v2 display terminal and generates its `terminalId`. The ID is unique within a session, remains stable for the terminal's lifetime, and **MUST NOT** be reused for another terminal in that session. `terminalId` and `toolCallId` are separate domains. An Agent may choose the same underlying string for both, but Clients **MUST NOT** rely on that. ### Tool-call terminal content Add a v2 `ToolCallContent` variant that references the terminal: ```json theme={null} { "type": "terminal", "terminalId": "term_001" } ``` The content item is only a display anchor. It does not create a Client-owned process or grant the Client any control over the Agent's process. The terminal reference and terminal session updates may arrive in either order. Clients should retain state for a first-seen `terminalId` so output is not lost while its tool-call content is being received or replayed. ### Terminal state upserts Add a `terminal_update` session update: ```json theme={null} { "sessionUpdate": "terminal_update", "terminalId": "term_001", "command": "cargo test", "cwd": "/workspace/project", "size": { "cols": 120, "rows": 40 }, "output": { "data": "cnVubmluZyAxMjMgdGVzdHMNCg==" }, "exitStatus": { "exitCode": 0, "signal": null } } ``` `terminal_update` is an upsert keyed by its required `terminalId`. The first update for an unseen ID creates stored terminal state. Its other fields are patches: * An omitted field leaves its previous value unchanged. * `null` clears its previous value. * A concrete value replaces its previous value. * On a first-seen ID, omitted fields start unknown or empty. The patch fields are: * `command`: the human-readable command being run. Agents **SHOULD** include it on the first update when the terminal represents a command. It is descriptive and does not ask the Client to execute anything. * `cwd`: the command's working directory. Every supplied path **MUST** be absolute. * `size`: the terminal size the command runs with, in character cells, with required `cols` and `rows`. It is optional. When present, Clients can render output at this size so that column layouts, progress bars, and cursor-positioned output display as the program wrote them. Without it, Clients choose a size. * `output`: an authoritative replacement snapshot containing required `data`. `data` is RFC 4648 base64-encoded bytes and has JSON Schema `contentEncoding: "base64"`. A concrete snapshot is the complete byte sequence the Agent wants the Client to retain for the terminal at that point. It replaces all previously stored bytes, and Clients **MUST NOT** merge or splice bytes from the previous snapshot into it. Later chunks append to the replacement. Optional nullable `output._meta` is scoped to that snapshot; omission and `null` are equivalent and mean no snapshot metadata was provided. * `exitStatus`: a concrete object marks the terminal as exited. Its `exitCode`, `signal`, and `_meta` fields are optional and nullable; omission and `null` are equivalent and mean that value was not provided. Agents should use conventional platform signal names. POSIX examples include `SIGTERM`, `SIGKILL`, and `SIGINT`; other platforms may use platform-specific names. `exitStatus._meta` is scoped to that exit information. `exitStatus: null` clears a previously reported exit status. * The top-level `_meta` is terminal-scoped. Omission and `null` follow the same patch semantics as the other update fields, and a concrete object patches the stored metadata by top-level key, as defined by [Metadata Patches](./meta-patches.mdx). The terminal's exit status is independent of its tool call's status. Agents should update both when both states change. For example, a process terminated by a POSIX termination signal can report: ```json theme={null} { "exitStatus": { "signal": "SIGTERM" } } ``` ### Live output chunks Add a `terminal_output_chunk` session update: ```json theme={null} { "sessionUpdate": "terminal_output_chunk", "terminalId": "term_001", "data": "cGFzc2VkDQo=" } ``` `terminalId` and `data` are required. `data` is one independently RFC 4648 base64-encoded byte chunk and has JSON Schema `contentEncoding: "base64"`. Clients decode each chunk separately and append the decoded bytes in received order for that `terminalId`; they **MUST NOT** concatenate the encoded strings and decode them as one value. Chunk boundaries have no text or terminal meaning. A chunk may split a UTF-8 code point or ANSI escape sequence, so terminal emulators and transcript decoders retain parser state between chunks. `_meta`, when present, is optional chunk-scoped metadata; omission and `null` both mean no chunk metadata was provided. This initial design does not add byte offsets or sequence numbers. Replacement snapshots provide the replay, correction, and resynchronization operation, while chunks provide the efficient live append operation. ### Command permission subjects Add `type: "command"` to the v2 permission subject union: ```json theme={null} { "title": "Run the test suite?", "subject": { "type": "command", "command": "cargo test", "cwd": "/workspace/project", "toolCallId": "call_001", "terminalId": "term_001" } } ``` `command` and `cwd` are required, and `cwd` **MUST** be absolute. `toolCallId`, `terminalId`, and `_meta` are optional and nullable; omission and `null` are equivalent and mean the value was not provided. `toolCallId` and `terminalId` only associate the permission with displayed state, and either may be unavailable when permission is requested before execution begins. The command subject is a self-contained description of the proposed execution, not a `TerminalUpdate`. Reusing the update type would incorrectly give permission context patch semantics. A selected allow outcome authorizes the Agent to execute the command; it never asks the Client to execute it. ## Shiny future > How will things play out once this feature exists? Agents can stream command output once in a byte-faithful format, and Clients can choose the presentation that fits their environment. Rich IDEs can render a terminal emulator, while simpler Clients remain interoperable with a safe transcript. Session replay reconstructs the same terminal display without replaying every historical chunk, and command permissions can show the exact command and working directory without hiding them in generic tool-call input. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? 1. Add a v2 `TerminalId` and the `terminal` `ToolCallContent` variant. 2. Add `terminal_update` and `terminal_output_chunk` to the v2 `SessionUpdate` union. 3. Model terminal update fields with distinct omitted, `null`, and concrete states. 4. Add optional `_meta` to every new object payload; keep `TerminalId` as a scalar string. 5. Mark snapshot and chunk `data` as base64 bytes with JSON Schema `contentEncoding: "base64"`. 6. Add the `command` permission subject with its required command and absolute working directory plus optional associations. 7. Update v2 protocol documentation, migration guidance, generated schemas, and SDK tests. 8. Keep v1 and all Client terminal execution methods unchanged. ### Compatibility The identical-looking v1 and v2 terminal content shapes have different ownership and lifetime semantics. Generic conversion **MUST NOT** map them by wire shape alone: * A v1 terminal ID refers to a Client-created resource that the Agent can control through `terminal/*` methods. * A v2 terminal ID refers to an Agent-owned display stream with no Client control surface. A cross-version adapter must reject terminal content, v2 terminal session updates, and command permission subjects unless it implements the required stateful behavior itself. A v1-to-v2 bridge can only adapt a v1 terminal by implementing the v1 Client terminal lifecycle. A v2-to-v1 bridge may accumulate and sanitize terminal bytes into ordinary text content or use an implementation-specific extension, but it must not synthesize a v1 terminal resource it does not own. ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why use base64 instead of strings? PTY output is a byte stream. It may contain invalid UTF-8, and transport chunks may split a valid UTF-8 code point. Independently encoded byte chunks preserve the original stream without making JSON string boundaries semantically significant. The size overhead is acceptable for a correct baseline representation. ### Why have both snapshots and chunks? Repeatedly replacing the full output buffer is inefficient for live output, while an append-only stream is insufficient for replay, correction, and resynchronization. The two operations have distinct, unambiguous semantics. ### Why put `command` and `cwd` on the terminal update? They describe the terminal itself and are needed even when state arrives before its tool-call content or is replayed independently. Keeping terminal content as a small ID reference also avoids duplicating mutable state wherever the terminal is displayed. ### Why include the terminal size? Programs format output for the size of the terminal they run in: columns, truncated lines, progress bars redrawn in place, and full-screen output positioned by row and column. Without the size, a Client has to guess, and in practice picks a very wide terminal to avoid garbled wrapping, which costs memory. The size stays optional because plain line output renders fine at any width. ### Why is there no capability? Display-only terminal output has a small safe fallback: decode the bytes, sanitize control sequences, and render a transcript. A capability would only be necessary if the protocol required richer behavior such as terminal emulation or interactive control. ## Revision history * 2026-10-30: `size` is a rendering hint; Clients can render at it rather than SHOULD. * 2026-10-29: Removed the batch ordering rule, since ACP v2 no longer uses JSON-RPC batches. * 2026-10-27: Added an optional `size` with `cols` and `rows` to `terminal_update`. * 2026-10-26: Noted the opt-in `terminal/cancel` control added by [Background Work](./background-work.mdx). * 2026-10-13: A top-level `_meta` object now patches stored metadata by key, per [Metadata Patches](./meta-patches.mdx). * 2026-07-14: Initial draft. # v2 Tool Call Updates Source: https://agentclientprotocol.com/rfds/v2/tool-call-updates Author(s): [@benbrandt](https://github.com/benbrandt) ## Elevator pitch > What are you proposing to change? ACP v2 should use a single `sessionUpdate: "tool_call_update"` notification for both creating and updating tool calls. The payload is an upsert keyed by `toolCallId`: if the Client has not seen the ID before, it creates a new displayed tool call; otherwise, it patches the existing tool call. ACP v2 should also add `sessionUpdate: "tool_call_content_chunk"` for streaming discrete tool-call content items. Chunks are keyed by `toolCallId` and append one `ToolCallContent` item to the current content for that tool call. The separate [Terminal Output](./terminal-output.mdx) RFD defines byte chunks for a referenced terminal. ## Status quo > How do things work today and what problems does this cause? Why would we change things? ACP v1 has two related tool-call session updates: ```json theme={null} { "sessionUpdate": "tool_call", "toolCallId": "call_001", "title": "Reading configuration file", "kind": "read", "status": "pending" } ``` ```json theme={null} { "sessionUpdate": "tool_call_update", "toolCallId": "call_001", "status": "completed" } ``` In practice, many agents end up sending just the updates anyway, because the notifications are functionally equivalent. So, many clients already support handling just `tool_call_update` notifications if that is all they receive. There also wasn't a way to handle unsetting values, which we established with `session_info_update`. ## What we propose to do about it > What are you proposing to improve the situation? ACP v2 should remove `sessionUpdate: "tool_call"` and make `sessionUpdate: "tool_call_update"` the only tool-call session update. The v2 `ToolCallUpdate` payload has the following semantics: * `toolCallId` is required. * `name`, `title`, `kind`, `status`, `content`, `locations`, `rawInput`, and `rawOutput` are patch fields. * An omitted patch field leaves the previous value unchanged. * `null` explicitly clears or unsets the field. * Any concrete value replaces the previous value. * `content` and `locations` are replaced as whole arrays, not appended. * `[]` and `null` both clear a collection field. * `_meta` preserves omitted, `null`, and object values as distinct update signals. An object patches the stored metadata by top-level key, as defined by [Metadata Patches](./meta-patches.mdx). * For a new `toolCallId`, omitted fields start at their protocol defaults. * Agents **SHOULD** include `title` the first time they report a `toolCallId`. The `session/request_permission` method should also carry this same `ToolCallUpdate` shape for tool-call permissions. In v2, [permission requests](./permission-requests.mdx) use an optional `subject` tagged union; tool-call permissions set `subject.type: "tool_call"` and carry the update in the subject's `toolCall` field, so the permission UI receives the same patch/upsert payload shape as session updates while leaving room for future permission subjects. Permission-specific prompt text should be carried by the request's common required `title` and optional `description` fields instead of `ToolCallUpdate.title` or `ToolCallUpdate.content`. That keeps a permission prompt from accidentally replacing displayed tool-call state. ACP v2 should define a matching streaming update: * `tool_call_content_chunk` Each content chunk has the following semantics: * `toolCallId` is required. * `content` is required and contains one `ToolCallContent` item. * Clients append the chunk's `content` item to the current content for that `toolCallId`. * Clients apply `tool_call_update` and `tool_call_content_chunk` notifications in the order they are received for each `toolCallId`. * If a `tool_call_update` includes `content`, that array replaces all content currently stored for the tool call, including content accumulated from earlier chunks. * Later `tool_call_content_chunk` notifications append to the replacement content. * `content: []` or `content: null` on `tool_call_update` clears tool-call content. ## Shiny future > How will things play out once this feature exists? There is a single way to update a tool call, removing lots of confusion from how v1 operated. Agents can stream discrete content items without repeatedly resending the whole content array, while still retaining a replacement update for replay, correction, and redaction. Terminal byte streams use their terminal-specific snapshot and chunk updates. ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? 1. Remove the v2 `sessionUpdate: "tool_call"` variant from the schema. 2. Represent patch fields with a three-state type so implementations can distinguish omitted, `null`, and concrete values. 3. Add the v2 `sessionUpdate: "tool_call_content_chunk"` variant with required `toolCallId` and required single `content` item. 4. Document ordering between full replacement content on `tool_call_update` and appended content chunks. ### Compatibility This RFD doesn't define v1↔v2 conversions. Implementations that bridge versions follow the migration guide's advice on [adapters](/protocol/v2/migration#share-application-logic-not-wire-shapes). ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? ### Why keep the `tool_call_update` name instead of `tool_call`? Most of the other notification names end in "update", and this was by far the most used, so it should help with the migration hopefully. ### Why make `null` different from omission? Tool-call updates need both operations. Omission means "I am not changing this field"; `null` means "clear the value." Without the distinction, Agents cannot unset a previously supplied field without resending a full replacement object. ### Why add chunks instead of making `tool_call_update.content` append? `tool_call_update.content` needs replacement semantics for replay, correction, and redaction. A separate chunk variant gives streaming a distinct append operation without making replacement updates ambiguous. `tool_call_content_chunk` appends a complete `ToolCallContent` item. It is not the byte-streaming operation for terminal output; terminals use `terminal_output_chunk` so arbitrary byte boundaries do not create many content items. ## Revision history * 2026-10-29: Omitted fields on a new entity start at protocol defaults, not Client defaults. * 2026-10-13: A top-level `_meta` object now patches stored metadata by key, per [Metadata Patches](./meta-patches.mdx). * 2026-07-14: Distinguished tool-call content item chunks from terminal byte-stream chunks. * 2026-07-02: Updated permission requests to carry tool-call updates through an optional `subject` tagged union and to use separate `title` and `description` fields for permission-specific prompt text. * 2026-06-09: Added `tool_call_content_chunk` for streaming tool-call content. * 2026-06-08: Initial draft # Updates Source: https://agentclientprotocol.com/updates Updates and announcements about the Agent Client Protocol This page is for larger ACP announcements and project updates. For lifecycle changes to Requests for Dialog, see [RFD Updates](/rfds/updates). **November 6, 2026** ## Client-Provided System Prompts are Stabilized The Client-Provided System Prompt RFD has moved to Completed, and `systemPrompt` on session setup is now stabilized in ACP v1 and v2. Agents that advertise `systemPrompt` accept system-level instructions in `append` mode. Agents that also advertise `mode.override` let Clients replace their built-in default instructions. [Read the full announcement](/announcements/client-system-prompt-stabilized). **September 17, 2026** ## Tool Call Names are Stabilized The Tool Call Name RFD has moved to Completed, and optional programmatic names for tool calls are now stabilized in ACP v1 and the v2 baseline. Agents can identify the invoked tool separately from its human-readable title without introducing capability or authorization semantics. [Read the full announcement](/announcements/tool-call-name-stabilized). **July 22, 2026** ## Elicitation is Stabilized The Elicitation RFD has moved to Completed, and structured form and URL-mode user interactions are now stabilized in ACP. Agents can request structured non-sensitive input or direct users to secure out-of-band flows, while Clients explicitly advertise the modes they support. [Read the full announcement](/announcements/elicitation-stabilized). **July 20, 2026** ## ACP v2 is Available in Draft The ACP v2 protocol documentation and schema are now published in Draft form. [Read the full announcement](/announcements/acp-v2-draft). **July 6, 2026** ## Boolean Config Options are Stabilized The Boolean Config Option Type RFD has moved to Completed and boolean session configuration options are stabilized. Agents can now expose native on/off controls, while v1 clients explicitly opt in through the `session.configOptions.boolean` capability. [Read the full announcement](/announcements/boolean-config-option-stabilized). **June 29, 2026** ## Request Cancellation is Stabilized The Request Cancellation RFD has moved to Completed and the `$/cancel_request` notification is stabilized. Either side can now request cancellation of an outstanding JSON-RPC request by ID without relying on method-specific cancellation. [Read the full announcement](/announcements/request-cancellation-stabilized). **June 25, 2026** ## Rust and TypeScript SDKs Reach 1.0 The Rust SDK based on SACP RFD has moved to Completed after both the Rust and TypeScript ACP SDKs reached version 1.0.0. The releases provide stable foundations for building ACP clients, agents, and protocol adapters in both ecosystems. [Read the full announcement](/announcements/sdk-1-0-releases). **June 24, 2026** ## Model Config Category is Stabilized The Model Config Option Category RFD has moved to Completed and the `model_config` category is stabilized. Agents can classify model-related parameters such as context size or speed and quality trade-offs so clients can present them alongside the main model selector. [Read the full announcement](/announcements/model-config-category-stabilized). **June 5, 2026** ## Message IDs are Stabilized The Message ID RFD has moved to Completed and optional Agent-generated `messageId` fields are stabilized in ACP v1. Message IDs let clients group streamed chunks into individual messages and detect when a new message begins. [Read the full announcement](/announcements/message-id-stabilized). **June 5, 2026** ## Session Usage Updates are Stabilized The Session Context Size and Cost RFD has moved to Completed and `usage_update` session notifications are stabilized. Agents can now report current context-window utilization and optional cumulative session cost so clients can keep usage displays up to date. [Read the full announcement](/announcements/session-usage-stabilized). **June 5, 2026** ## Session Delete is Stabilized The Session Delete RFD has moved to Completed and the `session/delete` method is stabilized. This gives users a standard way to remove sessions from session history while leaving storage and retention policy to the Agent. [Read the full announcement](/announcements/session-delete-stabilized). **June 1, 2026** ## Additional Workspace Roots are Stabilized The Additional Workspace Roots RFD has moved to Completed and `additionalDirectories` is stabilized for session lifecycle requests. Clients can declare absolute additional workspace roots while `cwd` remains the primary working directory. [Read the full announcement](/announcements/additional-directories-stabilized). **May 21, 2026** ## Logout Method is Stabilized The Logout Method RFD has moved to Completed and the `logout` method is stabilized. This gives clients a standard way to end an authenticated state and let users authenticate again without restarting the ACP connection. [Read the full announcement](/announcements/logout-method-stabilized). **April 23, 2026** ## Session Close is Stabilized The Session Close RFD has moved to Completed and the `session/close` method is stabilized. This gives clients a way to tell agents to cancel in-flight work for a session and free the resources tied to it without tearing down the whole ACP process. [Read the full announcement](/announcements/session-close-stabilized). **April 22, 2026** ## Session Resume is Stabilized The Session Resume RFD has moved to Completed and the `session/resume` method is stabilized. This gives clients a way to reconnect to an existing session without replaying conversation history, and lets proxies and adapters build `session/load` semantics on top of the simpler primitive. [Read the full announcement](/announcements/session-resume-stabilized). **April 22, 2026** ## Transports Working Group A new Transports Working Group has been formed to standardize remote agent transports like WebSockets and HTTP. Anna Zhdan (JetBrains / Core Maintainer) and Alex Hancock (Block / Goose) are leading the effort, with a Draft RFD already underway. [Read the full announcement](/announcements/transports-working-group). **March 9, 2026** ## ACP Registry is Released The ACP Registry RFD has moved to Completed and the initial version of the registry is released. The registry gives ACP clients a standard way to discover, install, and configure compatible agents without inventing custom integration metadata. [Read the full announcement](/announcements/acp-agent-registry-stabilized). **March 9, 2026** ## Session Info Update is Stabilized The Session Info Update RFD has moved to Completed and the session\_info\_update notification is stabilized. This lets agents push session metadata updates to clients in real time so titles and related metadata stay current without polling. [Read the full announcement](/announcements/session-info-update-stabilized). **March 9, 2026** ## Session List is Stabilized The Session List RFD has moved to Completed and the session/list method is stabilized. This gives clients a standard way to discover existing sessions from an agent for features like history, switching, and cleanup. [Read the full announcement](/announcements/session-list-stabilized). **February 18, 2026** ## Sergey Ignatov joins ACP as Lead Maintainer Sergey Ignatov from JetBrains is now a Lead Maintainer for ACP. This reflects the growing collaboration between Zed and JetBrains around ACP and recognizes Sergey’s significant contributions to the protocol. [Read the full announcement](/announcements/sergey-ignatov-lead-maintainer). **February 4, 2026** ## Session Config Options are now Stabilized The Session Config Options RFD has moved to Completed and is stabilized. This gives agents a flexible way to expose session-level configuration such as models, modes, reasoning levels, and other selectors. [Read the full announcement](/announcements/session-config-options-stabilized). **October 24, 2025** ## Implementation information for agents and clients ACP now allows agents and clients to share implementation details during initialization using the optional clientInfo and agentInfo fields. This makes it easier to identify which implementation is running, improve compatibility diagnostics, and understand adoption across the ecosystem. [Read the full announcement](/announcements/implementation-information).