feat: 工具层及 mcp 大重构 (#252)

* feat: 第一版大重构

* fix: 修复类型问题

* chore: 更新版本到 1.3.2

* Add brave as alternative WebSearchTool

* fix: 修正顺序

* fix: 修复对穷鬼模式的 auto dream 和 session memory 越过

* feat: 穷鬼模式去除 session-summary

* feat: 创建 builtin-tools 包，搬运所有工具实现

将 src/tools/ 下的全部 60 个工具目录迁移至 packages/builtin-tools/src/tools/，
内部导入路径已更新为 src/ alias 模式。

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor: 更新 src/ 中所有工具引用至 builtin-tools 包，删除 src/tools/

- src/tools.ts 及 178 个 src/ 文件的 import 路径从 ./tools/ 改为 builtin-tools/tools/
- 删除 src/tools/ 整个目录（已迁移至 packages/builtin-tools/）

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: 添加 builtin-tools 路径别名至 tsconfig，更新 bun.lock

- tsconfig.json 新增 builtin-tools/* 和 builtin-tools 路径映射
- 新增 packages/builtin-tools/src 至 include

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor: 为 builtin-tools、mcp-client、agent-tools 添加 @claude-code-best 作用域前缀

所有包名及 import 路径统一添加 @claude-code-best/ 前缀：
- builtin-tools → @claude-code-best/builtin-tools
- mcp-client → @claude-code-best/mcp-client
- agent-tools → @claude-code-best/agent-tools

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: 修复 node 环境没有 bun 的问题

---------

Co-authored-by: Eric-Guo <eric.guocz@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

packages/builtin-tools/src/tools/LSPTool/LSPTool.ts

@@ -0,0 +1,860 @@
+import { open } from 'fs/promises'
+import * as path from 'path'
+import { pathToFileURL } from 'url'
+import type {
+  CallHierarchyIncomingCall,
+  CallHierarchyItem,
+  CallHierarchyOutgoingCall,
+  DocumentSymbol,
+  Hover,
+  Location,
+  LocationLink,
+  SymbolInformation,
+} from 'vscode-languageserver-types'
+import { z } from 'zod/v4'
+import {
+  getInitializationStatus,
+  getLspServerManager,
+  isLspConnected,
+  waitForInitialization,
+} from 'src/services/lsp/manager.js'
+import type { ValidationResult } from 'src/Tool.js'
+import { buildTool, type ToolDef } from 'src/Tool.js'
+import { uniq } from 'src/utils/array.js'
+import { getCwd } from 'src/utils/cwd.js'
+import { logForDebugging } from 'src/utils/debug.js'
+import { isENOENT, toError } from 'src/utils/errors.js'
+import { execFileNoThrowWithCwd } from 'src/utils/execFileNoThrow.js'
+import { getFsImplementation } from 'src/utils/fsOperations.js'
+import { lazySchema } from 'src/utils/lazySchema.js'
+import { logError } from 'src/utils/log.js'
+import { expandPath } from 'src/utils/path.js'
+import { checkReadPermissionForTool } from 'src/utils/permissions/filesystem.js'
+import type { PermissionDecision } from 'src/utils/permissions/PermissionResult.js'
+import {
+  formatDocumentSymbolResult,
+  formatFindReferencesResult,
+  formatGoToDefinitionResult,
+  formatHoverResult,
+  formatIncomingCallsResult,
+  formatOutgoingCallsResult,
+  formatPrepareCallHierarchyResult,
+  formatWorkspaceSymbolResult,
+} from './formatters.js'
+import { DESCRIPTION, LSP_TOOL_NAME } from './prompt.js'
+import { lspToolInputSchema } from './schemas.js'
+import {
+  renderToolResultMessage,
+  renderToolUseErrorMessage,
+  renderToolUseMessage,
+  userFacingName,
+} from './UI.js'
+
+const MAX_LSP_FILE_SIZE_BYTES = 10_000_000
+
+/**
+ * Tool-compatible input schema (regular ZodObject instead of discriminated union)
+ * We validate against the discriminated union in validateInput for better error messages
+ */
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    operation: z
+      .enum([
+        'goToDefinition',
+        'findReferences',
+        'hover',
+        'documentSymbol',
+        'workspaceSymbol',
+        'goToImplementation',
+        'prepareCallHierarchy',
+        'incomingCalls',
+        'outgoingCalls',
+      ])
+      .describe('The LSP operation to perform'),
+    filePath: z.string().describe('The absolute or relative path to the file'),
+    line: z
+      .number()
+      .int()
+      .positive()
+      .describe('The line number (1-based, as shown in editors)'),
+    character: z
+      .number()
+      .int()
+      .positive()
+      .describe('The character offset (1-based, as shown in editors)'),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    operation: z
+      .enum([
+        'goToDefinition',
+        'findReferences',
+        'hover',
+        'documentSymbol',
+        'workspaceSymbol',
+        'goToImplementation',
+        'prepareCallHierarchy',
+        'incomingCalls',
+        'outgoingCalls',
+      ])
+      .describe('The LSP operation that was performed'),
+    result: z.string().describe('The formatted result of the LSP operation'),
+    filePath: z
+      .string()
+      .describe('The file path the operation was performed on'),
+    resultCount: z
+      .number()
+      .int()
+      .nonnegative()
+      .optional()
+      .describe('Number of results (definitions, references, symbols)'),
+    fileCount: z
+      .number()
+      .int()
+      .nonnegative()
+      .optional()
+      .describe('Number of files containing results'),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+
+export type Output = z.infer<OutputSchema>
+export type Input = z.infer<InputSchema>
+
+export const LSPTool = buildTool({
+  name: LSP_TOOL_NAME,
+  searchHint: 'code intelligence (definitions, references, symbols, hover)',
+  maxResultSizeChars: 100_000,
+  isLsp: true,
+  async description() {
+    return DESCRIPTION
+  },
+  userFacingName,
+  shouldDefer: true,
+  isEnabled() {
+    return isLspConnected()
+  },
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return true
+  },
+  getPath({ filePath }): string {
+    return expandPath(filePath)
+  },
+  async validateInput(input: Input): Promise<ValidationResult> {
+    // First validate against the discriminated union for better type safety
+    const parseResult = lspToolInputSchema().safeParse(input)
+    if (!parseResult.success) {
+      return {
+        result: false,
+        message: `Invalid input: ${parseResult.error.message}`,
+        errorCode: 3,
+      }
+    }
+
+    // Validate file exists and is a regular file
+    const fs = getFsImplementation()
+    const absolutePath = expandPath(input.filePath)
+
+    // SECURITY: Skip filesystem operations for UNC paths to prevent NTLM credential leaks.
+    if (absolutePath.startsWith('\\\\') || absolutePath.startsWith('//')) {
+      return { result: true }
+    }
+
+    let stats
+    try {
+      stats = await fs.stat(absolutePath)
+    } catch (error) {
+      if (isENOENT(error)) {
+        return {
+          result: false,
+          message: `File does not exist: ${input.filePath}`,
+          errorCode: 1,
+        }
+      }
+      const err = toError(error)
+      // Log filesystem access errors for tracking
+      logError(
+        new Error(
+          `Failed to access file stats for LSP operation on ${input.filePath}: ${err.message}`,
+        ),
+      )
+      return {
+        result: false,
+        message: `Cannot access file: ${input.filePath}. ${err.message}`,
+        errorCode: 4,
+      }
+    }
+
+    if (!stats.isFile()) {
+      return {
+        result: false,
+        message: `Path is not a file: ${input.filePath}`,
+        errorCode: 2,
+      }
+    }
+
+    return { result: true }
+  },
+  async checkPermissions(input, context): Promise<PermissionDecision> {
+    const appState = context.getAppState()
+    return checkReadPermissionForTool(
+      LSPTool,
+      input,
+      appState.toolPermissionContext,
+    )
+  },
+  async prompt() {
+    return DESCRIPTION
+  },
+  renderToolUseMessage,
+  renderToolUseErrorMessage,
+  renderToolResultMessage,
+  async call(input: Input, _context) {
+    const absolutePath = expandPath(input.filePath)
+    const cwd = getCwd()
+
+    // Wait for initialization if it's still pending
+    // This prevents returning "no server available" before init completes
+    const status = getInitializationStatus()
+    if (status.status === 'pending') {
+      await waitForInitialization()
+    }
+
+    // Get the LSP server manager
+    const manager = getLspServerManager()
+    if (!manager) {
+      // Log this system-level failure for tracking
+      logError(
+        new Error('LSP server manager not initialized when tool was called'),
+      )
+
+      const output: Output = {
+        operation: input.operation,
+        result:
+          'LSP server manager not initialized. This may indicate a startup issue.',
+        filePath: input.filePath,
+      }
+      return {
+        data: output,
+      }
+    }
+
+    // Map operation to LSP method and prepare params
+    const { method, params } = getMethodAndParams(input, absolutePath)
+
+    try {
+      // Ensure file is open in LSP server before making requests
+      // Most LSP servers require textDocument/didOpen before operations
+      // Only read the file if it's not already open to avoid unnecessary I/O
+      if (!manager.isFileOpen(absolutePath)) {
+        const handle = await open(absolutePath, 'r')
+        try {
+          const stats = await handle.stat()
+          if (stats.size > MAX_LSP_FILE_SIZE_BYTES) {
+            const output: Output = {
+              operation: input.operation,
+              result: `File too large for LSP analysis (${Math.ceil(stats.size / 1_000_000)}MB exceeds 10MB limit)`,
+              filePath: input.filePath,
+            }
+            return { data: output }
+          }
+          const fileContent = await handle.readFile({ encoding: 'utf-8' })
+          await manager.openFile(absolutePath, fileContent)
+        } finally {
+          await handle.close()
+        }
+      }
+
+      // Send request to LSP server
+      let result = await manager.sendRequest(absolutePath, method, params)
+
+      if (result === undefined) {
+        // Log for diagnostic purposes - helps track usage patterns and potential bugs
+        logForDebugging(
+          `No LSP server available for file type ${path.extname(absolutePath)} for operation ${input.operation} on file ${input.filePath}`,
+        )
+
+        const output: Output = {
+          operation: input.operation,
+          result: `No LSP server available for file type: ${path.extname(absolutePath)}`,
+          filePath: input.filePath,
+        }
+        return {
+          data: output,
+        }
+      }
+
+      // For incomingCalls and outgoingCalls, we need a two-step process:
+      // 1. First get CallHierarchyItem(s) from prepareCallHierarchy
+      // 2. Then request the actual calls using that item
+      if (
+        input.operation === 'incomingCalls' ||
+        input.operation === 'outgoingCalls'
+      ) {
+        const callItems = result as CallHierarchyItem[]
+        if (!callItems || callItems.length === 0) {
+          const output: Output = {
+            operation: input.operation,
+            result: 'No call hierarchy item found at this position',
+            filePath: input.filePath,
+            resultCount: 0,
+            fileCount: 0,
+          }
+          return { data: output }
+        }
+
+        // Use the first call hierarchy item to request calls
+        const callMethod =
+          input.operation === 'incomingCalls'
+            ? 'callHierarchy/incomingCalls'
+            : 'callHierarchy/outgoingCalls'
+
+        result = await manager.sendRequest(absolutePath, callMethod, {
+          item: callItems[0],
+        })
+
+        if (result === undefined) {
+          logForDebugging(
+            `LSP server returned undefined for ${callMethod} on ${input.filePath}`,
+          )
+          // Continue to formatter which will handle empty/null gracefully
+        }
+      }
+
+      // Filter out gitignored files from location-based results
+      if (
+        result &&
+        Array.isArray(result) &&
+        (input.operation === 'findReferences' ||
+          input.operation === 'goToDefinition' ||
+          input.operation === 'goToImplementation' ||
+          input.operation === 'workspaceSymbol')
+      ) {
+        if (input.operation === 'workspaceSymbol') {
+          // SymbolInformation has location.uri — filter by extracting locations
+          const symbols = result as SymbolInformation[]
+          const locations = symbols
+            .filter(s => s?.location?.uri)
+            .map(s => s.location)
+          const filteredLocations = await filterGitIgnoredLocations(
+            locations,
+            cwd,
+          )
+          const filteredUris = new Set(filteredLocations.map(l => l.uri))
+          result = symbols.filter(
+            s => !s?.location?.uri || filteredUris.has(s.location.uri),
+          )
+        } else {
+          // Location[] or (Location | LocationLink)[]
+          const locations = (result as (Location | LocationLink)[]).map(
+            toLocation,
+          )
+          const filteredLocations = await filterGitIgnoredLocations(
+            locations,
+            cwd,
+          )
+          const filteredUris = new Set(filteredLocations.map(l => l.uri))
+          result = (result as (Location | LocationLink)[]).filter(item => {
+            const loc = toLocation(item)
+            return !loc.uri || filteredUris.has(loc.uri)
+          })
+        }
+      }
+
+      // Format the result based on operation type
+      const { formatted, resultCount, fileCount } = formatResult(
+        input.operation,
+        result,
+        cwd,
+      )
+
+      const output: Output = {
+        operation: input.operation,
+        result: formatted,
+        filePath: input.filePath,
+        resultCount,
+        fileCount,
+      }
+
+      return {
+        data: output,
+      }
+    } catch (error) {
+      const err = toError(error)
+      const errorMessage = err.message
+
+      // Log error for tracking
+      logError(
+        new Error(
+          `LSP tool request failed for ${input.operation} on ${input.filePath}: ${errorMessage}`,
+        ),
+      )
+
+      const output: Output = {
+        operation: input.operation,
+        result: `Error performing ${input.operation}: ${errorMessage}`,
+        filePath: input.filePath,
+      }
+      return {
+        data: output,
+      }
+    }
+  },
+  mapToolResultToToolResultBlockParam(output, toolUseID) {
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content: output.result,
+    }
+  },
+} satisfies ToolDef<InputSchema, Output>)
+
+/**
+ * Maps LSPTool operation to LSP method and params
+ */
+function getMethodAndParams(
+  input: Input,
+  absolutePath: string,
+): { method: string; params: unknown } {
+  const uri = pathToFileURL(absolutePath).href
+  // Convert from 1-based (user-friendly) to 0-based (LSP protocol)
+  const position = {
+    line: input.line - 1,
+    character: input.character - 1,
+  }
+
+  switch (input.operation) {
+    case 'goToDefinition':
+      return {
+        method: 'textDocument/definition',
+        params: {
+          textDocument: { uri },
+          position,
+        },
+      }
+    case 'findReferences':
+      return {
+        method: 'textDocument/references',
+        params: {
+          textDocument: { uri },
+          position,
+          context: { includeDeclaration: true },
+        },
+      }
+    case 'hover':
+      return {
+        method: 'textDocument/hover',
+        params: {
+          textDocument: { uri },
+          position,
+        },
+      }
+    case 'documentSymbol':
+      return {
+        method: 'textDocument/documentSymbol',
+        params: {
+          textDocument: { uri },
+        },
+      }
+    case 'workspaceSymbol':
+      return {
+        method: 'workspace/symbol',
+        params: {
+          query: '', // Empty query returns all symbols
+        },
+      }
+    case 'goToImplementation':
+      return {
+        method: 'textDocument/implementation',
+        params: {
+          textDocument: { uri },
+          position,
+        },
+      }
+    case 'prepareCallHierarchy':
+      return {
+        method: 'textDocument/prepareCallHierarchy',
+        params: {
+          textDocument: { uri },
+          position,
+        },
+      }
+    case 'incomingCalls':
+      // For incoming/outgoing calls, we first need to prepare the call hierarchy
+      // The LSP server will return CallHierarchyItem(s) that we pass to the calls request
+      return {
+        method: 'textDocument/prepareCallHierarchy',
+        params: {
+          textDocument: { uri },
+          position,
+        },
+      }
+    case 'outgoingCalls':
+      return {
+        method: 'textDocument/prepareCallHierarchy',
+        params: {
+          textDocument: { uri },
+          position,
+        },
+      }
+  }
+}
+
+/**
+ * Counts the total number of symbols including nested children
+ */
+function countSymbols(symbols: DocumentSymbol[]): number {
+  let count = symbols.length
+  for (const symbol of symbols) {
+    if (symbol.children && symbol.children.length > 0) {
+      count += countSymbols(symbol.children)
+    }
+  }
+  return count
+}
+
+/**
+ * Counts unique files from an array of locations
+ */
+function countUniqueFiles(locations: Location[]): number {
+  return new Set(locations.map(loc => loc.uri)).size
+}
+
+/**
+ * Extracts a file path from a file:// URI, decoding percent-encoded characters.
+ */
+function uriToFilePath(uri: string): string {
+  let filePath = uri.replace(/^file:\/\//, '')
+  // On Windows, file:///C:/path becomes /C:/path — strip the leading slash
+  if (/^\/[A-Za-z]:/.test(filePath)) {
+    filePath = filePath.slice(1)
+  }
+  try {
+    filePath = decodeURIComponent(filePath)
+  } catch {
+    // Use un-decoded path if malformed
+  }
+  return filePath
+}
+
+/**
+ * Filters out locations whose file paths are gitignored.
+ * Uses `git check-ignore` with batched path arguments for efficiency.
+ */
+async function filterGitIgnoredLocations<T extends Location>(
+  locations: T[],
+  cwd: string,
+): Promise<T[]> {
+  if (locations.length === 0) {
+    return locations
+  }
+
+  // Collect unique file paths from URIs
+  const uriToPath = new Map<string, string>()
+  for (const loc of locations) {
+    if (loc.uri && !uriToPath.has(loc.uri)) {
+      uriToPath.set(loc.uri, uriToFilePath(loc.uri))
+    }
+  }
+
+  const uniquePaths = uniq(uriToPath.values())
+  if (uniquePaths.length === 0) {
+    return locations
+  }
+
+  // Batch check paths with git check-ignore
+  // Exit code 0 = at least one path is ignored, 1 = none ignored, 128 = not a git repo
+  const ignoredPaths = new Set<string>()
+  const BATCH_SIZE = 50
+  for (let i = 0; i < uniquePaths.length; i += BATCH_SIZE) {
+    const batch = uniquePaths.slice(i, i + BATCH_SIZE)
+    const result = await execFileNoThrowWithCwd(
+      'git',
+      ['check-ignore', ...batch],
+      {
+        cwd,
+        preserveOutputOnError: false,
+        timeout: 5_000,
+      },
+    )
+
+    if (result.code === 0 && result.stdout) {
+      for (const line of result.stdout.split('\n')) {
+        const trimmed = line.trim()
+        if (trimmed) {
+          ignoredPaths.add(trimmed)
+        }
+      }
+    }
+  }
+
+  if (ignoredPaths.size === 0) {
+    return locations
+  }
+
+  return locations.filter(loc => {
+    const filePath = uriToPath.get(loc.uri)
+    return !filePath || !ignoredPaths.has(filePath)
+  })
+}
+
+/**
+ * Checks if item is LocationLink (has targetUri) vs Location (has uri)
+ */
+function isLocationLink(item: Location | LocationLink): item is LocationLink {
+  return 'targetUri' in item
+}
+
+/**
+ * Converts LocationLink to Location format for uniform handling
+ */
+function toLocation(item: Location | LocationLink): Location {
+  if (isLocationLink(item)) {
+    return {
+      uri: item.targetUri,
+      range: item.targetSelectionRange || item.targetRange,
+    }
+  }
+  return item
+}
+
+/**
+ * Formats LSP result based on operation type and extracts summary counts
+ */
+function formatResult(
+  operation: Input['operation'],
+  result: unknown,
+  cwd: string,
+): { formatted: string; resultCount: number; fileCount: number } {
+  switch (operation) {
+    case 'goToDefinition': {
+      // Handle both Location and LocationLink formats
+      const rawResults = Array.isArray(result)
+        ? result
+        : result
+          ? [result as Location | LocationLink]
+          : []
+
+      // Convert LocationLinks to Locations for uniform handling
+      const locations = rawResults.map(toLocation)
+
+      // Log and filter out locations with undefined uris
+      const invalidLocations = locations.filter(loc => !loc || !loc.uri)
+      if (invalidLocations.length > 0) {
+        logError(
+          new Error(
+            `LSP server returned ${invalidLocations.length} location(s) with undefined URI for goToDefinition on ${cwd}. ` +
+              `This indicates malformed data from the LSP server.`,
+          ),
+        )
+      }
+
+      const validLocations = locations.filter(loc => loc && loc.uri)
+      return {
+        formatted: formatGoToDefinitionResult(
+          result as
+            | Location
+            | Location[]
+            | LocationLink
+            | LocationLink[]
+            | null,
+          cwd,
+        ),
+        resultCount: validLocations.length,
+        fileCount: countUniqueFiles(validLocations),
+      }
+    }
+    case 'findReferences': {
+      const locations = (result as Location[]) || []
+
+      // Log and filter out locations with undefined uris
+      const invalidLocations = locations.filter(loc => !loc || !loc.uri)
+      if (invalidLocations.length > 0) {
+        logError(
+          new Error(
+            `LSP server returned ${invalidLocations.length} location(s) with undefined URI for findReferences on ${cwd}. ` +
+              `This indicates malformed data from the LSP server.`,
+          ),
+        )
+      }
+
+      const validLocations = locations.filter(loc => loc && loc.uri)
+      return {
+        formatted: formatFindReferencesResult(result as Location[] | null, cwd),
+        resultCount: validLocations.length,
+        fileCount: countUniqueFiles(validLocations),
+      }
+    }
+    case 'hover': {
+      return {
+        formatted: formatHoverResult(result as Hover | null, cwd),
+        resultCount: result ? 1 : 0,
+        fileCount: result ? 1 : 0,
+      }
+    }
+    case 'documentSymbol': {
+      // LSP allows documentSymbol to return either DocumentSymbol[] or SymbolInformation[]
+      const symbols = (result as (DocumentSymbol | SymbolInformation)[]) || []
+      // Detect format: DocumentSymbol has 'range', SymbolInformation has 'location'
+      const isDocumentSymbol =
+        symbols.length > 0 && symbols[0] && 'range' in symbols[0]
+      // Count symbols - DocumentSymbol can have nested children, SymbolInformation is flat
+      const count = isDocumentSymbol
+        ? countSymbols(symbols as DocumentSymbol[])
+        : symbols.length
+      return {
+        formatted: formatDocumentSymbolResult(
+          result as (DocumentSymbol[] | SymbolInformation[]) | null,
+          cwd,
+        ),
+        resultCount: count,
+        fileCount: symbols.length > 0 ? 1 : 0,
+      }
+    }
+    case 'workspaceSymbol': {
+      const symbols = (result as SymbolInformation[]) || []
+
+      // Log and filter out symbols with undefined location.uri
+      const invalidSymbols = symbols.filter(
+        sym => !sym || !sym.location || !sym.location.uri,
+      )
+      if (invalidSymbols.length > 0) {
+        logError(
+          new Error(
+            `LSP server returned ${invalidSymbols.length} symbol(s) with undefined location URI for workspaceSymbol on ${cwd}. ` +
+              `This indicates malformed data from the LSP server.`,
+          ),
+        )
+      }
+
+      const validSymbols = symbols.filter(
+        sym => sym && sym.location && sym.location.uri,
+      )
+      const locations = validSymbols.map(s => s.location)
+      return {
+        formatted: formatWorkspaceSymbolResult(
+          result as SymbolInformation[] | null,
+          cwd,
+        ),
+        resultCount: validSymbols.length,
+        fileCount: countUniqueFiles(locations),
+      }
+    }
+    case 'goToImplementation': {
+      // Handle both Location and LocationLink formats (same as goToDefinition)
+      const rawResults = Array.isArray(result)
+        ? result
+        : result
+          ? [result as Location | LocationLink]
+          : []
+
+      // Convert LocationLinks to Locations for uniform handling
+      const locations = rawResults.map(toLocation)
+
+      // Log and filter out locations with undefined uris
+      const invalidLocations = locations.filter(loc => !loc || !loc.uri)
+      if (invalidLocations.length > 0) {
+        logError(
+          new Error(
+            `LSP server returned ${invalidLocations.length} location(s) with undefined URI for goToImplementation on ${cwd}. ` +
+              `This indicates malformed data from the LSP server.`,
+          ),
+        )
+      }
+
+      const validLocations = locations.filter(loc => loc && loc.uri)
+      return {
+        // Reuse goToDefinition formatter since the result format is identical
+        formatted: formatGoToDefinitionResult(
+          result as
+            | Location
+            | Location[]
+            | LocationLink
+            | LocationLink[]
+            | null,
+          cwd,
+        ),
+        resultCount: validLocations.length,
+        fileCount: countUniqueFiles(validLocations),
+      }
+    }
+    case 'prepareCallHierarchy': {
+      const items = (result as CallHierarchyItem[]) || []
+      return {
+        formatted: formatPrepareCallHierarchyResult(
+          result as CallHierarchyItem[] | null,
+          cwd,
+        ),
+        resultCount: items.length,
+        fileCount: items.length > 0 ? countUniqueFilesFromCallItems(items) : 0,
+      }
+    }
+    case 'incomingCalls': {
+      const calls = (result as CallHierarchyIncomingCall[]) || []
+      return {
+        formatted: formatIncomingCallsResult(
+          result as CallHierarchyIncomingCall[] | null,
+          cwd,
+        ),
+        resultCount: calls.length,
+        fileCount:
+          calls.length > 0 ? countUniqueFilesFromIncomingCalls(calls) : 0,
+      }
+    }
+    case 'outgoingCalls': {
+      const calls = (result as CallHierarchyOutgoingCall[]) || []
+      return {
+        formatted: formatOutgoingCallsResult(
+          result as CallHierarchyOutgoingCall[] | null,
+          cwd,
+        ),
+        resultCount: calls.length,
+        fileCount:
+          calls.length > 0 ? countUniqueFilesFromOutgoingCalls(calls) : 0,
+      }
+    }
+  }
+}
+
+/**
+ * Counts unique files from CallHierarchyItem array
+ * Filters out items with undefined URIs
+ */
+function countUniqueFilesFromCallItems(items: CallHierarchyItem[]): number {
+  const validUris = items.map(item => item.uri).filter(uri => uri)
+  return new Set(validUris).size
+}
+
+/**
+ * Counts unique files from CallHierarchyIncomingCall array
+ * Filters out calls with undefined URIs
+ */
+function countUniqueFilesFromIncomingCalls(
+  calls: CallHierarchyIncomingCall[],
+): number {
+  const validUris = calls.map(call => call.from?.uri).filter(uri => uri)
+  return new Set(validUris).size
+}
+
+/**
+ * Counts unique files from CallHierarchyOutgoingCall array
+ * Filters out calls with undefined URIs
+ */
+function countUniqueFilesFromOutgoingCalls(
+  calls: CallHierarchyOutgoingCall[],
+): number {
+  const validUris = calls.map(call => call.to?.uri).filter(uri => uri)
+  return new Set(validUris).size
+}

packages/builtin-tools/src/tools/LSPTool/UI.tsx

@@ -0,0 +1,203 @@
+import type { ToolResultBlockParam } from '@anthropic-ai/sdk/resources/index.mjs'
+import React from 'react'
+import { CtrlOToExpand } from 'src/components/CtrlOToExpand.js'
+import { FallbackToolUseErrorMessage } from 'src/components/FallbackToolUseErrorMessage.js'
+import { MessageResponse } from 'src/components/MessageResponse.js'
+import { Box, Text } from '@anthropic/ink'
+import { getDisplayPath } from 'src/utils/file.js'
+import { extractTag } from 'src/utils/messages.js'
+import type { Input, Output } from './LSPTool.js'
+import { getSymbolAtPosition } from './symbolContext.js'
+
+// Lookup map for operation-specific labels
+const OPERATION_LABELS: Record<
+  Input['operation'],
+  { singular: string; plural: string; special?: string }
+> = {
+  goToDefinition: { singular: 'definition', plural: 'definitions' },
+  findReferences: { singular: 'reference', plural: 'references' },
+  documentSymbol: { singular: 'symbol', plural: 'symbols' },
+  workspaceSymbol: { singular: 'symbol', plural: 'symbols' },
+  hover: { singular: 'hover info', plural: 'hover info', special: 'available' },
+  goToImplementation: { singular: 'implementation', plural: 'implementations' },
+  prepareCallHierarchy: { singular: 'call item', plural: 'call items' },
+  incomingCalls: { singular: 'caller', plural: 'callers' },
+  outgoingCalls: { singular: 'callee', plural: 'callees' },
+}
+
+/**
+ * Reusable component for LSP result summaries with collapsed/expanded views
+ */
+function LSPResultSummary({
+  operation,
+  resultCount,
+  fileCount,
+  content,
+  verbose,
+}: {
+  operation: Input['operation']
+  resultCount: number
+  fileCount: number
+  content: string
+  verbose: boolean
+}): React.ReactNode {
+  // Get label configuration for this operation
+  const labelConfig = OPERATION_LABELS[operation] || {
+    singular: 'result',
+    plural: 'results',
+  }
+  const countLabel =
+    resultCount === 1 ? labelConfig.singular : labelConfig.plural
+
+  const primaryText =
+    operation === 'hover' && resultCount > 0 && labelConfig.special ? (
+      <Text>Hover info {labelConfig.special}</Text>
+    ) : (
+      <Text>
+        Found <Text bold>{resultCount} </Text>
+        {countLabel}
+      </Text>
+    )
+
+  const secondaryText =
+    fileCount > 1 ? (
+      <Text>
+        {' '}
+        across <Text bold>{fileCount} </Text>
+        files
+      </Text>
+    ) : null
+
+  if (verbose) {
+    return (
+      <Box flexDirection="column">
+        <Box flexDirection="row">
+          <Text>
+            <Text dimColor>&nbsp;&nbsp;⎿ &nbsp;</Text>
+            {primaryText}
+            {secondaryText}
+          </Text>
+        </Box>
+        <Box marginLeft={5}>
+          <Text>{content}</Text>
+        </Box>
+      </Box>
+    )
+  }
+
+  return (
+    <MessageResponse height={1}>
+      <Text>
+        {primaryText}
+        {secondaryText} {resultCount > 0 && <CtrlOToExpand />}
+      </Text>
+    </MessageResponse>
+  )
+}
+
+export function userFacingName(): string {
+  return 'LSP'
+}
+
+export function renderToolUseMessage(
+  input: Partial<Input>,
+  { verbose }: { verbose: boolean },
+): React.ReactNode {
+  if (!input.operation) {
+    return null
+  }
+
+  const parts: string[] = []
+
+  // For position-based operations (goToDefinition, findReferences, hover, goToImplementation),
+  // show the symbol at the position for better context
+  if (
+    (input.operation === 'goToDefinition' ||
+      input.operation === 'findReferences' ||
+      input.operation === 'hover' ||
+      input.operation === 'goToImplementation') &&
+    input.filePath &&
+    input.line !== undefined &&
+    input.character !== undefined
+  ) {
+    // Convert from 1-based (user input) to 0-based (internal file reading)
+    const symbol = getSymbolAtPosition(
+      input.filePath,
+      input.line - 1,
+      input.character - 1,
+    )
+    const displayPath = verbose
+      ? input.filePath
+      : getDisplayPath(input.filePath)
+
+    if (symbol) {
+      parts.push(`operation: "${input.operation}"`)
+      parts.push(`symbol: "${symbol}"`)
+      parts.push(`in: "${displayPath}"`)
+    } else {
+      parts.push(`operation: "${input.operation}"`)
+      parts.push(`file: "${displayPath}"`)
+      parts.push(`position: ${input.line}:${input.character}`)
+    }
+
+    return parts.join(', ')
+  }
+
+  // For other operations (documentSymbol, workspaceSymbol),
+  // show operation and file without position details
+  parts.push(`operation: "${input.operation}"`)
+
+  if (input.filePath) {
+    const displayPath = verbose
+      ? input.filePath
+      : getDisplayPath(input.filePath)
+    parts.push(`file: "${displayPath}"`)
+  }
+
+  return parts.join(', ')
+}
+
+export function renderToolUseErrorMessage(
+  result: ToolResultBlockParam['content'],
+  { verbose }: { verbose: boolean },
+): React.ReactNode {
+  if (
+    !verbose &&
+    typeof result === 'string' &&
+    extractTag(result, 'tool_use_error')
+  ) {
+    return (
+      <MessageResponse>
+        <Text color="error">LSP operation failed</Text>
+      </MessageResponse>
+    )
+  }
+  return <FallbackToolUseErrorMessage result={result} verbose={verbose} />
+}
+
+export function renderToolResultMessage(
+  output: Output,
+  _progressMessages: unknown[],
+  { verbose }: { verbose: boolean },
+): React.ReactNode {
+  // Use collapsed/expanded view if we have count information
+  if (output.resultCount !== undefined && output.fileCount !== undefined) {
+    return (
+      <LSPResultSummary
+        operation={output.operation}
+        resultCount={output.resultCount}
+        fileCount={output.fileCount}
+        content={output.result}
+        verbose={verbose}
+      />
+    )
+  }
+
+  // Fallback for error cases where counts aren't available
+  // (e.g., LSP server initialization failures, request errors)
+  return (
+    <MessageResponse>
+      <Text>{output.result}</Text>
+    </MessageResponse>
+  )
+}

packages/builtin-tools/src/tools/LSPTool/__tests__/formatters.test.ts

@@ -0,0 +1,197 @@
+import { mock, describe, expect, test } from "bun:test";
+
+mock.module("src/utils/debug.js", () => ({
+  logForDebugging: () => {},
+  isDebugMode: () => false,
+}));
+
+mock.module("src/utils/errors.js", () => ({
+  errorMessage: (e: unknown) => String(e),
+}));
+
+mock.module("src/utils/stringUtils.js", () => ({
+  plural: (n: number, singular: string, plural?: string) =>
+    n === 1 ? singular : (plural ?? singular + "s"),
+}));
+
+const {
+  formatGoToDefinitionResult,
+  formatFindReferencesResult,
+  formatHoverResult,
+  formatDocumentSymbolResult,
+  formatWorkspaceSymbolResult,
+  formatPrepareCallHierarchyResult,
+  formatIncomingCallsResult,
+  formatOutgoingCallsResult,
+} = await import("../formatters");
+
+// Minimal LSP type stubs for testing
+const makeLocation = (uri: string, startLine: number, startChar: number, endLine: number, endChar: number) => ({
+  uri,
+  range: {
+    start: { line: startLine, character: startChar },
+    end: { line: endLine, character: endChar },
+  },
+});
+
+const makeSymbol = (name: string, kind: number, range: { start: { line: number; character: number }; end: { line: number; character: number } }) => ({
+  name,
+  kind,
+  range,
+  children: undefined,
+});
+
+const makeCallItem = (name: string, uri: string, line: number) => ({
+  name,
+  kind: 12, // Function
+  uri,
+  range: {
+    start: { line: line, character: 0 },
+    end: { line: line, character: 10 },
+  },
+  selectionRange: {
+    start: { line: line, character: 0 },
+    end: { line: line, character: name.length },
+  },
+});
+
+describe("formatGoToDefinitionResult", () => {
+  test("returns no definitions message for null", () => {
+    const result = formatGoToDefinitionResult(null);
+    expect(result).toContain("No definition found");
+  });
+
+  test("formats single location", () => {
+    const loc = makeLocation("file:///src/foo.ts", 10, 5, 10, 15);
+    const result = formatGoToDefinitionResult(loc);
+    expect(result).toContain("foo.ts");
+    // LSP lines are 0-based, display is 1-based → line 10 = display line 11
+    expect(result).toContain("11");
+  });
+
+  test("formats array of locations", () => {
+    const locs = [
+      makeLocation("file:///src/a.ts", 1, 0, 1, 5),
+      makeLocation("file:///src/b.ts", 5, 0, 5, 5),
+    ];
+    const result = formatGoToDefinitionResult(locs);
+    expect(result).toContain("a.ts");
+    expect(result).toContain("b.ts");
+  });
+});
+
+describe("formatFindReferencesResult", () => {
+  test("returns no references message for null", () => {
+    expect(formatFindReferencesResult(null)).toContain("No references found");
+  });
+
+  test("formats references", () => {
+    const refs = [
+      makeLocation("file:///src/a.ts", 1, 0, 1, 5),
+      makeLocation("file:///src/b.ts", 3, 0, 3, 5),
+    ];
+    const result = formatFindReferencesResult(refs);
+    expect(result).toContain("a.ts");
+    expect(result).toContain("b.ts");
+  });
+});
+
+describe("formatHoverResult", () => {
+  test("returns no hover message for null", () => {
+    expect(formatHoverResult(null)).toContain("No hover information");
+  });
+
+  test("formats hover with string contents", () => {
+    const hover = {
+      contents: { kind: "plaintext", value: "string" },
+      range: makeLocation("file:///a.ts", 0, 0, 0, 5).range,
+    };
+    const result = formatHoverResult(hover as any);
+    expect(result).toContain("string");
+  });
+});
+
+describe("formatDocumentSymbolResult", () => {
+  test("returns no symbols message for null", () => {
+    expect(formatDocumentSymbolResult(null)).toContain("No symbols found");
+  });
+
+  test("returns no symbols for empty array", () => {
+    expect(formatDocumentSymbolResult([])).toContain("No symbols found");
+  });
+
+  test("formats document symbols", () => {
+    const symbols = [
+      makeSymbol("MyClass", 5, { start: { line: 0, character: 0 }, end: { line: 10, character: 0 } }),
+      makeSymbol("myMethod", 6, { start: { line: 2, character: 0 }, end: { line: 5, character: 0 } }),
+    ];
+    const result = formatDocumentSymbolResult(symbols as any);
+    expect(result).toContain("MyClass");
+    expect(result).toContain("myMethod");
+  });
+});
+
+describe("formatWorkspaceSymbolResult", () => {
+  test("returns no symbols for null", () => {
+    expect(formatWorkspaceSymbolResult(null)).toContain("No symbols found");
+  });
+
+  test("formats workspace symbols", () => {
+    const symbols = [
+      {
+        name: "SearchResult",
+        kind: 12,
+        location: makeLocation("file:///src/a.ts", 0, 0, 0, 5),
+      },
+    ];
+    const result = formatWorkspaceSymbolResult(symbols as any);
+    expect(result).toContain("SearchResult");
+  });
+});
+
+describe("formatPrepareCallHierarchyResult", () => {
+  test("returns no items for null", () => {
+    expect(formatPrepareCallHierarchyResult(null)).toContain("No call hierarchy");
+  });
+
+  test("formats call hierarchy items", () => {
+    const items = [makeCallItem("main", "file:///src/main.ts", 5)];
+    const result = formatPrepareCallHierarchyResult(items as any);
+    expect(result).toContain("main");
+    expect(result).toContain("main.ts");
+  });
+});
+
+describe("formatIncomingCallsResult", () => {
+  test("returns no calls for null", () => {
+    expect(formatIncomingCallsResult(null)).toContain("No incoming calls");
+  });
+
+  test("formats incoming calls", () => {
+    const calls = [
+      {
+        from: makeCallItem("caller", "file:///src/a.ts", 3),
+        fromRanges: [makeLocation("file:///src/a.ts", 3, 0, 3, 5).range],
+      },
+    ];
+    const result = formatIncomingCallsResult(calls as any);
+    expect(result).toContain("caller");
+  });
+});
+
+describe("formatOutgoingCallsResult", () => {
+  test("returns no calls for null", () => {
+    expect(formatOutgoingCallsResult(null)).toContain("No outgoing calls");
+  });
+
+  test("formats outgoing calls", () => {
+    const calls = [
+      {
+        to: makeCallItem("callee", "file:///src/b.ts", 10),
+        fromRanges: [makeLocation("file:///src/main.ts", 5, 0, 5, 5).range],
+      },
+    ];
+    const result = formatOutgoingCallsResult(calls as any);
+    expect(result).toContain("callee");
+  });
+});

packages/builtin-tools/src/tools/LSPTool/__tests__/schemas.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import { isValidLSPOperation } from "../schemas";
+
+describe("isValidLSPOperation", () => {
+  const validOps = [
+    "goToDefinition",
+    "findReferences",
+    "hover",
+    "documentSymbol",
+    "workspaceSymbol",
+    "goToImplementation",
+    "prepareCallHierarchy",
+    "incomingCalls",
+    "outgoingCalls",
+  ];
+
+  test.each(validOps)("returns true for valid operation: %s", (op) => {
+    expect(isValidLSPOperation(op)).toBe(true);
+  });
+
+  test("returns false for invalid operation", () => {
+    expect(isValidLSPOperation("invalidOp")).toBe(false);
+  });
+
+  test("returns false for empty string", () => {
+    expect(isValidLSPOperation("")).toBe(false);
+  });
+
+  test("returns false for undefined", () => {
+    expect(isValidLSPOperation(undefined as any)).toBe(false);
+  });
+
+  test("is case sensitive", () => {
+    expect(isValidLSPOperation("GoToDefinition")).toBe(false);
+    expect(isValidLSPOperation("HOVER")).toBe(false);
+  });
+});

packages/builtin-tools/src/tools/LSPTool/formatters.ts

@@ -0,0 +1,592 @@
+import { relative } from 'path'
+import type {
+  CallHierarchyIncomingCall,
+  CallHierarchyItem,
+  CallHierarchyOutgoingCall,
+  DocumentSymbol,
+  Hover,
+  Location,
+  LocationLink,
+  MarkedString,
+  MarkupContent,
+  SymbolInformation,
+  SymbolKind,
+} from 'vscode-languageserver-types'
+import { logForDebugging } from 'src/utils/debug.js'
+import { errorMessage } from 'src/utils/errors.js'
+import { plural } from 'src/utils/stringUtils.js'
+
+/**
+ * Formats a URI by converting it to a relative path if possible.
+ * Handles URI decoding and gracefully falls back to un-decoded path if malformed.
+ * Only uses relative paths when shorter and not starting with ../../
+ */
+function formatUri(uri: string | undefined, cwd?: string): string {
+  // Handle undefined/null URIs - this indicates malformed LSP data
+  if (!uri) {
+    // NOTE: This should ideally be caught earlier with proper error logging
+    // This is a defensive backstop in the formatting layer
+    logForDebugging(
+      'formatUri called with undefined URI - indicates malformed LSP server response',
+      { level: 'warn' },
+    )
+    return '<unknown location>'
+  }
+
+  // Remove file:// protocol if present
+  // On Windows, file:///C:/path becomes /C:/path after replacing file://
+  // We need to strip the leading slash for Windows drive-letter paths
+  let filePath = uri.replace(/^file:\/\//, '')
+  if (/^\/[A-Za-z]:/.test(filePath)) {
+    filePath = filePath.slice(1)
+  }
+
+  // Decode URI encoding - handle malformed URIs gracefully
+  try {
+    filePath = decodeURIComponent(filePath)
+  } catch (error) {
+    // Log for debugging but continue with un-decoded path
+    const errorMsg = errorMessage(error)
+    logForDebugging(
+      `Failed to decode LSP URI '${uri}': ${errorMsg}. Using un-decoded path: ${filePath}`,
+      { level: 'warn' },
+    )
+    // filePath already contains the un-decoded path, which is still usable
+  }
+
+  // Convert to relative path if cwd is provided
+  if (cwd) {
+    // Normalize separators to forward slashes for consistent display output
+    const relativePath = relative(cwd, filePath).replaceAll('\\', '/')
+    // Only use relative path if it's shorter and doesn't start with ../..
+    if (
+      relativePath.length < filePath.length &&
+      !relativePath.startsWith('../../')
+    ) {
+      return relativePath
+    }
+  }
+
+  // Normalize separators to forward slashes for consistent display output
+  return filePath.replaceAll('\\', '/')
+}
+
+/**
+ * Groups items by their file URI.
+ * Generic helper that works with both Location[] and SymbolInformation[]
+ */
+function groupByFile<T extends { uri: string } | { location: { uri: string } }>(
+  items: T[],
+  cwd?: string,
+): Map<string, T[]> {
+  const byFile = new Map<string, T[]>()
+  for (const item of items) {
+    const uri = 'uri' in item ? item.uri : item.location.uri
+    const filePath = formatUri(uri, cwd)
+    const existingItems = byFile.get(filePath)
+    if (existingItems) {
+      existingItems.push(item)
+    } else {
+      byFile.set(filePath, [item])
+    }
+  }
+  return byFile
+}
+
+/**
+ * Formats a Location with file path and line/character position
+ */
+function formatLocation(location: Location, cwd?: string): string {
+  const filePath = formatUri(location.uri, cwd)
+  const line = location.range.start.line + 1 // Convert to 1-based
+  const character = location.range.start.character + 1 // Convert to 1-based
+  return `${filePath}:${line}:${character}`
+}
+
+/**
+ * Converts LocationLink to Location format for consistent handling
+ */
+function locationLinkToLocation(link: LocationLink): Location {
+  return {
+    uri: link.targetUri,
+    range: link.targetSelectionRange || link.targetRange,
+  }
+}
+
+/**
+ * Checks if an object is a LocationLink (has targetUri) vs Location (has uri)
+ */
+function isLocationLink(item: Location | LocationLink): item is LocationLink {
+  return 'targetUri' in item
+}
+
+/**
+ * Formats goToDefinition result
+ * Can return Location, LocationLink, or arrays of either
+ */
+export function formatGoToDefinitionResult(
+  result: Location | Location[] | LocationLink | LocationLink[] | null,
+  cwd?: string,
+): string {
+  if (!result) {
+    return 'No definition found. This may occur if the cursor is not on a symbol, or if the definition is in an external library not indexed by the LSP server.'
+  }
+
+  if (Array.isArray(result)) {
+    // Convert LocationLinks to Locations for uniform handling
+    const locations: Location[] = result.map(item =>
+      isLocationLink(item) ? locationLinkToLocation(item) : item,
+    )
+
+    // Log and filter out any locations with undefined uris
+    const invalidLocations = locations.filter(loc => !loc || !loc.uri)
+    if (invalidLocations.length > 0) {
+      logForDebugging(
+        `formatGoToDefinitionResult: Filtering out ${invalidLocations.length} invalid location(s) - this should have been caught earlier`,
+        { level: 'warn' },
+      )
+    }
+
+    const validLocations = locations.filter(loc => loc && loc.uri)
+
+    if (validLocations.length === 0) {
+      return 'No definition found. This may occur if the cursor is not on a symbol, or if the definition is in an external library not indexed by the LSP server.'
+    }
+    if (validLocations.length === 1) {
+      return `Defined in ${formatLocation(validLocations[0]!, cwd)}`
+    }
+    const locationList = validLocations
+      .map(loc => `  ${formatLocation(loc, cwd)}`)
+      .join('\n')
+    return `Found ${validLocations.length} definitions:\n${locationList}`
+  }
+
+  // Single result - convert LocationLink if needed
+  const location = isLocationLink(result)
+    ? locationLinkToLocation(result)
+    : result
+  return `Defined in ${formatLocation(location, cwd)}`
+}
+
+/**
+ * Formats findReferences result
+ */
+export function formatFindReferencesResult(
+  result: Location[] | null,
+  cwd?: string,
+): string {
+  if (!result || result.length === 0) {
+    return 'No references found. This may occur if the symbol has no usages, or if the LSP server has not fully indexed the workspace.'
+  }
+
+  // Log and filter out any locations with undefined uris
+  const invalidLocations = result.filter(loc => !loc || !loc.uri)
+  if (invalidLocations.length > 0) {
+    logForDebugging(
+      `formatFindReferencesResult: Filtering out ${invalidLocations.length} invalid location(s) - this should have been caught earlier`,
+      { level: 'warn' },
+    )
+  }
+
+  const validLocations = result.filter(loc => loc && loc.uri)
+
+  if (validLocations.length === 0) {
+    return 'No references found. This may occur if the symbol has no usages, or if the LSP server has not fully indexed the workspace.'
+  }
+
+  if (validLocations.length === 1) {
+    return `Found 1 reference:\n  ${formatLocation(validLocations[0]!, cwd)}`
+  }
+
+  // Group references by file
+  const byFile = groupByFile(validLocations, cwd)
+
+  const lines: string[] = [
+    `Found ${validLocations.length} references across ${byFile.size} files:`,
+  ]
+
+  for (const [filePath, locations] of byFile) {
+    lines.push(`\n${filePath}:`)
+    for (const loc of locations) {
+      const line = loc.range.start.line + 1
+      const character = loc.range.start.character + 1
+      lines.push(`  Line ${line}:${character}`)
+    }
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Extracts text content from MarkupContent or MarkedString
+ */
+function extractMarkupText(
+  contents: MarkupContent | MarkedString | MarkedString[],
+): string {
+  if (Array.isArray(contents)) {
+    return contents
+      .map(item => {
+        if (typeof item === 'string') {
+          return item
+        }
+        return item.value
+      })
+      .join('\n\n')
+  }
+
+  if (typeof contents === 'string') {
+    return contents
+  }
+
+  if ('kind' in contents) {
+    // MarkupContent
+    return contents.value
+  }
+
+  // MarkedString object
+  return contents.value
+}
+
+/**
+ * Formats hover result
+ */
+export function formatHoverResult(result: Hover | null, _cwd?: string): string {
+  if (!result) {
+    return 'No hover information available. This may occur if the cursor is not on a symbol, or if the LSP server has not fully indexed the file.'
+  }
+
+  const content = extractMarkupText(result.contents)
+
+  if (result.range) {
+    const line = result.range.start.line + 1
+    const character = result.range.start.character + 1
+    return `Hover info at ${line}:${character}:\n\n${content}`
+  }
+
+  return content
+}
+
+/**
+ * Maps SymbolKind enum to readable string
+ */
+function symbolKindToString(kind: SymbolKind): string {
+  const kinds: Record<SymbolKind, string> = {
+    [1]: 'File',
+    [2]: 'Module',
+    [3]: 'Namespace',
+    [4]: 'Package',
+    [5]: 'Class',
+    [6]: 'Method',
+    [7]: 'Property',
+    [8]: 'Field',
+    [9]: 'Constructor',
+    [10]: 'Enum',
+    [11]: 'Interface',
+    [12]: 'Function',
+    [13]: 'Variable',
+    [14]: 'Constant',
+    [15]: 'String',
+    [16]: 'Number',
+    [17]: 'Boolean',
+    [18]: 'Array',
+    [19]: 'Object',
+    [20]: 'Key',
+    [21]: 'Null',
+    [22]: 'EnumMember',
+    [23]: 'Struct',
+    [24]: 'Event',
+    [25]: 'Operator',
+    [26]: 'TypeParameter',
+  }
+  return kinds[kind] || 'Unknown'
+}
+
+/**
+ * Formats a single DocumentSymbol with indentation
+ */
+function formatDocumentSymbolNode(
+  symbol: DocumentSymbol,
+  indent: number = 0,
+): string[] {
+  const lines: string[] = []
+  const prefix = '  '.repeat(indent)
+  const kind = symbolKindToString(symbol.kind)
+
+  let line = `${prefix}${symbol.name} (${kind})`
+  if (symbol.detail) {
+    line += ` ${symbol.detail}`
+  }
+
+  const symbolLine = symbol.range.start.line + 1
+  line += ` - Line ${symbolLine}`
+
+  lines.push(line)
+
+  // Recursively format children
+  if (symbol.children && symbol.children.length > 0) {
+    for (const child of symbol.children) {
+      lines.push(...formatDocumentSymbolNode(child, indent + 1))
+    }
+  }
+
+  return lines
+}
+
+/**
+ * Formats documentSymbol result (hierarchical outline)
+ * Handles both DocumentSymbol[] (hierarchical, with range) and SymbolInformation[] (flat, with location.range)
+ * per LSP spec which allows textDocument/documentSymbol to return either format
+ */
+export function formatDocumentSymbolResult(
+  result: DocumentSymbol[] | SymbolInformation[] | null,
+  cwd?: string,
+): string {
+  if (!result || result.length === 0) {
+    return 'No symbols found in document. This may occur if the file is empty, not supported by the LSP server, or if the server has not fully indexed the file.'
+  }
+
+  // Detect format: DocumentSymbol has 'range' directly, SymbolInformation has 'location.range'
+  // Check the first valid element to determine format
+  const firstSymbol = result[0]
+  const isSymbolInformation = firstSymbol && 'location' in firstSymbol
+
+  if (isSymbolInformation) {
+    // Delegate to workspace symbol formatter which handles SymbolInformation[]
+    return formatWorkspaceSymbolResult(result as SymbolInformation[], cwd)
+  }
+
+  // Handle DocumentSymbol[] format (hierarchical)
+  const lines: string[] = ['Document symbols:']
+
+  for (const symbol of result as DocumentSymbol[]) {
+    lines.push(...formatDocumentSymbolNode(symbol))
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Formats workspaceSymbol result (flat list of symbols)
+ */
+export function formatWorkspaceSymbolResult(
+  result: SymbolInformation[] | null,
+  cwd?: string,
+): string {
+  if (!result || result.length === 0) {
+    return 'No symbols found in workspace. This may occur if the workspace is empty, or if the LSP server has not finished indexing the project.'
+  }
+
+  // Log and filter out any symbols with undefined location.uri
+  const invalidSymbols = result.filter(
+    sym => !sym || !sym.location || !sym.location.uri,
+  )
+  if (invalidSymbols.length > 0) {
+    logForDebugging(
+      `formatWorkspaceSymbolResult: Filtering out ${invalidSymbols.length} invalid symbol(s) - this should have been caught earlier`,
+      { level: 'warn' },
+    )
+  }
+
+  const validSymbols = result.filter(
+    sym => sym && sym.location && sym.location.uri,
+  )
+
+  if (validSymbols.length === 0) {
+    return 'No symbols found in workspace. This may occur if the workspace is empty, or if the LSP server has not finished indexing the project.'
+  }
+
+  const lines: string[] = [
+    `Found ${validSymbols.length} ${plural(validSymbols.length, 'symbol')} in workspace:`,
+  ]
+
+  // Group by file
+  const byFile = groupByFile(validSymbols, cwd)
+
+  for (const [filePath, symbols] of byFile) {
+    lines.push(`\n${filePath}:`)
+    for (const symbol of symbols) {
+      const kind = symbolKindToString(symbol.kind)
+      const line = symbol.location.range.start.line + 1
+      let symbolLine = `  ${symbol.name} (${kind}) - Line ${line}`
+
+      // Add container name if available
+      if (symbol.containerName) {
+        symbolLine += ` in ${symbol.containerName}`
+      }
+
+      lines.push(symbolLine)
+    }
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Formats a CallHierarchyItem with its location
+ * Validates URI before formatting to handle malformed LSP data
+ */
+function formatCallHierarchyItem(
+  item: CallHierarchyItem,
+  cwd?: string,
+): string {
+  // Validate URI - handle undefined/null gracefully
+  if (!item.uri) {
+    logForDebugging(
+      'formatCallHierarchyItem: CallHierarchyItem has undefined URI',
+      { level: 'warn' },
+    )
+    return `${item.name} (${symbolKindToString(item.kind)}) - <unknown location>`
+  }
+
+  const filePath = formatUri(item.uri, cwd)
+  const line = item.range.start.line + 1
+  const kind = symbolKindToString(item.kind)
+  let result = `${item.name} (${kind}) - ${filePath}:${line}`
+  if (item.detail) {
+    result += ` [${item.detail}]`
+  }
+  return result
+}
+
+/**
+ * Formats prepareCallHierarchy result
+ * Returns the call hierarchy item(s) at the given position
+ */
+export function formatPrepareCallHierarchyResult(
+  result: CallHierarchyItem[] | null,
+  cwd?: string,
+): string {
+  if (!result || result.length === 0) {
+    return 'No call hierarchy item found at this position'
+  }
+
+  if (result.length === 1) {
+    return `Call hierarchy item: ${formatCallHierarchyItem(result[0]!, cwd)}`
+  }
+
+  const lines = [`Found ${result.length} call hierarchy items:`]
+  for (const item of result) {
+    lines.push(`  ${formatCallHierarchyItem(item, cwd)}`)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Formats incomingCalls result
+ * Shows all functions/methods that call the target
+ */
+export function formatIncomingCallsResult(
+  result: CallHierarchyIncomingCall[] | null,
+  cwd?: string,
+): string {
+  if (!result || result.length === 0) {
+    return 'No incoming calls found (nothing calls this function)'
+  }
+
+  const lines = [
+    `Found ${result.length} incoming ${plural(result.length, 'call')}:`,
+  ]
+
+  // Group by file
+  const byFile = new Map<string, CallHierarchyIncomingCall[]>()
+  for (const call of result) {
+    if (!call.from) {
+      logForDebugging(
+        'formatIncomingCallsResult: CallHierarchyIncomingCall has undefined from field',
+        { level: 'warn' },
+      )
+      continue
+    }
+    const filePath = formatUri(call.from.uri, cwd)
+    const existing = byFile.get(filePath)
+    if (existing) {
+      existing.push(call)
+    } else {
+      byFile.set(filePath, [call])
+    }
+  }
+
+  for (const [filePath, calls] of byFile) {
+    lines.push(`\n${filePath}:`)
+    for (const call of calls) {
+      if (!call.from) {
+        continue // Already logged above
+      }
+      const kind = symbolKindToString(call.from.kind)
+      const line = call.from.range.start.line + 1
+      let callLine = `  ${call.from.name} (${kind}) - Line ${line}`
+
+      // Show call sites within the caller
+      if (call.fromRanges && call.fromRanges.length > 0) {
+        const callSites = call.fromRanges
+          .map(r => `${r.start.line + 1}:${r.start.character + 1}`)
+          .join(', ')
+        callLine += ` [calls at: ${callSites}]`
+      }
+
+      lines.push(callLine)
+    }
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Formats outgoingCalls result
+ * Shows all functions/methods called by the target
+ */
+export function formatOutgoingCallsResult(
+  result: CallHierarchyOutgoingCall[] | null,
+  cwd?: string,
+): string {
+  if (!result || result.length === 0) {
+    return 'No outgoing calls found (this function calls nothing)'
+  }
+
+  const lines = [
+    `Found ${result.length} outgoing ${plural(result.length, 'call')}:`,
+  ]
+
+  // Group by file
+  const byFile = new Map<string, CallHierarchyOutgoingCall[]>()
+  for (const call of result) {
+    if (!call.to) {
+      logForDebugging(
+        'formatOutgoingCallsResult: CallHierarchyOutgoingCall has undefined to field',
+        { level: 'warn' },
+      )
+      continue
+    }
+    const filePath = formatUri(call.to.uri, cwd)
+    const existing = byFile.get(filePath)
+    if (existing) {
+      existing.push(call)
+    } else {
+      byFile.set(filePath, [call])
+    }
+  }
+
+  for (const [filePath, calls] of byFile) {
+    lines.push(`\n${filePath}:`)
+    for (const call of calls) {
+      if (!call.to) {
+        continue // Already logged above
+      }
+      const kind = symbolKindToString(call.to.kind)
+      const line = call.to.range.start.line + 1
+      let callLine = `  ${call.to.name} (${kind}) - Line ${line}`
+
+      // Show call sites within the current function
+      if (call.fromRanges && call.fromRanges.length > 0) {
+        const callSites = call.fromRanges
+          .map(r => `${r.start.line + 1}:${r.start.character + 1}`)
+          .join(', ')
+        callLine += ` [called from: ${callSites}]`
+      }
+
+      lines.push(callLine)
+    }
+  }
+
+  return lines.join('\n')
+}

packages/builtin-tools/src/tools/LSPTool/prompt.ts

@@ -0,0 +1,21 @@
+export const LSP_TOOL_NAME = 'LSP' as const
+
+export const DESCRIPTION = `Interact with Language Server Protocol (LSP) servers to get code intelligence features.
+
+Supported operations:
+- goToDefinition: Find where a symbol is defined
+- findReferences: Find all references to a symbol
+- hover: Get hover information (documentation, type info) for a symbol
+- documentSymbol: Get all symbols (functions, classes, variables) in a document
+- workspaceSymbol: Search for symbols across the entire workspace
+- goToImplementation: Find implementations of an interface or abstract method
+- prepareCallHierarchy: Get call hierarchy item at a position (functions/methods)
+- incomingCalls: Find all functions/methods that call the function at a position
+- outgoingCalls: Find all functions/methods called by the function at a position
+
+All operations require:
+- filePath: The file to operate on
+- line: The line number (1-based, as shown in editors)
+- character: The character offset (1-based, as shown in editors)
+
+Note: LSP servers must be configured for the file type. If no server is available, an error will be returned.`

packages/builtin-tools/src/tools/LSPTool/schemas.ts

@@ -0,0 +1,215 @@
+import { z } from 'zod/v4'
+import { lazySchema } from 'src/utils/lazySchema.js'
+
+/**
+ * Discriminated union of all LSP operations
+ * Uses 'operation' as the discriminator field
+ */
+export const lspToolInputSchema = lazySchema(() => {
+  /**
+   * Go to Definition operation
+   * Finds the definition location of a symbol at the given position
+   */
+  const goToDefinitionSchema = z.strictObject({
+    operation: z.literal('goToDefinition'),
+    filePath: z.string().describe('The absolute or relative path to the file'),
+    line: z
+      .number()
+      .int()
+      .positive()
+      .describe('The line number (1-based, as shown in editors)'),
+    character: z
+      .number()
+      .int()
+      .positive()
+      .describe('The character offset (1-based, as shown in editors)'),
+  })
+
+  /**
+   * Find References operation
+   * Finds all references to a symbol at the given position
+   */
+  const findReferencesSchema = z.strictObject({
+    operation: z.literal('findReferences'),
+    filePath: z.string().describe('The absolute or relative path to the file'),
+    line: z
+      .number()
+      .int()
+      .positive()
+      .describe('The line number (1-based, as shown in editors)'),
+    character: z
+      .number()
+      .int()
+      .positive()
+      .describe('The character offset (1-based, as shown in editors)'),
+  })
+
+  /**
+   * Hover operation
+   * Gets hover information (documentation, type info) for a symbol at the given position
+   */
+  const hoverSchema = z.strictObject({
+    operation: z.literal('hover'),
+    filePath: z.string().describe('The absolute or relative path to the file'),
+    line: z
+      .number()
+      .int()
+      .positive()
+      .describe('The line number (1-based, as shown in editors)'),
+    character: z
+      .number()
+      .int()
+      .positive()
+      .describe('The character offset (1-based, as shown in editors)'),
+  })
+
+  /**
+   * Document Symbol operation
+   * Gets all symbols (functions, classes, variables) in a document
+   */
+  const documentSymbolSchema = z.strictObject({
+    operation: z.literal('documentSymbol'),
+    filePath: z.string().describe('The absolute or relative path to the file'),
+    line: z
+      .number()
+      .int()
+      .positive()
+      .describe('The line number (1-based, as shown in editors)'),
+    character: z
+      .number()
+      .int()
+      .positive()
+      .describe('The character offset (1-based, as shown in editors)'),
+  })
+
+  /**
+   * Workspace Symbol operation
+   * Searches for symbols across the entire workspace
+   */
+  const workspaceSymbolSchema = z.strictObject({
+    operation: z.literal('workspaceSymbol'),
+    filePath: z.string().describe('The absolute or relative path to the file'),
+    line: z
+      .number()
+      .int()
+      .positive()
+      .describe('The line number (1-based, as shown in editors)'),
+    character: z
+      .number()
+      .int()
+      .positive()
+      .describe('The character offset (1-based, as shown in editors)'),
+  })
+
+  /**
+   * Go to Implementation operation
+   * Finds the implementation locations of an interface or abstract method
+   */
+  const goToImplementationSchema = z.strictObject({
+    operation: z.literal('goToImplementation'),
+    filePath: z.string().describe('The absolute or relative path to the file'),
+    line: z
+      .number()
+      .int()
+      .positive()
+      .describe('The line number (1-based, as shown in editors)'),
+    character: z
+      .number()
+      .int()
+      .positive()
+      .describe('The character offset (1-based, as shown in editors)'),
+  })
+
+  /**
+   * Prepare Call Hierarchy operation
+   * Prepares a call hierarchy item at the given position (first step for call hierarchy)
+   */
+  const prepareCallHierarchySchema = z.strictObject({
+    operation: z.literal('prepareCallHierarchy'),
+    filePath: z.string().describe('The absolute or relative path to the file'),
+    line: z
+      .number()
+      .int()
+      .positive()
+      .describe('The line number (1-based, as shown in editors)'),
+    character: z
+      .number()
+      .int()
+      .positive()
+      .describe('The character offset (1-based, as shown in editors)'),
+  })
+
+  /**
+   * Incoming Calls operation
+   * Finds all functions/methods that call the function at the given position
+   */
+  const incomingCallsSchema = z.strictObject({
+    operation: z.literal('incomingCalls'),
+    filePath: z.string().describe('The absolute or relative path to the file'),
+    line: z
+      .number()
+      .int()
+      .positive()
+      .describe('The line number (1-based, as shown in editors)'),
+    character: z
+      .number()
+      .int()
+      .positive()
+      .describe('The character offset (1-based, as shown in editors)'),
+  })
+
+  /**
+   * Outgoing Calls operation
+   * Finds all functions/methods called by the function at the given position
+   */
+  const outgoingCallsSchema = z.strictObject({
+    operation: z.literal('outgoingCalls'),
+    filePath: z.string().describe('The absolute or relative path to the file'),
+    line: z
+      .number()
+      .int()
+      .positive()
+      .describe('The line number (1-based, as shown in editors)'),
+    character: z
+      .number()
+      .int()
+      .positive()
+      .describe('The character offset (1-based, as shown in editors)'),
+  })
+
+  return z.discriminatedUnion('operation', [
+    goToDefinitionSchema,
+    findReferencesSchema,
+    hoverSchema,
+    documentSymbolSchema,
+    workspaceSymbolSchema,
+    goToImplementationSchema,
+    prepareCallHierarchySchema,
+    incomingCallsSchema,
+    outgoingCallsSchema,
+  ])
+})
+
+/**
+ * TypeScript type for LSPTool input
+ */
+export type LSPToolInput = z.infer<ReturnType<typeof lspToolInputSchema>>
+
+/**
+ * Type guard to check if an operation is a valid LSP operation
+ */
+export function isValidLSPOperation(
+  operation: string,
+): operation is LSPToolInput['operation'] {
+  return [
+    'goToDefinition',
+    'findReferences',
+    'hover',
+    'documentSymbol',
+    'workspaceSymbol',
+    'goToImplementation',
+    'prepareCallHierarchy',
+    'incomingCalls',
+    'outgoingCalls',
+  ].includes(operation)
+}

packages/builtin-tools/src/tools/LSPTool/symbolContext.ts

@@ -0,0 +1,90 @@
+import { logForDebugging } from 'src/utils/debug.js'
+import { truncate } from 'src/utils/format.js'
+import { getFsImplementation } from 'src/utils/fsOperations.js'
+import { expandPath } from 'src/utils/path.js'
+
+const MAX_READ_BYTES = 64 * 1024
+
+/**
+ * Extracts the symbol/word at a specific position in a file.
+ * Used to show context in tool use messages.
+ *
+ * @param filePath - The file path (absolute or relative)
+ * @param line - 0-indexed line number
+ * @param character - 0-indexed character position on the line
+ *
+ * Note: This uses synchronous file I/O because it is called from
+ * renderToolUseMessage (a synchronous React render function). The read is
+ * wrapped in try/catch so ENOENT and other errors fall back gracefully.
+ * @returns The symbol at that position, or null if extraction fails
+ */
+export function getSymbolAtPosition(
+  filePath: string,
+  line: number,
+  character: number,
+): string | null {
+  try {
+    const fs = getFsImplementation()
+    const absolutePath = expandPath(filePath)
+
+    // Read only the first 64KB instead of the whole file. Most LSP hover/goto
+    // targets are near recent edits; 64KB covers ~1000 lines of typical code.
+    // If the target line is past this window we fall back to null (the UI
+    // already handles that by showing `position: line:char`).
+    // eslint-disable-next-line custom-rules/no-sync-fs -- called from sync React render (renderToolUseMessage)
+    const { buffer, bytesRead } = fs.readSync(absolutePath, {
+      length: MAX_READ_BYTES,
+    })
+    const content = buffer.toString('utf-8', 0, bytesRead)
+    const lines = content.split('\n')
+
+    if (line < 0 || line >= lines.length) {
+      return null
+    }
+    // If we filled the full buffer the file continues past our window,
+    // so the last split element may be truncated mid-line.
+    if (bytesRead === MAX_READ_BYTES && line === lines.length - 1) {
+      return null
+    }
+
+    const lineContent = lines[line]
+    if (!lineContent || character < 0 || character >= lineContent.length) {
+      return null
+    }
+
+    // Extract the word/symbol at the character position
+    // Pattern matches:
+    // - Standard identifiers: alphanumeric + underscore + dollar
+    // - Rust lifetimes: 'a, 'static
+    // - Rust macros: macro_name!
+    // - Operators and special symbols: +, -, *, etc.
+    // This is more inclusive to handle various programming languages
+    const symbolPattern = /[\w$'!]+|[+\-*/%&|^~<>=]+/g
+    let match: RegExpExecArray | null
+
+    while ((match = symbolPattern.exec(lineContent)) !== null) {
+      const start = match.index
+      const end = start + match[0].length
+
+      // Check if the character position falls within this match
+      if (character >= start && character < end) {
+        const symbol = match[0]
+        // Limit length to 30 characters to avoid overly long symbols
+        return truncate(symbol, 30)
+      }
+    }
+
+    return null
+  } catch (error) {
+    // Log unexpected errors for debugging (permission issues, encoding problems, etc.)
+    // Use logForDebugging since this is a display enhancement, not a critical error
+    if (error instanceof Error) {
+      logForDebugging(
+        `Symbol extraction failed for ${filePath}:${line}:${character}: ${error.message}`,
+        { level: 'warn' },
+      )
+    }
+    // Still return null for graceful fallback to position display
+    return null
+  }
+}