Add diagnostics/read capability for reading LSP diagnostics

[nojaf]

Motivation

Code editors typically run language servers (LSP) that produce diagnostics: errors, warnings, and other feedback from compilers, linters, and type checkers. These diagnostics are a valuable signal for coding agents, especially after making edits, to determine whether changes introduced new errors or to help users fix existing ones.

Currently, ACP has no mechanism for agents to access editor diagnostics. Agents that run inside the editor (e.g. Zed's built-in agent) can access diagnostics directly through internal APIs, but external agents connected via ACP cannot. This creates a capability gap between internal and external agents.

An external agent's workarounds today are limited and suboptimal:

• Running the compiler/linter via a terminal tool (slow, requires knowing the build system, may not match the editor's LSP configuration)
• Not having access to diagnostics at all

Proposal

Add a new diagnostics/read client method and a corresponding diagnostics capability on ClientCapabilities.

Client Capability

"ClientCapabilities": {
  "properties": {
    "diagnostics": {
      "allOf": [{"$ref": "#/$defs/DiagnosticsCapability"}],
      "default": {"read": false}
    }
  }
}

"DiagnosticsCapability": {
  "description": "Diagnostics capabilities supported by the client.",
  "properties": {
    "_meta": {
      "additionalProperties": true,
      "type": ["object", "null"]
    },
    "read": {
      "default": false,
      "description": "Whether the client supports diagnostics/read requests.",
      "type": "boolean"
    }
  },
  "type": "object"
}

Request

"ReadDiagnosticsRequest": {
  "description": "Request to read diagnostics (errors, warnings) from the editor's language services.",
  "properties": {
    "_meta": {
      "additionalProperties": true,
      "type": ["object", "null"]
    },
    "sessionId": {
      "$ref": "#/$defs/SessionId",
      "description": "The session ID for this request."
    },
    "path": {
      "description": "Absolute path to a specific file. If omitted, returns a project-wide summary.",
      "type": ["string", "null"]
    },
    "severity": {
      "description": "Filter by minimum severity. Defaults to returning errors and warnings.",
      "enum": ["error", "warning", "information", "hint"],
      "type": ["string", "null"]
    }
  },
  "required": ["sessionId"],
  "type": "object",
  "x-method": "diagnostics/read",
  "x-side": "client"
}

Response

"ReadDiagnosticsResponse": {
  "description": "Response containing diagnostics from the editor's language services.",
  "properties": {
    "_meta": {
      "additionalProperties": true,
      "type": ["object", "null"]
    },
    "diagnostics": {
      "description": "List of diagnostics. When a path was specified, these are the diagnostics for that file. When no path was specified, these are summary counts per file.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/Diagnostic"
      }
    }
  },
  "required": ["diagnostics"],
  "type": "object",
  "x-method": "diagnostics/read",
  "x-side": "client"
}

"Diagnostic": {
  "description": "A single diagnostic from the editor's language services.",
  "properties": {
    "path": {
      "description": "Absolute path to the file.",
      "type": "string"
    },
    "line": {
      "description": "1-based line number where the diagnostic starts.",
      "format": "uint32",
      "minimum": 1,
      "type": ["integer", "null"]
    },
    "endLine": {
      "description": "1-based line number where the diagnostic ends.",
      "format": "uint32",
      "minimum": 1,
      "type": ["integer", "null"]
    },
    "severity": {
      "description": "Severity level of the diagnostic.",
      "enum": ["error", "warning", "information", "hint"],
      "type": "string"
    },
    "message": {
      "description": "The diagnostic message.",
      "type": "string"
    },
    "source": {
      "description": "The source of the diagnostic (e.g. 'rustc', 'eslint', 'typescript').",
      "type": ["string", "null"]
    },
    "code": {
      "description": "A diagnostic code from the source (e.g. 'E0308', 'no-unused-vars').",
      "type": ["string", "null"]
    }
  },
  "required": ["path", "severity", "message"],
  "type": "object"
}

Use cases

1. Post-edit validation: After an agent makes code changes, it calls diagnostics/read on the edited file to check whether new errors were introduced.
2. Fix diagnostics workflow: User asks "fix the errors in my project". Agent calls diagnostics/read with no path to get the summary, then reads specific files to get details and fix them.
3. Iterative repair: Agent edits a file, checks diagnostics, makes corrections, re-checks - a tight feedback loop without needing to invoke build tools through a terminal.

Design considerations

• Follows existing patterns: The capability/request/response structure mirrors fs/read_text_file exactly.
• Graceful degradation: Agents can check ClientCapabilities.diagnostics.read and fall back to terminal-based compilation if the client doesn't support it.
• Summary vs detail: When no path is given, clients can return per-file summary counts (error/warning counts). When a path is given, clients return individual diagnostics with locations. This matches how editors typically organize diagnostic information.
• Severity filter: The optional severity field lets agents request only errors (skipping warnings/hints) when that's all they care about.

[nojaf]

Hi @benbrandt and @PsiACE, sorry for the direct ping.

I noticed that my discussion (#495) doesn’t appear in the Protocol Suggestions overview:

https://github.com/orgs/agentclientprotocol/discussions/categories/protocol-suggestions

It has gathered 27 upvotes, so I just wanted to make sure it’s actually on your radar. Could you check whether it’s correctly categorised or if there’s something I should adjust?

Thanks!