Add File Attachment Capability to new_task Tool

[daniel-lxs]

Add File Attachment Capability to new_task Tool

Closes: #2931

This PR introduces a new parameter to the new_task tool, enabling the parent agent to attach files by mimicking how users reference files in tasks.

Context

This enhancement adds a <files> parameter to the new_task tool. Files specified in this parameter will be processed using the same logic as the read_file function, including:

• Application of the maximum line limit constraint
• Inclusion of line numbers in file contents
• Support for specifying line ranges using the format path:startLine:endLine

Purpose:

This allows tasks to be created with immediately available file context, which:

• Avoids redundant file read requests from child agents
• Reduces token consumption from sequential file operations
• Encourages explicit file inclusion in task definitions
• Improves overall task execution efficiency

Implementation Details

1. File Specification Format:

   • Basic format: <file>path/to/file.ts</file>
   • With line range: <file>path/to/file.ts:10:50</file> (lines 10-50)

2. Backend Changes:

   • Added AttachedFileSpec interface in shared/tools.ts
   • Enhanced newTaskTool.ts to parse file paths and extract line ranges
   • Updated ClineProvider.ts to pass file specifications to the Cline constructor
   • Refactored Cline.ts to process attached files with line ranges and format them appropriately in the initial prompt

3. UI Enhancements:

   • Updated ChatRow.tsx to display attached files as badges within the task content block
   • Added support for showing line ranges in the badges (e.g., @filename:10-50)
   • Clicking the badge opens the file with a selection of the line range if specified

4. Documentation:

   • Updated the tool description in new-task.ts to explain the new syntax and provide examples

Visual Comparison

Before: New tasks required the child agent to explicitly request files, leading to redundant operations and token usage.

After: Files are immediately available to the child agent, with badges showing attached files:

• @filename for full files
• @filename:10-50 for files with line ranges

Testing Protocol

1. Basic Functionality:

   • Create a new task with a single attached file
   • Create a new task with multiple attached files
   • Verify files appear in the initial context of the child agent

2. Line Range Testing:

   • Attach a file with a specific line range (e.g., src/core/Cline.ts:580:600)
   • Verify only the specified lines are included in the context
   • Test edge cases (start line > end line, line numbers beyond file length)

3. UI Verification:

   • Confirm file badges appear correctly in the task approval message
   • Verify line ranges are displayed properly in the badges
   • Check that badges are displayed side-by-side in a flex container
   • Click on the badges to confirm the file opens correctly

4. Error Handling:

   • Test with non-existent files
   • Test with invalid line ranges
   • Verify appropriate error messages are shown

---

Important

This PR adds file attachment capability with line range specifications to the new_task tool, updating backend processing and UI display.

• Behavior:
  • Adds <files> parameter to new_task tool for attaching files with optional line ranges.
  • Files processed using read_file logic, including line limits and line numbers.
• Backend Changes:
  • Introduces AttachedFileSpec interface in shared/tools.ts.
  • Updates newTaskTool.ts to parse and handle file paths and line ranges.
  • Modifies ClineProvider.ts to pass file specifications to Cline.
  • Refactors Cline.ts to format attached files for task prompts.
• UI Enhancements:
  • Updates ChatRow.tsx to display attached files as badges with line ranges.
  • Clicking badges opens files with specified line selections.
• Documentation:
  • Updates new-task.ts to include new syntax and examples for file attachments.

