> ## Documentation Index
> Fetch the complete documentation index at: https://zed-685ed6d6-auto-sync-registry.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 advisory
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 an advisory presentation event. 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 advisory 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 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.
* Generated unstable schemas and draft protocol guides include the feature.
  See the [v1 guide](/protocol/v1/draft/prompt-turn#session-notices) and
  [v2 guide](/protocol/v2/draft/prompt-lifecycle#session-notices).

The feature remains behind `unstable_session_notices` and is not included in
the stable schemas. Preview does not stabilize the wire contract. The schema
crate intentionally provides no built-in v1/v2 conversion layer.

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 advisory 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 advisory 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-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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.