perf: improve Java LSP tool result handoff

package.json

@@ -52,7 +52,7 @@
       {
         "name": "lsp_java_getFileStructure",
         "toolReferenceName": "javaFileStructure",
-        "modelDescription": "Get a known Java file's outline: classes, interfaces, methods, fields, symbol kinds, and line ranges, to pick a precise read_file range instead of reading the whole file.\n\nUse after lsp_java_findSymbol returns a file, or when the user gave a Java file path; do not guess paths. Not for workspace-wide search\u2014use lsp_java_findSymbol for that. Do not re-call for the same file unless the first result was empty.",
+        "modelDescription": "Get a known Java file's outline: classes, interfaces, methods, fields, symbol kinds, and line ranges, to pick a precise read_file range instead of reading the whole file.\n\nUse when the user gave a Java file path or lsp_java_findSymbol returned a file and broader file context is needed; do not guess paths. Not for workspace-wide search\u2014use lsp_java_findSymbol for that. Do not re-call for the same file unless the first result was empty.",
         "displayName": "Java: Get File Structure",
         "userDescription": "Get a Java file outline with classes, methods, fields, and line ranges.",
         "tags": [
@@ -69,7 +69,7 @@
           "properties": {
             "uri": {
               "type": "string",
-              "description": "Workspace-relative path to a Java file. Must be a known path from prior tool results or user input — do not guess."
+              "description": "Workspace-relative path to a Java file. Prefer file returned by lsp_java_findSymbol. Must be a known path from prior tool results or user input — do not guess."
             }
           },
           "required": [
@@ -80,7 +80,7 @@
       {
         "name": "lsp_java_findSymbol",
         "toolReferenceName": "javaFindSymbol",
-        "modelDescription": "Find Java class, interface, method, or field definitions across the workspace by name or partial identifier. Prefer over grep_search, file_search, semantic_search, or search subagents for Java symbol lookup.\n\nOn relevant results, do not repeat with a similar query; continue with lsp_java_getFileStructure or read_file on the returned line range. The tool retries internally, so on an empty result do not re-search\u2014retry once only if it reports indexing in progress, otherwise use generic search.\n\nDo not use for non-Java files, literals, comments, build/XML files, or conceptual exploration.",
+        "modelDescription": "Find Java class, interface, method, or field definitions across the workspace by name or partial identifier. Prefer over grep_search, file_search, semantic_search, or search subagents for Java symbol lookup.\n\nResults include file, startLine, endLine, range, and readFileInput ({ filePath, offset, limit }) compatible with read_file. On relevant results, use read_file with readFileInput when source is needed, or lsp_java_getFileStructure with the returned file when broader file context is needed. The tool retries internally, so on an empty result do not re-search\u2014retry once only if it reports indexing in progress, otherwise use generic search.\n\nDo not use for non-Java files, literals, comments, build/XML files, or conceptual exploration.",
         "displayName": "Java: Find Symbol",
         "userDescription": "Find Java class, method, field, or interface definitions by name.",
         "tags": [

resources/instruments/javaLspContext.instructions.md

@@ -10,6 +10,6 @@ For Java symbol navigation, two compiler-accurate `lsp_java_*` tools are availab
 
 If these tools are not already available in the current tool list, load them with `tool_search` using a query such as `Java LSP symbol navigation lsp_java`.
 
-Use `lsp_java_findSymbol` before `grep_search`, `search_subagent`, `semantic_search`, or `file_search` only when the task is to locate Java symbols by name or partial identifier. If it returns relevant symbols, do not call it again with the same or similar query; next use `lsp_java_getFileStructure` for the returned file or `read_file` on the smallest useful line range.
+Use `lsp_java_findSymbol` before `grep_search`, `search_subagent`, `semantic_search`, or `file_search` only when the task is to locate Java symbols by name or partial identifier. If it returns relevant symbols and source is needed, call `read_file` with the returned `readFileInput`, or call `lsp_java_getFileStructure` with the returned `file` when broader file context is needed.
 
-Use `lsp_java_getFileStructure` only with a path confirmed by the user or a previous tool result. Do not guess paths. Use generic search for string literals, comments, XML, Gradle/Maven files, non-Java files, or broad conceptual exploration. `findSymbol` already retries internally with a normalized identifier, so do not re-issue the same search on an empty result: if it reports indexing in progress, retry once after a short pause; otherwise fall back to generic search.
+Use `lsp_java_getFileStructure` only with a path confirmed by the user or a previous tool result. Prefer `file` from `findSymbol`; do not guess paths. Use generic search for string literals, comments, XML, Gradle/Maven files, non-Java files, or broad conceptual exploration. `findSymbol` already retries internally with a normalized identifier, so do not re-issue the same search on an empty result: if it reports indexing in progress, retry once after a short pause; otherwise fall back to generic search.

resources/skills/java-lsp-tools/SKILL.md

@@ -12,13 +12,13 @@ Two compiler-accurate tools backed by the Java Language Server (jdtls). They ret
 ### `lsp_java_findSymbol`
 Search for Java symbol definitions (classes, methods, fields) by name across the workspace. Supports partial matching.
 - Input: `{ query, limit? }` — limit defaults to 20, max 50
-- Output: `{ results: [{ name, kind, container?, location, range }], total }` (~60 tokens); `range` is `L start-end`
+- Output: `{ results: [{ name, kind, container?, file, startLine, endLine, readFileInput, location, range }], total }`; `readFileInput` is `{ filePath, offset, limit }` for `read_file`, and `file` can be passed to `lsp_java_getFileStructure`
 - **Use instead of** `grep_search`, `file_search`, `semantic_search`, or `search_subagent` when looking for where a Java class/method/field is defined by identifier
-- Do not repeat with the same or similar query after relevant results are returned
+- When source is needed for a returned symbol, use its `readFileInput` directly
 
 ### `lsp_java_getFileStructure`
 Get hierarchical outline of a Java file (classes, methods, fields) with line ranges.
-- Input: `{ uri }` — workspace-relative path. Must be a known path from prior tool results or user input — do not guess
+- Input: `{ uri }` — workspace-relative path. Prefer `file` from `lsp_java_findSymbol`. Must be a known path from prior tool results or user input — do not guess
 - Output: symbol tree with `L start-end` ranges (~100 tokens)
 - **Use before** `read_file` when you need to choose a precise line range in a known Java file
 
@@ -36,7 +36,7 @@ Get hierarchical outline of a Java file (classes, methods, fields) with line ran
 
 **findSymbol → getFileStructure → read_file (specific lines only)**
 
-If `findSymbol` returns relevant symbols, move forward to `getFileStructure` or `read_file`; do not call `findSymbol` again with the same or similar identifier.
+If `findSymbol` returns relevant symbols and source is needed, call `read_file` with the returned `readFileInput`, or call `getFileStructure` with the returned `file` when broader file context is needed.
 
 ## Fallback
 

src/copilot/tools/javaContextTools.ts

@@ -44,6 +44,28 @@ function getResponseCharCount(data: unknown): number {
     return typeof data === "string" ? data.length : JSON.stringify(data, null, 2).length;
 }
 
+interface ReadFileInput {
+    filePath: string;
+    offset: number;
+    limit: number;
+}
+
+function toInclusiveLineRange(range: vscode.Range): { startLine: number; endLine: number } {
+    const startLine = range.start.line + 1;
+    const endLine = Math.max(startLine, range.end.character === 0 && range.end.line > range.start.line
+        ? range.end.line
+        : range.end.line + 1);
+    return { startLine, endLine };
+}
+
+function toReadFileInput(filePath: string, startLine: number, endLine: number): ReadFileInput {
+    return {
+        filePath,
+        offset: startLine,
+        limit: endLine - startLine + 1,
+    };
+}
+
 /**
  * Normalize a workspace-symbol query for a single fallback retry.
  * Strips a fully-qualified package prefix (com.foo.Bar -> Bar), generic parameters
@@ -86,7 +108,8 @@ function getToolErrorCode(error: unknown): string {
  *   - Relative path:  "src/main/java/Main.java"
  *   - Absolute path:  "/home/user/project/src/Main.java" or "C:\\Users\\...\\Main.java"
  *
- * Relative paths are resolved against the first workspace folder.
+ * Relative paths are resolved against the first workspace folder unless they
+ * start with a workspace folder name in a multi-root workspace.
  * The resolved URI must use the file: scheme and fall under a workspace folder.
  */
 function resolveFileUri(input: string): vscode.Uri {
@@ -96,19 +119,31 @@ function resolveFileUri(input: string): vscode.Uri {
     }
 
     let uri: vscode.Uri;
+    const normalizedInput = input.trim();
 
-    if (input.includes("://")) {
+    if (normalizedInput.includes("://")) {
         // URI string (e.g. "file:///home/user/project/src/Main.java")
-        uri = vscode.Uri.parse(input);
+        uri = vscode.Uri.parse(normalizedInput);
         if (uri.scheme !== "file") {
             throw new Error(`Unsupported URI scheme "${uri.scheme}". Only file: URIs are allowed.`);
         }
-    } else if (path.isAbsolute(input)) {
+    } else if (path.isAbsolute(normalizedInput)) {
         // Absolute filesystem path (Unix or Windows)
-        uri = vscode.Uri.file(input);
+        uri = vscode.Uri.file(normalizedInput);
     } else {
-        // Relative path — resolve against first workspace folder
-        uri = vscode.Uri.joinPath(folders[0].uri, input);
+        // Relative path — resolve against a matching workspace folder when
+        // asRelativePath included the folder name, otherwise use the first root.
+        const normalizedRelativePath = normalizedInput.replace(/\\/g, "/");
+        const matchingFolder = folders.find(folder =>
+            normalizedRelativePath === folder.name || normalizedRelativePath.startsWith(`${folder.name}/`));
+        if (matchingFolder) {
+            const pathInFolder = normalizedRelativePath === matchingFolder.name
+                ? ""
+                : normalizedRelativePath.substring(matchingFolder.name.length + 1);
+            uri = vscode.Uri.joinPath(matchingFolder.uri, pathInFolder);
+        } else {
+            uri = vscode.Uri.joinPath(folders[0].uri, normalizedRelativePath);
+        }
     }
 
     // Ensure the resolved path is under a workspace folder
@@ -288,13 +323,21 @@ const findSymbolTool: vscode.LanguageModelTool<FindSymbolInput> = {
                 return toResult(noMatchesPayload);
             }
             totalResults = symbols.length;
-            const results = symbols.slice(0, limit).map(s => ({
-                name: s.name,
-                kind: vscode.SymbolKind[s.kind],
-                container: s.containerName || undefined,
-                location: `${vscode.workspace.asRelativePath(s.location.uri)}:${s.location.range.start.line + 1}`,
-                range: `L${s.location.range.start.line + 1}-${s.location.range.end.line + 1}`,
-            }));
+            const results = symbols.slice(0, limit).map(s => {
+                const file = vscode.workspace.asRelativePath(s.location.uri);
+                const { startLine, endLine } = toInclusiveLineRange(s.location.range);
+                return {
+                    name: s.name,
+                    kind: vscode.SymbolKind[s.kind],
+                    container: s.containerName || undefined,
+                    file,
+                    startLine,
+                    endLine,
+                    readFileInput: toReadFileInput(file, startLine, endLine),
+                    location: `${file}:${startLine}`,
+                    range: `L${startLine}-${endLine}`,
+                };
+            });
             resultCount = results.length;
             const findSymbolPayload = { results, total: symbols.length };
             responseCharCount = getResponseCharCount(findSymbolPayload);