fix(claude-code): workaround reserved tool name collision (read_file)

[loject]

Related GitHub Issue

Closes: #10867

Roo Code Task Context (Optional)

Description

Claude Code OAuth API requests fail when a tool is named read_file.
This PR adds a small workaround by renaming the tool before sending it to Claude Code (e.g. read_file → _read_file).

Notes for reviewers:

• This appears to be a reserved-name collision / backend validation issue on the Claude Code side.
• The change is intentionally minimal and only affects the tool name used in the outgoing request, keeping the tool schema unchanged otherwise.

Test Procedure

1. Open Roo Code and sign in via Claude Code OAuth.
2. Trigger any request that includes the read_file tool (e.g. ask Roo Code to read a file from the workspace).
3. Verify the request succeeds (previously failed before this change).
4. Optionally confirm that tool calls still work as expected after the rename workaround.

Pre-Submission Checklist

• Issue Linked: This PR is linked to an approved GitHub Issue (see "Related GitHub Issue" above).
• Scope: My changes are focused on the linked issue (one major feature/fix per PR).
• Self-Review: I have performed a thorough self-review of my code.
• Testing: New and/or updated tests have been added to cover my changes (if applicable).
• Documentation Impact: I have considered if my changes require documentation updates (see "Documentation Updates" section below).
• Contribution Guidelines: I have read and agree to the Contributor Guidelines.

Screenshots / Videos

Documentation Updates

Additional Notes

If the Claude Code OAuth gateway treats read_file as a reserved/system tool name, this workaround prevents collisions while keeping Roo Code behavior unchanged for users.

Get in Touch

Discord: loject

---

Important

Fixes tool name collision in Claude Code OAuth by renaming read_file to _read_file in claude-code.ts.

• Behavior:
  • Adds patchReservedAnthropicToolNames() and unpatchToolName() functions in claude-code.ts to rename read_file tool to _read_file before sending requests.
  • Updates createMessage() in ClaudeCodeHandler to apply the renaming workaround for reserved tool names.
• Misc:
  • Adds constants RESERVED_ANTHROPIC_TOOL_NAMES and RESERVED_ANTHROPIC_TOOL_PREFIX in claude-code.ts for managing reserved tool names.

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

[roomote]

Rooviewer   See task on Roo Cloud

Review Completed

No new issues found. The latest commit (cb99814) improves the previous fix by:

1. Type safety: Changed unpatchToolName() to properly handle undefined names (continuation chunks in tool call streaming don't include the name field)
2. Exports for testability: Made constants and helper functions available for testing
3. Test coverage: Added 13 comprehensive unit tests covering all edge cases

The workaround for the Claude Code OAuth reserved tool name collision (read_file -> _read_file) is working correctly.

Previous reviews

• 9abd227: Review #1

_{Mention @roomote in a comment to request specific changes to this pull request or fix all unresolved issues.}

[roomote]

Review Summary

Overall Assessment: ✅ Approved with suggested improvements

This PR provides a solid workaround for the Claude Code OAuth API reserved tool name collision issue. The implementation is clean and well-documented. I've identified a few improvements and have pushed fixes along with comprehensive test coverage.

---

Issues Identified & Fixed

1. Type Safety Issue (Fixed)

The original code had an unsafe type assertion on line 282:

name: unpatchToolName(chunk.name as string, reverseNameMap),

The chunk.name can be undefined for continuation chunks in tool call streaming (as documented in StreamToolCallPartialChunk). The as string cast masked this, which could lead to unexpected runtime behavior.

Fix applied:

• Updated unpatchToolName() to accept string | undefined and return string | undefined
• Removed the unsafe type assertion

2. Missing Unit Tests (Added)

The PR description noted that testing was not complete. I've added comprehensive unit tests for:

• patchReservedAnthropicToolNames() - 5 test cases covering reserved/non-reserved names, empty arrays, and property preservation
• unpatchToolName() - 4 test cases including undefined handling
• Integration tests for tool name handling in streaming

All 35 tests now pass ✅

3. Exported Functions for Testability

The helper functions and constants are now exported so they can be properly tested:

• RESERVED_ANTHROPIC_TOOL_NAMES
• RESERVED_ANTHROPIC_TOOL_PREFIX
• patchReservedAnthropicToolNames()
• unpatchToolName()

---

Suggested Follow-up (Not blocking)

The tool_use blocks in conversation history messages are not currently patched. When a follow-up request is sent with previous assistant messages containing tool_use blocks:

• The tool definitions will have the prefixed name (_read_file)
• The tool_use blocks in history may have the original name (read_file)

This could potentially cause mismatches. If issues arise in multi-turn conversations with the read_file tool, consider also patching tool_use block names in the messages array before sending.

---

Changes Made in This Review

1. Fixed type signature of unpatchToolName() to handle undefined
2. Removed unsafe as string cast
3. Exported functions/constants for testability
4. Added 13 new unit tests for the patching functionality

Great work on this fix! 🎉

[roomote]

Suggested Changes

I've pushed the review fixes to a branch that you can cherry-pick or merge:

Branch: RooCodeInc/Roo-Code:fix/claude-code-read-file-tool-name
Commit: cb99814

Summary of Changes

1. Fixed type safety issue in unpatchToolName():

   • Changed signature from (name: string, ...) to (name: string | undefined, ...)
   • Properly handles undefined tool names in continuation chunks
   • Removed the unsafe as string cast

2. Exported functions for testability:

   • RESERVED_ANTHROPIC_TOOL_NAMES
   • RESERVED_ANTHROPIC_TOOL_PREFIX
   • patchReservedAnthropicToolNames()
   • unpatchToolName()

3. Added 13 unit tests covering:

   • Reserved tool name patching
   • Non-reserved tool name pass-through
   • Empty arrays and property preservation
   • Undefined name handling
   • Integration tests for streaming

To Apply These Changes

You can fetch and cherry-pick my commit:

git fetch https://github.com/RooCodeInc/Roo-Code.git fix/claude-code-read-file-tool-name
git cherry-pick cb99814e7

Or view the diff: 9abd227...cb99814