^{This description was created by for d5a1d4af904060bdb8e5bce3075e3acdf9740847. You can customize this summary. It will automatically update as commits are pushed.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 6b9865ffffe1b095fc01c6af88dd067a30d910f2

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[daniel-lxs]

@cte @mrubens This test is unrelated to the feature but it still failed, it seems like a faulty test.

[adamhill]

🚀

[jezweb]

this will be a brilliant time saver thank you

[mrubens]

We're focused on orchestrator improvements this week - @cte will be in touch about this

[daniel-lxs]

Rebased, now it's up to date with the recent Cline.ts refactor

[hannesrudolph]

@mrubens @cte can we please review this tomorrow?

[jr]

I like this idea a lot.

It seems like it overlaps a lot with what readFileTool does. Is it practical to share most of that code, or are there reasons I'm not thinking of why that wouldn't work?

[daniel-lxs]

@jr
I agree with you, I will check if moving the read file logic makes sense in this case, it probably does.
I will definitely make the file content more like the read_file tool.

[daniel-lxs]

@jr
I refactored readFileTool.ts to extract the read file logic and put it on a shared file src/shared/fileReadUtils.ts, now this shared file works for both this new feature and the read_file tool.

I have also split the tests, now we test the file reading logic separately from the read_file tool, while keeping the same coverage from the previous tests.

[hannesrudolph]

@daniel-lxs can you move over to experimental and fix conflicts?

[KJ7LNW]

@samhvw8 please review #3086 with respect to #2886:

It looks like this #3086 simply factors out processFileForReading, which may not affect #2886 at all, but I want to avoid any complications because #2886 has become quite mature.

Both PRs touch read_file and @samhvw8 (plus other users, including myself) have put a lot of testing into #2886 and it works quite well.

[daniel-lxs]

Hey @KJ7LNW, the refactor to the read_file logic was made to unify the logic so it can be used in both places that is needed without duplicating the code.

The read_file tool unit tests were separated from the file reading logic, but I made sure to avoid modifying the tests themselves on both cases, if you see a case where a test no longer serves its original purpose please let me know.

[KJ7LNW]

Overall, I like the implementation and I think this will be very useful.

Most of my comments are about best practices and ways to minimize differences across the refactor.

Thank you for putting this together!

[KJ7LNW]

processFileForReading is only used for tools, so it would be better placed in something like src/core/tools/toolHelpers.ts because fileReadUtils.ts is intended for file operations they have nothing to do with the user interface.

[KJ7LNW]

as below, move the test to src/core/tools/__tests__

[KJ7LNW]

I am pretty sure this function already exists somewhere else? or maybe it was just reordered?

[KJ7LNW]

I think this function exists somewhere else, or maybe it was already here, but I do not understand why we see a bunch of + lines

[KJ7LNW]

does the stereotype need to be accessible by the user interface? if so put it in shared/ , otherwise it goes in toolHelpers.ts or maybe a file dedicated to tool structures if we do not have one yet

[KJ7LNW]

This should probably stay in readFileTool.ts and export it if you need it somewhere else.

someday functions like this will be in a tool base class to build xml without string concatenation with a proper xml builder library .

[KJ7LNW]

Please see #2886 and work with @samhvw8 so that are line range formats do not diverge; multiple range formats would probably confuse the model across tools.

Gemini and Claude have both been shown empirically tested that the following format used in #2886 works very well for the model. this is a real life example:

<read_file>
<args>
  <file>
    <path>src/core/config/__tests__/ContextProxy.test.ts</path>
    <line_range>130-140</line_range> <!-- Around line 134 -->
    <line_range>160-170</line_range> <!-- Around line 166 -->
  </file>
  <file>
    <path>src/exports/api.ts</path>
    <line_range>60-75</line_range> <!-- Around line 67 -->
  </file>
  <file>
    <path>src/exports/types.ts</path> <!-- To see RooCodeSettings definition -->
  </file>
  <file>
    <path>src/schemas/index.ts</path>
    <line_range>150-160</line_range> <!-- To see historyItemSchema definition -->
  </file>
</args>
</read_file>

standardizing XML representation will simplify it tool class refactors in the future

[KJ7LNW]

where did access allowed go?

if it moved somewhere centralized, then great but I want to make sure we are not creating regressions

[KJ7LNW]

These look like unnecessary variable rename that cause diff review bloat.

Unless there is a really good reason to rename variables let's not do that if we can avoid it, so we can tell what actually change for the pull request, and what is original .

[KJ7LNW]

This is a huge function hoist, and we need to make sure there are no hallucinations: please show the diff to a smart model (o4-high, etc) and ask it to validate that there is exactly no behavior change.

Especially, please validate around output formatting and file line endings, leading and trailing blank lines, etc, which have been validated in detail (and hopefully the tests will still enforce). If you were to look up the pull request related to XML output formatting, this was done meticulously for consistent output and help gemini with understanding things.

[KJ7LNW]

Hey @KJ7LNW, the refactor to the read_file logic was made to unify the logic so it can be used in both places that is needed without duplicating the code.
The read_file tool unit tests were separated from the file reading logic, but I made sure to avoid modifying the tests themselves on both cases, if you see a case where a test no longer serves its original purpose please let me know.

If the test still pass, then hopefully it is fine. I only made this comment because I have seen models hallucinate during large code moves, so I always ask the model in a separate question showing only the diff and have it validate that the difference in behavior is identical.

It probably is identical but, I operate on the side of caution with these kinds of things.

[daniel-lxs]

This can potentially break power-steering and it's not something we want at the moment.