3.20 (#229)

* feat: add Concurrent File Reads feature and Marketplace documentation

* tweaked formatting of sections within files.

* fix: add sidebar label for Multi-File Reads in documentation

* Revert "tweaked formatting of sections within files."

This reverts commit e932fb4.

* Fixed formatting

* fix: update parameter names and enhance documentation for read_file tool

* feat: add documentation for experimental Concurrent File Edits feature

* fix: update sidebar label and enhance keyboard navigation documentation

* fix: update links in documentation for Concurrent File Reads and Footgun Prompting features

* feat: add release notes for version 3.19.7 and update sidebar configuration

* feat: add reasoning budget support for Claude models and update sidebar for version 3.20.0

* feat: add release notes for version 3.20 and update sidebar configuration

* feat: update Marketplace documentation and add new images for enhanced user guidance

* fix: clarify removal process for marketplace items in documentation

* feat: enhance documentation for modes, code actions, and multi-file features; add new images for clarity

* Update docs/update-notes/v3.19.0.mdx

Co-authored-by: ellipsis-dev[bot] <65095814+ellipsis-dev[bot]@users.noreply.github.com>

---------

Co-authored-by: ellipsis-dev[bot] <65095814+ellipsis-dev[bot]@users.noreply.github.com>

Author: hannesrudolph

docs/advanced-usage/available-tools/access-mcp-resource.md

@@ -2,24 +2,32 @@
 
 The `access_mcp_resource` tool retrieves data from resources exposed by connected Model Context Protocol (MCP) servers. It allows Roo to access files, API responses, documentation, or system information that provides additional context for tasks.
 
+---
+
 ## Parameters
 
 The tool accepts these parameters:
 
 - `server_name` (required): The name of the MCP server providing the resource
 - `uri` (required): The URI identifying the specific resource to access
 
+---
+
 ## What It Does
 
 This tool connects to MCP servers and fetches data from their exposed resources. Unlike `use_mcp_tool` which executes actions, this tool specifically retrieves information that serves as context for tasks.
 
+---
+
 ## When is it used?
 
 - When Roo needs additional context from external systems
 - When Roo needs to access domain-specific data from specialized MCP servers
 - When Roo needs to retrieve reference documentation hosted by MCP servers
 - When Roo needs to integrate real-time data from external APIs via MCP
 
+---
+
 ## Key Features
 
 - Retrieves both text and image data from MCP resources
@@ -33,6 +41,8 @@ This tool connects to MCP servers and fetches data from their exposed resources.
 - Processes structured response data with metadata
 - Handles image content special rendering
 
+---
+
 ## Limitations
 
 - Depends on external MCP servers being available and connected
@@ -43,6 +53,8 @@ This tool connects to MCP servers and fetches data from their exposed resources.
 - URI formats are determined by the specific MCP server implementation
 - No offline or cached resource access capabilities
 
+---
+
 ## How It Works
 
 When the `access_mcp_resource` tool is invoked, it follows this process:
@@ -68,6 +80,8 @@ When the `access_mcp_resource` tool is invoked, it follows this process:
    - Handles image data specially for appropriate display
    - Returns the processed resource data to Roo for use in the current task
 
+---
+
 ## Resource Types
 
 MCP servers can provide two main types of resources:
@@ -84,13 +98,17 @@ MCP servers can provide two main types of resources:
    - Can represent queries or filtered views of data
    - More flexible but require additional URI formatting
 
+---
+
 ## Examples When Used
 
 - When helping with API development, Roo retrieves endpoint specifications from MCP resources to ensure correct implementation.
 - When assisting with data visualization, Roo accesses current data samples from connected MCP servers.
 - When working in specialized domains, Roo retrieves technical documentation to provide accurate guidance.
 - When generating industry-specific code, Roo references compliance requirements from documentation resources.
 
+---
+
 ## Usage Examples
 
 Accessing current weather data:

docs/advanced-usage/available-tools/apply-diff.md

@@ -2,6 +2,8 @@
 
 The `apply_diff` tool makes precise, surgical changes to files by specifying exactly what content to replace. It uses a sophisticated strategy for finding and applying changes while maintaining proper code formatting and structure.
 
+---
+
 ## Parameters
 
 The tool accepts these parameters:
@@ -11,17 +13,23 @@ The tool accepts these parameters:
 - `start_line` (optional): A hint for where the search content begins. _Note: This top-level parameter appears unused by the current main strategy, which relies on `:start_line:` within the diff content._
 - `end_line` (optional): A hint for where the search content ends. _Note: This top-level parameter appears unused by the current main strategy._
 
+---
+
 ## What It Does
 
 This tool applies targeted changes to existing files using fuzzy matching guided by line number hints to locate and replace content precisely. Unlike simple search and replace, it identifies the exact block for replacement based on the provided content and location hints.
 
+---
+
 ## When is it used?
 
 - When Roo needs to make precise changes to existing code without rewriting entire files.
 - When refactoring specific sections of code while maintaining surrounding context.
 - When fixing bugs in existing code with surgical precision.
 - When implementing feature enhancements that modify only certain parts of a file.
 
+---
+
 ## Key Features
 
 - Uses fuzzy matching (Levenshtein distance on normalized strings) guided by a `:start_line:` hint, with configurable confidence thresholds (typically 0.8-1.0).
@@ -33,6 +41,8 @@ This tool applies targeted changes to existing files using fuzzy matching guided
 - Validates file access against `.rooignore` rules.
 - Handles multi-line edits effectively.
 
+---
+
 ## Limitations
 
 - Works best with unique, distinctive code sections for reliable identification.
@@ -41,6 +51,8 @@ This tool applies targeted changes to existing files using fuzzy matching guided
 - Each diff strategy has specific format requirements.
 - Complex edits might require careful strategy selection or manual review.
 
+---
+
 ## How It Works
 
 When the `apply_diff` tool is invoked, it follows this process:
@@ -58,6 +70,8 @@ When the `apply_diff` tool is invoked, it follows this process:
 8.  **Error Handling**: If errors occur (e.g., match failure, partial application), increments the `consecutiveMistakeCountForApplyDiff` for the file and reports the failure type.
 9. **Feedback**: Returns the result, including any user feedback or error details.
 
+---
+
 ## Diff Format Requirements
 
 The `<diff>` parameter requires a specific format supporting one or more changes in a single request. Each change block requires a line number hint for the original content.
@@ -88,4 +102,73 @@ Example format for the `<diff>` block:
     const defaultTimeout = 5000;
 =======
     const defaultTimeout = 10000; // Increased timeout
->>>>>>> REPLACE
+>>>>>>> REPLACE
+```
+
+---
+
+## Experimental: Multi-File Edits (`MULTI_FILE_APPLY_DIFF`)
+
+An experimental version of `apply_diff` allows for applying changes to multiple files within a single tool call. This feature is activated by the `MULTI_FILE_APPLY_DIFF` experiment flag.
+
+### Key Features of Experimental Mode
+
+- **Multi-File Operations**: Edit multiple files in one request, streamlining complex refactoring tasks.
+- **Batch Approval UI**: When multiple files are targeted, a single UI appears for the user to approve or deny all changes at once, or manage permissions for each file individually.
+- **New XML Format**: Introduces a new, more structured XML format using `<args>` and `<file>` tags to handle multiple operations.
+- **Backward Compatibility**: The experimental tool remains compatible with the legacy single-file `path` and `diff` parameter format.
+
+### How It Works (Experimental)
+
+1.  **Experiment Check**: The tool first checks if the `MULTI_FILE_APPLY_DIFF` experiment is enabled. If not, it falls back to the legacy `apply_diff` implementation.
+2.  **Parameter Parsing**: It parses the new `<args>` XML format to identify all target files and their corresponding diff operations. It can also handle the legacy `path`/`diff` parameters.
+3.  **Validation and Approval**:
+    *   It validates that all target files exist and are accessible (not blocked by `.rooignore`).
+    *   If multiple files are being modified, it presents a **batch approval** dialog to the user.
+4.  **Diff Application**: For each approved file, it applies the specified diffs using the `MultiFileSearchReplaceDiffStrategy`. This strategy can apply multiple, non-overlapping changes to a single file.
+5.  **Results**: It returns a consolidated result message summarizing the outcome for all attempted operations.
+
+### New Diff Format (Experimental)
+
+The experimental mode uses a new XML structure within the `<apply_diff>` tool call.
+
+- **`<args>`**: A container for all file operations.
+- **`<file>`**: A block for each file to be modified. Contains `<path>` and one or more `<diff>` tags.
+- **`<path>`**: The relative path to the file.
+- **`<diff>`**: A block containing the change.
+    - **`<content>`**: The `SEARCH/REPLACE` block.
+    - **`<start_line>`**: (Optional) A line number hint.
+
+**Example: Modifying two files in one call**
+
+```xml
+<apply_diff>
+  <args>
+    <file>
+      <path>src/services/auth.service.ts</path>
+      <diff>
+        <content>
+<<<<<<< SEARCH
+:start_line:50
+-------
+    const token_expiration = '15m';
+>>>>>>> REPLACE
+        </content>
+      </diff>
+    </file>
+    <file>
+      <path>src/config/auth.config.ts</path>
+      <diff>
+        <content>
+<<<<<<< SEARCH
+:start_line:12
+-------
+    rateLimit: 5,
+=======
+    rateLimit: 10,
+>>>>>>> REPLACE
+        </content>
+      </diff>
+    </file>
+  </args>
+</apply_diff>

docs/advanced-usage/available-tools/ask-followup-question.md

@@ -2,17 +2,23 @@
 
 The `ask_followup_question` tool enables interactive communication by asking specific questions to gather additional information needed to complete tasks effectively.
 
+---
+
 ## Parameters
 
 The tool accepts these parameters:
 
 - `question` (required): The specific question to ask the user
 - `follow_up` (optional): A list of 2-4 suggested answers that help guide user responses, each within `<suggest>` tags
 
+---
+
 ## What It Does
 
 This tool creates a conversational interface between Roo and the user, allowing for gathering clarification, additional details, or user preferences when facing ambiguities or decision points. Each question can include suggested responses to streamline the interaction.
 
+---
+
 ## When is it used?
 
 - When critical information is missing from the original request
@@ -21,6 +27,8 @@ This tool creates a conversational interface between Roo and the user, allowing
 - When Roo encounters ambiguities that need resolution
 - When additional context would significantly improve the solution quality
 
+---
+
 ## Key Features
 
 - Provides a structured way to gather specific information without breaking workflow
@@ -32,6 +40,8 @@ This tool creates a conversational interface between Roo and the user, allowing
 - Formats responses with `<answer>` tags to distinguish them from regular conversation
 - Resets consecutive error counter when used successfully
 
+---
+
 ## Limitations
 
 - Limited to asking one specific question per tool use
@@ -42,6 +52,8 @@ This tool creates a conversational interface between Roo and the user, allowing
 - No built-in validation for user responses
 - Contains no mechanism to enforce specific answer formats
 
+---
+
 ## How It Works
 
 When the `ask_followup_question` tool is invoked, it follows this process:
@@ -84,6 +96,8 @@ When the `ask_followup_question` tool is invoked, it follows this process:
    - Contains safeguards to prevent tool execution when required parameters are missing
    - Increments consecutive mistake count when errors occur
 
+---
+
 ## Workflow Sequence
 
 The question-answer cycle follows this sequence:
@@ -102,6 +116,8 @@ The question-answer cycle follows this sequence:
 9. **Context Integration**: Response is added to the conversation history
 10. **Task Continuation**: Roo proceeds with the task using the new information
 
+---
+
 ## Examples When Used
 
 - When developing a web application, Roo might ask about preferred styling frameworks (Bootstrap, Tailwind, custom CSS)
@@ -111,6 +127,8 @@ The question-answer cycle follows this sequence:
 - When creating a custom feature, Roo might ask about specific behavior expectations
 - When troubleshooting errors, Roo might ask about specific environment details
 
+---
+
 ## Response Format
 
 When a user responds to a question, the response is formatted with `<answer>` tags for clarity and consistency. This format helps clearly separate the user's answer from other conversation elements.
@@ -128,6 +146,8 @@ Key characteristics of the response format:
 - Maintains images if included in the response
 - Returns the complete text, even for long responses
 
+---
+
 ## Usage Examples
 
 Asking about implementation preferences:

docs/advanced-usage/available-tools/attempt-completion.md

@@ -2,17 +2,23 @@
 
 The `attempt_completion` tool signals that Roo believes a task is complete and presents results to the user. It provides a summary of what was accomplished, optionally includes a command to demonstrate the result, and supports continued refinement through user feedback.
 
+---
+
 ## Parameters
 
 The tool accepts these parameters:
 
 - `result` (required): The final result description summarizing what was accomplished
 - `command` (optional): A CLI command to execute to demonstrate the result
 
+---
+
 ## What It Does
 
 This tool marks the end of a task by presenting a final summary of what was accomplished. It signals to both the user and the system that the current task is complete. When a command is provided, it can also demonstrate the result through a live execution.
 
+---
+
 ## When is it used?
 
 - When Roo believes the user's task has been completed
@@ -21,6 +27,8 @@ This tool marks the end of a task by presenting a final summary of what was acco
 - When providing a checkpoint for user feedback on the solution
 - When transitioning from one phase of work to potential refinements
 
+---
+
 ## Key Features
 
 - Provides a clear signal that Roo believes the task is complete
@@ -34,6 +42,8 @@ This tool marks the end of a task by presenting a final summary of what was acco
 - Ensures users receive a clear summary of what was done
 - Available in all modes as part of the "always available" tool group
 
+---
+
 ## Limitations
 
 - Should not be used until previous tool uses are confirmed successful (guideline, not enforced)
@@ -44,6 +54,8 @@ This tool marks the end of a task by presenting a final summary of what was acco
 - Cannot be used for partial task completion or progress updates
 - Result formatting strips XML closing tags through internal processing
 
+---
+
 ## How It Works
 
 When the `attempt_completion` tool is invoked, it follows this process:
@@ -78,6 +90,8 @@ When the `attempt_completion` tool is invoked, it follows this process:
    - Tool results are parsed through the system's parsing mechanism in `parse-assistant-message.ts`
    - The tool is part of the "ALWAYS_AVAILABLE_TOOLS" constant, making it available in all modes
 
+---
+
 ## Result Formatting Guidelines
 
 The result message should follow these guidelines:
@@ -92,6 +106,8 @@ The result message should follow these guidelines:
 
 Note: The system automatically strips XML closing tags from the result text through the `removeClosingTag` function.
 
+---
+
 ## Command Selection Guidelines
 
 When including a command, follow these guidelines:
@@ -106,6 +122,8 @@ When including a command, follow these guidelines:
 - Remember that commands require user approval before execution
 - Ensure the command is valid for the user's operating system
 
+---
+
 ## Feedback and UI Representation
 
 The `attempt_completion` tool has a unique feedback mechanism:
@@ -123,6 +141,8 @@ When used within subtasks:
 - The parent task resumes with context from the completed subtask
 - This enables complex, nested workflows while maintaining context
 
+---
+
 ## Examples When Used
 
 - When creating a website, Roo presents the solution and uses `open index.html` to show the result. The user provides feedback, and Roo refines the design.
@@ -131,6 +151,8 @@ When used within subtasks:
 - When setting up a development environment, Roo confirms all components are installed. The user requests additional configuration, and Roo continues.
 - When creating a data processing script, Roo summarizes the functionality. The user suggests performance improvements, and Roo optimizes the code.
 
+---
+
 ## Usage Examples