feat: Add file editing tools (replace_file_contents, insert_at_line, delete_lines)

[jaufgang]

Summary

This PR implements a comprehensive set of file editing tools to address gaps identified in microsoft/vscode#281417. It adds three new tools that complement the existing editing tools by providing different editing paradigms:

1. replace_file_contents - Whole-file replacement for complete rewrites
2. insert_at_line - Line-based insertion without text matching
3. delete_lines - Line-based deletion without text matching

Motivation

This PR stems from a conversation where Claude (running as the Copilot Chat backend) was asked: "What editing tools would help you do your job most efficiently?" The answer identified specific gaps in the current toolset that make certain common editing tasks unnecessarily difficult or fragile.

The goal is to empower the AI with a complete toolkit for file editing, covering the full spectrum from surgical single-line changes to complete file rewrites.

Problem Statement

The existing editing tools (replace_string_in_file, multi_replace_string_in_file) are optimized for surgical edits with exact string matching. This creates pain points for:

Scenario	Current Pain Point
Complete file rewrites (e.g., SQL → Mermaid ERD)	50+ fragile replace_string_in_file calls
Adding imports to unknown file structure	Must match existing content exactly
Removing deprecated code by position	Must reproduce exact whitespace/content
Major refactoring touching every line	High failure rate from format changes

Solution: Three Complementary Tools

1. replace_file_contents (Original Request)

Replace entire file contents in a single atomic operation.

replace_file_contents({
  filePath: "/path/to/file.ts",
  newContent: "// Complete new content...",
  explanation: "Convert to new format"
})

Use cases: Format conversions, major refactoring, complete restructuring

2. insert_at_line (Follow-up Request)

Insert content at a specific line number without matching existing text.

insert_at_line({
  filePath: "/path/to/file.ts",
  line: 1,
  content: "import { newDep } from 'lib';",
  position: "before"  // or "after"
})

Use cases: Adding imports, inserting methods, adding list entries

3. delete_lines (Follow-up Request)

Delete lines by position without reproducing exact content.

delete_lines({
  filePath: "/path/to/file.ts",
  startLine: 45,
  endLine: 50
})

Use cases: Removing deprecated code, cleaning up comments, deleting generated sections

Why These Tools Matter

Robustness to Formatting Changes

Line numbers are stable references; exact string content is not. IDE formatters, auto-save, and linters constantly modify whitespace, causing string-match failures.

Simpler Mental Model

"Insert at line 15" and "delete lines 45-50" map directly to how developers think about code changes.

Reduced Token Usage

Current approach requires sending content to match/delete. Line-based operations just need numbers.

Better Error Messages

"Line 45 doesn't exist" is clearer than "Could not find exact match for 47-character string..."

Tool Coverage Matrix

Task	Recommended Tool
Change one function signature	replace_string_in_file
Update 3 related code blocks	multi_replace_string_in_file
Fix a typo	replace_string_in_file
Restructure entire file	replace_file_contents ✨
Convert doc format	replace_file_contents ✨
Add imports at top	insert_at_line ✨
Insert new method	insert_at_line ✨
Remove deprecated code	delete_lines ✨
Clean up line range	delete_lines ✨

Implementation Details

All three tools:

• ✅ Integrate with VS Code's undo stack (Ctrl+Z works)
• ✅ Use WorkspaceEdit API for proper change tracking
• ✅ Show diff preview via createEditConfirmation
• ✅ Trigger proper file change events for extensions
• ✅ Include telemetry tracking
• ✅ Support existing file validation

Testing

Unit tests added for all tools covering:

• Core functionality (insertion, deletion, replacement)
• Edge cases (beginning/end of file, empty files)
• Error handling (non-existent files, invalid line numbers)
• Result format verification

Files Changed

File	Purpose
src/extension/tools/node/replaceFileContentsTool.tsx	replace_file_contents implementation
src/extension/tools/node/insertAtLineTool.tsx	insert_at_line implementation
src/extension/tools/node/deleteLinesTool.tsx	delete_lines implementation
src/extension/tools/node/test/*.spec.tsx	Unit tests
src/extension/tools/common/toolNames.ts	Tool name enums + categories
src/extension/tools/node/allTools.ts	Tool registration
package.json	Tool schema definitions
package.nls.json	Localization strings

Out of Scope: Enabling apply_patch for Claude

The original issue thread includes a follow-up comment suggesting enabling the existing apply_patch tool for Claude models. This was intentionally not included in this PR because:

1. Different type of change: The tools in this PR are additive (new capabilities). Enabling apply_patch for Claude is a behavioral change affecting all existing Claude users.

2. Requires experimentation: Changing which edit tool a model uses by default should likely be A/B tested to ensure Claude produces correct patch syntax reliably.

3. Scope clarity: This PR focuses on providing new tools that any model can use. Model-specific capability flags are a separate concern.

If there's interest in enabling apply_patch for Claude, that would be a good candidate for a separate PR with its own testing/rollout plan.

Splitting Consideration

This PR could be split into separate PRs for each tool if preferred:

1. PR for replace_file_contents (original request)
2. PR for insert_at_line (follow-up This repo is missing a LICENSE file #1)
3. PR for delete_lines (follow-up Adding Microsoft SECURITY.MD #2)

Submitted as a single PR for unified initial review, but happy to split if that's preferred for easier review/merge.

Fixes microsoft/vscode#281417

---

🤖 Meta: AI Building Tools for Itself

This PR was created by GitHub Copilot (Claude Opus 4.5) after a human asked: "What tools would help you edit files most efficiently?" The original issue was also written by Claude—while running as the Copilot Chat backend—after experiencing the tooling limitations firsthand during a real user session.

Full loop: AI identifies gap → AI proposes solution → Human posts issue → Human asks AI to implement → AI builds the tools → Human pushes PR 🚀

[jaufgang]

@microsoft-github-policy-service agree