RFD: Agent-to-Client Logging

[chazcb]

Summary

This RFD proposes a capability-gated log notification (agent → client) so agents can share diagnostic messages without polluting conversation history.

Key features

• Capability-gated: Clients opt in via clientCapabilities.logging; agents only send logs to clients that declare the capability
• Level filtering: Clients can specify minimum log level (default: info)
• Optional sessionId: Connection-wide if absent, session-specific if present
• RFC 5424 severity levels: debug, info, notice, warning, error, critical, alert, emergency
• Optional fields: logger name, timestamp, structured data

Problem

Today, agents have limited ways to inform clients about status that might impact their experience:

• JSON-RPC errors: Terminate the request immediately (can't use for non-fatal conditions)
• session/update: Puts diagnostics in chat history (not appropriate for transient status)

Neither works when:

• There's no active JSON RPC request to attach an error response to
• We don't want to fail the request (e.g., retries, rate limiting, fallback selection)
• There's no session yet (diagnostics after initialize but before session/new)
• We don't want to put diagnostics in chat history

Example

{
  "jsonrpc": "2.0",
  "method": "log",
  "params": {
    "level": "warning",
    "message": "Backing model rate limited, retrying in 5 seconds...",
    "sessionId": "abc-123",
    "logger": "model",
    "timestamp": "2025-01-21T10:30:00Z",
    "data": { "model": "claude-3", "retryIn": 5 }
  }
}

Capability negotiation

{
  "method": "initialize",
  "params": {
    "clientCapabilities": {
      "logging": {
        "level": "warning"
      }
    }
  }
}

🤖 Generated with Claude Code

[benbrandt]

See my notes on status vs logging.

I think I am trying to better understand the motivating use case. In my mind, I think we would want a more semantically meaningful status update if these will be user-facing within the main UI.

However, given that we are moving more things to remote scenarios, what this seems to show me is a way for a client to subscribe to the equivalent of stderr with a filter? Which could be helpful in debug scenarios where you need to look at the logs from the client side and don't have the luxury of having access to stderr as you would from a local process.

If we are targeting the latter, then I think this could definitely provide some value. I just think (speaking from Zed) we would likely relegate this to our ACP log/debug views that the user pulls up on-demand rather than utilize them within the main UI to avoid overly noisy logs (even with WARN/ERROR it is unclear that these should always be surfaced based on the semantics, as with many logs, they serve a different purpose potentially than a UI facing status update).

Curious to get your thoughts on all of this, and if I am completely missing the purpose of what you are proposing here.

[benbrandt]

I was going to say as a notification we could just add this, but having some sort of filter totally makes sense here.

Another option would be the default filter level is "error" and the client can opt-in to allowing more?

This also gives me some pause as it feels like we are mixing configuration with capabilities, so I wonder if this needs to live somewhere else, but just a gut reaction

[chazcb]

Hmm, agree on mixing config and capabilities. At the same time, I don't like needing to add new methods for setting logging levels, especially when you want to init a session with a specific logging level.

For our debug logging, it's important that we can get logs immediately after initialization. Other ways to accomplish that:

1. New "setLogLevel" method that can be called prior to initialization
2. New field on "params" for initialize that opts the client into logging with a specific configuration (the theory being that this is not a client "capability")
3. Or finally, if the client specifies "logging" in client capabilities, then we default to sending all log levels (for now).

Thoughts on those options?

[benbrandt]

Makes sense. I do feel like this more structured status would be super helpful, but understand that you are trying to get at a different use case here.

I think the clients would benefit a lot from these more interactive status messages, but you are proposing something else here

[chazcb]

Yeah this proposal is really about debug and / or error logging, specifically for developers trying to get a better sense of why something went wrong or what is happening under the hood. I would imagine some UIs might provide the "show logs" pane so end users can also debug, but this is really about getting the info to the client and not about structuring dynamic UIs.

[benbrandt]

Cool yeah then we are aligned here. Basically allows a client to offer some sort of log UI

It does now beg the question for me though 😄 :
Do we want a way for a client to be able to change the requested log-level while the connection is active? I could see it being helpful to adjust this after you have already connected, but we can also say the user needs to specify/configure this beforehand

[benbrandt]

(this can totally be a "we do this later" thing, just a thought I had)

[benbrandt]

Regarding this: I think for clients to give a meaningful, user-facing status update, we may want to go with the more structured status approach? With the current proposal, speaking from the client perspective, I don't know that we would surface these as they would potentially be too noisy/unpredictable.

[chazcb]

Agree this should get removed from proposal language and proposal should focus more around logging for client visibility into internals, rather than for UIs.

[benbrandt]

Perfect thanks!