feat(workspace): support tool name remapping in workspace tools config (#13687)

## Summary

- Adds a `name` property to `WorkspaceToolConfig` so workspace tools can
be exposed under custom names to the LLM
- Mastracode uses this to remap workspace tools back to its original
names (`view`, `search_content`, `string_replace_lsp`, etc.) so they
match the tool guidance prompts
- Removes hardcoded tool-name cross-references from `edit-file` and
`ast-edit` descriptions/output, since tools can be renamed or disabled
- Extracts tool names into `MC_TOOLS` constants and
`TOOL_NAME_OVERRIDES` mapping in `mastracode/src/tool-names.ts` for
reuse across permissions, TUI, subagents, and tool guidance
- Fixes pre-existing test failures in mastracode's `extra-tools.test.ts`
that still expected workspace tools in `createDynamicTools()` output

## Test plan

- [x] All 19 core workspace tool creation tests pass (including 6 new
name remapping tests)
- [x] All 14 mastracode extra-tools tests pass
- [x] Core and mastracode packages build cleanly
- [x] Verify mastracode works end-to-end with remapped tool names

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
* Tools can now be exposed under custom names while maintaining their
original configuration identifiers.

* **Documentation**
* Updated tool descriptions to remove implementation-specific references
for improved clarity.

* **Refactor**
* Standardized tool name references throughout the codebase for
consistency and maintainability.

* **Tests**
* Added comprehensive test coverage for custom tool name remapping
scenarios.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: CalebBarnes <CalebBarnes@users.noreply.github.com>

Author: CalebBarnes

.changeset/open-crews-lie.md

@@ -0,0 +1,18 @@
+---
+'@mastra/core': minor
+---
+
+Added `name` property to `WorkspaceToolConfig` for remapping workspace tool names. Tools can now be exposed under custom names to the LLM while keeping the original constant as the config key.
+
+```typescript
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './project' }),
+  tools: {
+    mastra_workspace_read_file: { name: 'view' },
+    mastra_workspace_grep: { name: 'search_content' },
+    mastra_workspace_edit_file: { name: 'string_replace_lsp' },
+  },
+});
+```
+
+Also removed hardcoded tool-name cross-references from edit-file and ast-edit tool descriptions, since tools can be renamed or disabled.

.changeset/perky-glasses-make.md

@@ -0,0 +1,5 @@
+---
+'mastracode': patch
+---
+
+Workspace tool names are now remapped to canonical names (`view`, `search_content`, `string_replace_lsp`, etc.) so they match tool guidance prompts, permissions, and TUI rendering.

mastracode/src/agents/__tests__/extra-tools.test.ts

@@ -4,6 +4,7 @@ import { describe, it, expect } from 'vitest';
 import z from 'zod';
 
 import { getToolCategory } from '../../permissions.js';
+import { MC_TOOLS } from '../../tool-names.js';
 import { buildToolGuidance } from '../prompts/tool-guidance.js';
 import { createDynamicTools } from '../tools.js';
 
@@ -43,26 +44,23 @@ describe('createDynamicTools – extraTools', () => {
     expect(tools).toHaveProperty('my_custom_tool');
     expect(tools.my_custom_tool).toBe(myCustomTool);
 
-    // Built-in tools should still be present
-    expect(tools).toHaveProperty('view');
-    expect(tools).toHaveProperty('search_content');
-    expect(tools).toHaveProperty('find_files');
-    expect(tools).toHaveProperty('execute_command');
+    // Built-in non-workspace tools should still be present
+    expect(tools).toHaveProperty('request_sandbox_access');
   });
 
   it('should not overwrite built-in tools with extraTools of the same name', () => {
     const sneakyTool = createTool({
-      id: 'view',
-      description: 'Trying to overwrite the built-in view tool',
+      id: 'request_sandbox_access',
+      description: 'Trying to overwrite the built-in request_sandbox_access tool',
       inputSchema: z.object({}),
       execute: async () => ({ result: 'sneaky' }),
     });
 
-    const getDynamicTools = createDynamicTools(undefined, { view: sneakyTool });
+    const getDynamicTools = createDynamicTools(undefined, { request_sandbox_access: sneakyTool });
     const tools = getDynamicTools({ requestContext: makeRequestContext() });
 
-    // Built-in view should NOT be replaced by the extra tool
-    expect(tools.view).not.toBe(sneakyTool);
+    // Built-in request_sandbox_access should NOT be replaced by the extra tool
+    expect(tools.request_sandbox_access).not.toBe(sneakyTool);
   });
 
   it('should return extraTools even when no MCP manager is provided', () => {
@@ -90,9 +88,9 @@ describe('createDynamicTools – extraTools', () => {
     const getDynamicTools = createDynamicTools(undefined, undefined);
     const tools = getDynamicTools({ requestContext: makeRequestContext() });
 
-    // Should have built-in tools but nothing extra
-    expect(tools).toHaveProperty('view');
-    expect(tools).toHaveProperty('search_content');
+    // Should have built-in non-workspace tools but nothing extra
+    // Note: workspace tools (view, search_content, etc.) are provided by the workspace, not createDynamicTools
+    expect(tools).toHaveProperty('request_sandbox_access');
     expect(tools).not.toHaveProperty('my_custom_tool');
   });
 });
@@ -105,10 +103,10 @@ describe('getToolCategory – extra tools', () => {
   });
 
   it('should still categorize built-in tools correctly', () => {
-    expect(getToolCategory('view')).toBe('read');
-    expect(getToolCategory('search_content')).toBe('read');
-    expect(getToolCategory('string_replace_lsp')).toBe('edit');
-    expect(getToolCategory('execute_command')).toBe('execute');
+    expect(getToolCategory(MC_TOOLS.VIEW)).toBe('read');
+    expect(getToolCategory(MC_TOOLS.SEARCH_CONTENT)).toBe('read');
+    expect(getToolCategory(MC_TOOLS.STRING_REPLACE_LSP)).toBe('edit');
+    expect(getToolCategory(MC_TOOLS.EXECUTE_COMMAND)).toBe('execute');
   });
 
   it('should return null for always-allowed tools', () => {
@@ -123,31 +121,33 @@ describe('createDynamicTools – denied tool filtering', () => {
     const getDynamicTools = createDynamicTools();
     const tools = getDynamicTools({
       requestContext: makeRequestContext({
-        permissionRules: { categories: {}, tools: { execute_command: 'deny' } },
+        permissionRules: { categories: {}, tools: { request_sandbox_access: 'deny' } },
       }),
     });
 
-    expect(tools).not.toHaveProperty('execute_command');
-    // Other tools should still be present
-    expect(tools).toHaveProperty('view');
-    expect(tools).toHaveProperty('search_content');
+    expect(tools).not.toHaveProperty('request_sandbox_access');
   });
 
   it('should omit multiple denied tools', () => {
-    const getDynamicTools = createDynamicTools();
+    const myTool = createTool({
+      id: 'my_tool',
+      description: 'A custom tool',
+      inputSchema: z.object({}),
+      execute: async () => ({ result: 'custom' }),
+    });
+
+    const getDynamicTools = createDynamicTools(undefined, { my_tool: myTool });
     const tools = getDynamicTools({
       requestContext: makeRequestContext({
         permissionRules: {
           categories: {},
-          tools: { execute_command: 'deny', view: 'deny', find_files: 'deny' },
+          tools: { request_sandbox_access: 'deny', my_tool: 'deny' },
         },
       }),
     });
 
-    expect(tools).not.toHaveProperty('execute_command');
-    expect(tools).not.toHaveProperty('view');
-    expect(tools).not.toHaveProperty('find_files');
-    expect(tools).toHaveProperty('search_content');
+    expect(tools).not.toHaveProperty('request_sandbox_access');
+    expect(tools).not.toHaveProperty('my_tool');
   });
 
   it('should keep tools with allow or ask policies', () => {
@@ -156,13 +156,12 @@ describe('createDynamicTools – denied tool filtering', () => {
       requestContext: makeRequestContext({
         permissionRules: {
           categories: {},
-          tools: { execute_command: 'allow', view: 'ask' },
+          tools: { request_sandbox_access: 'allow' },
         },
       }),
     });
 
-    expect(tools).toHaveProperty('execute_command');
-    expect(tools).toHaveProperty('view');
+    expect(tools).toHaveProperty('request_sandbox_access');
   });
 
   it('should also deny extraTools when they have a deny policy', () => {
@@ -187,32 +186,32 @@ describe('createDynamicTools – denied tool filtering', () => {
 describe('buildToolGuidance – denied tool filtering', () => {
   it('should omit guidance for denied tools', () => {
     const guidance = buildToolGuidance('build', {
-      deniedTools: new Set(['execute_command']),
+      deniedTools: new Set([MC_TOOLS.EXECUTE_COMMAND]),
     });
 
-    expect(guidance).not.toContain('**execute_command**');
-    expect(guidance).toContain('**view**');
-    expect(guidance).toContain('**search_content**');
+    expect(guidance).not.toContain(`**${MC_TOOLS.EXECUTE_COMMAND}**`);
+    expect(guidance).toContain(`**${MC_TOOLS.VIEW}**`);
+    expect(guidance).toContain(`**${MC_TOOLS.SEARCH_CONTENT}**`);
   });
 
   it('should omit multiple denied tools from guidance', () => {
     const guidance = buildToolGuidance('build', {
-      deniedTools: new Set(['execute_command', 'write_file', 'subagent']),
+      deniedTools: new Set([MC_TOOLS.EXECUTE_COMMAND, MC_TOOLS.WRITE_FILE, 'subagent']),
     });
 
-    expect(guidance).not.toContain('**execute_command**');
-    expect(guidance).not.toContain('**write_file**');
+    expect(guidance).not.toContain(`**${MC_TOOLS.EXECUTE_COMMAND}**`);
+    expect(guidance).not.toContain(`**${MC_TOOLS.WRITE_FILE}**`);
     expect(guidance).not.toContain('**subagent**');
-    expect(guidance).toContain('**view**');
-    expect(guidance).toContain('**string_replace_lsp**');
+    expect(guidance).toContain(`**${MC_TOOLS.VIEW}**`);
+    expect(guidance).toContain(`**${MC_TOOLS.STRING_REPLACE_LSP}**`);
   });
 
   it('should include all tools when no denied set is provided', () => {
     const guidance = buildToolGuidance('build');
 
-    expect(guidance).toContain('**execute_command**');
-    expect(guidance).toContain('**view**');
-    expect(guidance).toContain('**string_replace_lsp**');
+    expect(guidance).toContain(`**${MC_TOOLS.EXECUTE_COMMAND}**`);
+    expect(guidance).toContain(`**${MC_TOOLS.VIEW}**`);
+    expect(guidance).toContain(`**${MC_TOOLS.STRING_REPLACE_LSP}**`);
     expect(guidance).toContain('**subagent**');
   });
 });

mastracode/src/agents/prompts/tool-guidance.ts

@@ -4,6 +4,8 @@
  * and are scoped to what's available in the current mode.
  */
 
+import { MC_TOOLS } from '../../tool-names.js';
+
 interface ToolGuidanceOptions {
   hasWebSearch?: boolean;
   /** Tool names that have been denied — omit their guidance sections. */
@@ -24,44 +26,44 @@ You have access to the following tools. Use the RIGHT tool for the job:`);
 
   const readTools: string[] = [];
 
-  if (!denied.has('view')) {
+  if (!denied.has(MC_TOOLS.VIEW)) {
     readTools.push(`
-**view** — Read file contents or list directories
+**${MC_TOOLS.VIEW}** — Read file contents or list directories
 - Use this to read files before editing them. NEVER propose changes to code you haven't read.
 - Use \`view_range\` for large files to read specific sections.
 - For directory listings, this shows 2 levels deep.
 - Example: To check lines 50-100 of a large file: \`view("src/big-file.ts", { view_range: [50, 100] })\``);
   }
 
-  if (!denied.has('search_content')) {
+  if (!denied.has(MC_TOOLS.SEARCH_CONTENT)) {
     readTools.push(`
-**search_content** — Search file contents using regex
+**${MC_TOOLS.SEARCH_CONTENT}** — Search file contents using regex
 - Use this for ALL content search (finding functions, variables, error messages, imports, etc.)
 - NEVER use \`execute_command\` with grep, rg, or ag. Always use the search_content tool.
 - Supports regex patterns, file type filtering, and context lines.
 - Example: Find where a function is defined: \`search_content("function handleSubmit", { glob: "**/*.ts" })\`
 - Example: Find all imports of a module: \`search_content("from ['\\"\\]express['\\"\\]", { glob: "**/*.ts" })\``);
   }
 
-  if (!denied.has('find_files')) {
+  if (!denied.has(MC_TOOLS.FIND_FILES)) {
     readTools.push(`
-**find_files** — Find files by name pattern
+**${MC_TOOLS.FIND_FILES}** — Find files by name pattern
 - Use this to find files matching a pattern (e.g., "**/*.ts", "src/**/test*").
 - NEVER use \`execute_command\` with find or ls for file search. Always use find_files.
 - Respects .gitignore automatically.
 - Example: Find all test files: \`find_files("**/*.test.ts")\`
 - Example: Find config files: \`find_files("**/config.{js,ts,json}")\``);
   }
 
-  if (!denied.has('execute_command')) {
+  if (!denied.has(MC_TOOLS.EXECUTE_COMMAND)) {
     readTools.push(`
-**execute_command** — Run shell commands
+**${MC_TOOLS.EXECUTE_COMMAND}** — Run shell commands
 - Use for: git, npm/pnpm, docker, build tools, test runners, and other terminal operations.
-- Do NOT use for: file reading (use view), file search (use search_content/find_files), file editing (use string_replace_lsp/write_file).
+- Do NOT use for: file reading (use ${MC_TOOLS.VIEW}), file search (use ${MC_TOOLS.SEARCH_CONTENT}/${MC_TOOLS.FIND_FILES}), file editing (use ${MC_TOOLS.STRING_REPLACE_LSP}/${MC_TOOLS.WRITE_FILE}).
 - Commands have a 30-second default timeout. Use the \`timeout\` parameter for longer-running commands.
 - Pipe to \`| tail -N\` for commands with long output — the full output streams to the user, only the last N lines are returned to you. If you're building any kind of package you should be tailing.
 - Good: Run independent commands in parallel when possible.
-- Bad: Running \`cat file.txt\` — use the view tool instead.`);
+- Bad: Running \`cat file.txt\` — use the ${MC_TOOLS.VIEW} tool instead.`);
   }
 
   if (readTools.length > 0) {
@@ -73,22 +75,22 @@ You have access to the following tools. Use the RIGHT tool for the job:`);
   if (modeId !== 'plan') {
     const writeTools: string[] = [];
 
-    if (!denied.has('string_replace_lsp')) {
+    if (!denied.has(MC_TOOLS.STRING_REPLACE_LSP)) {
       writeTools.push(`
-**string_replace_lsp** — Edit files by replacing exact text
-- You MUST read a file with \`view\` before editing it.
+**${MC_TOOLS.STRING_REPLACE_LSP}** — Edit files by replacing exact text
+- You MUST read a file with \`${MC_TOOLS.VIEW}\` before editing it.
 - \`old_str\` must be an exact match of existing text in the file.
 - Provide enough surrounding context in \`old_str\` to make it unique.
-- For creating new files, use \`write_file\` instead.
+- For creating new files, use \`${MC_TOOLS.WRITE_FILE}\` instead.
 - Good: Include 2-3 lines of surrounding context to ensure uniqueness.
 - Bad: Using just \`return true;\` — too common, will match multiple places.`);
     }
 
-    if (!denied.has('write_file')) {
+    if (!denied.has(MC_TOOLS.WRITE_FILE)) {
       writeTools.push(`
-**write_file** — Create new files or overwrite existing ones
+**${MC_TOOLS.WRITE_FILE}** — Create new files or overwrite existing ones
 - Use this to create new files.
-- If overwriting an existing file, you MUST have read it first with \`view\`.
+- If overwriting an existing file, you MUST have read it first with \`${MC_TOOLS.VIEW}\`.
 - NEVER create files unless necessary. Prefer editing existing files.`);
     }
 

mastracode/src/agents/subagents/audit-tests.ts

@@ -5,6 +5,7 @@
  * explores the repo's existing testing conventions, and produces
  * a detailed audit report with actionable improvement recommendations.
  */
+import { MC_TOOLS } from '../../tool-names.js';
 import type { SubagentDefinition } from './types.js';
 
 export const auditTestsSubagent: SubagentDefinition = {
@@ -117,5 +118,5 @@ Prioritized, actionable list. Most impactful improvements first. Be specific —
 - Ground all feedback in the repo's actual conventions, not generic best practices.
 - Be direct. If tests are sloppy, say so. If they're good, say that too.
 - Focus on **actionable feedback** — every finding should have a clear "do this instead" recommendation.`,
-  allowedTools: ['view', 'search_content', 'find_files'],
+  allowedTools: [MC_TOOLS.VIEW, MC_TOOLS.SEARCH_CONTENT, MC_TOOLS.FIND_FILES],
 };

mastracode/src/agents/subagents/execute.ts

@@ -5,6 +5,7 @@
  * read and write tools to complete it. It can modify files, run commands,
  * and perform actual development work within a constrained scope.
  */
+import { MC_TOOLS } from '../../tool-names.js';
 import type { SubagentDefinition } from './types.js';
 
 export const executeSubagent: SubagentDefinition = {
@@ -45,14 +46,14 @@ End with a structured summary:
 . **Notes**: Follow-up needed (if any)`,
   allowedTools: [
     // Read tools
-    'view',
-    'search_content',
-    'find_files',
+    MC_TOOLS.VIEW,
+    MC_TOOLS.SEARCH_CONTENT,
+    MC_TOOLS.FIND_FILES,
     // Write tools
-    'string_replace_lsp',
-    'write_file',
+    MC_TOOLS.STRING_REPLACE_LSP,
+    MC_TOOLS.WRITE_FILE,
     // Execution tool
-    'execute_command',
+    MC_TOOLS.EXECUTE_COMMAND,
     // Task tracking (built-in harness tools)
     'task_write',
     'task_check',

mastracode/src/agents/subagents/explore.ts

@@ -5,6 +5,7 @@
  * "understand how module Y works") and uses read-only tools to explore
  * the codebase, then returns a concise summary of its findings.
  */
+import { MC_TOOLS } from '../../tool-names.js';
 import type { SubagentDefinition } from './types.js';
 
 export const exploreSubagent: SubagentDefinition = {
@@ -36,5 +37,5 @@ End with a structured summary:
 . **Details**: Additional context if needed
 
 Keep your summary under 300 words.`,
-  allowedTools: ['view', 'search_content', 'find_files'],
+  allowedTools: [MC_TOOLS.VIEW, MC_TOOLS.SEARCH_CONTENT, MC_TOOLS.FIND_FILES],
 };

mastracode/src/agents/subagents/plan.ts

@@ -5,6 +5,7 @@
  * implementation plan. It can read the codebase to understand existing
  * patterns and architecture, but cannot modify anything.
  */
+import { MC_TOOLS } from '../../tool-names.js';
 import type { SubagentDefinition } from './types.js';
 
 export const planSubagent: SubagentDefinition = {
@@ -38,5 +39,5 @@ Structure your plan as:
 . **Risks**: Potential issues or edge cases (if any)
 
 Be specific about code locations (file paths, function names, line numbers). Keep the plan actionable and under 500 words.`,
-  allowedTools: ['view', 'search_content', 'find_files'],
+  allowedTools: [MC_TOOLS.VIEW, MC_TOOLS.SEARCH_CONTENT, MC_TOOLS.FIND_FILES],
 };