Enhancement: Allow escaping of context mentions

[cannuri]

Context

Closes #2931.

This PR introduces a way to escape @ symbols in text inputs, allowing users to pass CLI-style arguments like @/foo literally without triggering file content expansion.

Many command-line tools (e.g., gcc, rsync, curl, dotnet, protoc, etc.) use @/file.txt as a common syntax to read arguments from a file. However, in our system, the @ symbol triggers immediate interpolation and file inclusion. This behavior breaks standard CLI usage and prevents passing such strings directly into tasks or subtasks.

The change allows prefixing the @ symbol with a backslash (\@) to bypass the mention system and pass the input unaltered.

Additionally, when such escaped mentions are passed from a parent task (e.g., orchestrator) to a subtask via the new_task tool, the escaping is correctly handled hierarchically. Each subtask level removes one layer of escaping, enabling correct mention behavior at the intended depth.

Implementation

1. Mention Parsing (src/shared/context-mentions.ts)

   • The mention parser now includes a negative lookbehind (?<!\\) in the regex to ignore escaped @ symbols.
   • Tests updated to confirm that \@foo is ignored and \\@foo is interpreted as @foo.

2. Subtask Unescaping (src/core/tools/newTaskTool.ts)

   • In newTaskTool, \\@ is converted to \@ before initializing the subtask.
   • This ensures each subtask layer peels off one escape level, preserving intended mentions.

3. Tests (src/core/tools/__tests__/newTaskTool.test.ts)

   • Added tests to verify correct behavior with one or more levels of escaping (\@, \\@, \\\\@).
   • Confirms proper transformation and message integrity across nested tasks.

How to Test

Example 1:
Prompt: Return the content of \@/file.txt

• Result: The file is not expanded directly. Roo uses read_file to load it.

Example 2:
Prompt: Create a new task for code mode and return the content of \@/file.txt

• Result: The parent task skips mention expansion. The subtask receives @/file.txt and resolves it.

---

Important

Enhances context mention handling by allowing escaping with backslashes and supports hierarchical un-escaping in subtasks.

• Behavior:
  • Allows escaping of context mentions by prefixing with \ in context-mentions.ts.
  • Hierarchical un-escaping in newTaskTool for subtasks, removing one level of escaping per subtask.
• Regex:
  • Modified mentionRegex in context-mentions.ts to include negative lookbehind (?<!\\) to ignore escaped mentions.
• Testing:
  • Added tests in context-mentions.test.ts for escaped mentions.
  • Added tests in newTaskTool.test.ts for hierarchical un-escaping logic.
• Misc:
  • Updated newTaskTool to process messages with hierarchical un-escaping before task initialization.

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: 46623124bdb2582682d2efab13ff33866f339b8d

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

[ellipsis-dev]

Consider adding additional tests for error handling scenarios such as missing mode or message, invalid mode, and approval denial. This would improve test coverage and ensure robust error handling as per our standards.

^{This comment was generated because it violated the following rules: mrule_oAUXVfj5l9XxF01R and mrule_OR1S8PRRHcvbdFib.}

[KJ7LNW]

does it remove the \ after processing the input?

\@foo must reach the model as @foo
\\@foo must reach the model as \@foo
\\\@foo must reach the model as \\@foo

etc.

[cannuri]

does it remove the \ after processing the input?

\@foo must reach the model as @foo \\@foo must reach the model as \@foo \\\@foo must reach the model as \\@foo

etc.

it reaches the subtask with one \ subtracted

[hannesrudolph]

@cannuri
This PR acts as a band-aid and doesn’t address the underlying issue. The root cause is properly resolved by PR #3086. Closing this one in favor of that fix. Thanks for your effort here!

[KJ7LNW]

@cannuri This PR acts as a band-aid and doesn’t address the underlying issue. The root cause is properly resolved by PR #3086. Closing this one in favor of that fix. Thanks for your effort here!

I think you are missing something that this also fixes:

currently it is impossible to pass the following text directly to a model @foo which is especially important when users need to instruct the model to create mentions in things like pull requests and other purposes.

This PR is nice and simple and allows recursive escaping \@/foo ... \\@/foo ... \\\@/foo

I am fine with what #3086 does (I just reviewed it and I like it), but this pull request is fundamentally about making sure we do not prevent certain kinds of input from being passed to the model.

[KJ7LNW]

@hannesrudolph, please see the previous message: I am going to reopen this so it does not get lost.

if there have been recent changes and you really can not pass things like @/foo to a model without unexpected interpetation, then this could be closed but I do not believe that is the case.

[cannuri]

Yes, documentation shouldn't be forgotten. Maybe add it to the Tips & Tricks section.
We could also add a Escape-Button to the popup when you type "@".

both of those are great ideas

Glad you like it. So is that decided then? @hannesrudolph fine for you?

[hannesrudolph]

Yes

[cannuri]

@daniel-lxs I noticed that all the options in the menu (when typing @) are hard coded english strings. Shall I translate them on the way? or shall I hard code the new option as well?

[daniel-lxs]

@cannuri

Do you think it would be too much work to create an issue and PR to translate them?
And maybe have that merged before this? If it is, then I think you can just hard code them like the rest for now.

[cannuri]

@cannuri

Do you think it would be too much work to create an issue and PR to translate them? And maybe have that merged before this? If it is, then I think you can just hard code them like the rest for now.

@daniel-lxs Can do, but I would suggest to get this one merged first, no?

[mrubens]

Is the failing test legit?

[hannesrudolph]

Yes

I thought you were just asking me if the overall PR was given the green light. The change to the UI blurs concerns and is not good practice as it strays from the original issue this was approved based off of.

[KJ7LNW]

As requested by @hannesrudolph, I have split off the core functionality for escaping context mentions into a separate PR #4362, which focuses solely on implementing the escaping mechanism without UI changes.

@cannuri, would you please create a new issue and pull request for the UI changes?

Closed by #4362 pending new issue+pr for UI.