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