# How Roo Code Enforces Tool Group Restrictions and File Patterns in Its Mode System

> Discover how Roo Code's mode system enforces tool group restrictions and file patterns using alias resolution and runtime overrides for strict access controls. Learn more today.

- Repository: [Roo Code/Roo-Code](https://github.com/RooCodeInc/Roo-Code)
- Tags: internals
- Published: 2026-04-26

---

**Roo Code uses a mode‑centric permission model that cross‑references mode configurations with tool group memberships, alias resolution, and runtime overrides to enforce strict access controls, while file‑pattern limits are applied per‑call via ripgrep glob arguments.**

The **Roo Code** mode system, as implemented in the `RooCodeInc/Roo‑Code` repository, provides a granular sandbox for AI assistant capabilities. By defining which **tool groups** each mode may access and enforcing **file pattern** restrictions at the tool‑execution layer, the system ensures that agents operate within their intended boundaries.

## The Mode-Centric Permission Architecture

Roo Code’s enforcement mechanism rests on a validation pipeline that translates high‑level mode configurations into concrete runtime permissions. The process involves canonical group definitions, alias resolution, and multi‑layered filtering before any tool reaches the LLM context.

### Canonical Tool Groups and Schema Definitions

The foundation of the permission model is the `toolGroups` array defined in the shared types package:

```typescript
export const toolGroups = ["read", "edit", "command", "mcp", "modes"] as const

```

This declaration in [`packages/types/src/tool.ts`](https://github.com/RooCodeInc/Roo-Code/blob/main/packages/types/src/tool.ts) **L07‑L10** establishes the valid group namespaces that modes can request. Each group represents a logical collection of native tools—for example, the `edit` group contains file‑modifying utilities, while `read` covers inspection tools.

### Expanding Mode Groups to Concrete Tool Lists

When a user selects a mode, the system expands the mode’s configured groups into an explicit list of tool names via `getToolsForMode(modeConfig.groups)`. This expansion occurs in `src/core/prompts/tools/filter‑tools‑for‑mode.ts` **L45‑L46**, where group entries (which may be simple strings or tuples with options) are resolved into the full set of tools implied by those groups.

### Validating Tools Against Mode Permissions

The core enforcement logic resides in `isToolAllowedForMode`, which validates whether a specific tool belongs to one of the mode’s enabled groups. During the filtering process in `filter‑tools‑for‑mode.ts` **L48‑L60**, the system:

1. Iterates over `allToolsForMode`.
2. Resolves any aliases to canonical names.
3. Calls `isToolAllowedForMode` (implemented in [`src/core/tools/validateToolUse.ts`](https://github.com/RooCodeInc/Roo-Code/blob/main/src/core/tools/validateToolUse.ts)) to verify the tool’s group membership against the mode’s whitelist.

If a tool does not belong to an allowed group, it is excluded from the final set.

### Alias Resolution Before Validation

To maintain backward compatibility without breaking security boundaries, Roo Code resolves legacy tool names before validation. The `ALIAS_TO_CANONICAL` map—built from `TOOL_ALIASES` at module load time in **L14‑L22**—translates aliases like `search_and_replace` to their canonical equivalents (e.g., `edit`).

During the construction of `allowedToolNames` in **L96‑L99**, `resolveToolAlias` ensures that even when an LLM requests a tool by its legacy name, the permission check evaluates against the canonical group membership.

### Runtime Overrides and Final Whitelist Construction

After establishing the base tool set, `filterNativeToolsForMode` applies several conditional filters to produce the final runtime whitelist:

- **Model customizations**: `applyModelToolCustomization` adds or removes tools based on the specific LLM’s capabilities.
- **Feature flags**: Code like `allowedToolNames.delete("codebase_search")` in **L71‑L77** removes tools when prerequisite services (such as the code‑index) are unavailable.
- **User settings**: Blocks checking `settings?.disabledTools?.length` in **L94‑L100** prune tools explicitly disabled by the user.
- **MCP availability**: Lines **L04‑L07** verify that MCP tools are only included when the MCP hub is active.

The result is a `Set<string>` of `allowedToolNames` that represents the definitive boundary of what the assistant may invoke.

## File Pattern Enforcement in Search Operations

Beyond group‑level restrictions, Roo Code enforces **file‑pattern** limits at the individual tool‑call level, particularly for the `search_files` utility.

### The search_files Tool Interface

The `search_files` tool accepts an optional `file_pattern` parameter that constrains the search scope:

```typescript
interface SearchFilesParams {
  path: string
  regex: string
  file_pattern?: string | null   // optional glob pattern
}

```

In [`src/core/tools/SearchFilesTool.ts`](https://github.com/RooCodeInc/Roo-Code/blob/main/src/core/tools/SearchFilesTool.ts) **L58‑L60**, the implementation forwards this parameter unchanged to the underlying search service:

```typescript
const results = await regexSearchFiles(
  task.cwd,
  absolutePath,
  regex,
  filePattern,                 // forwarded to ripgrep
  task.rooIgnoreController
);

```

### Ripgrep Glob Filtering

The actual enforcement occurs in [`src/services/ripgrep/index.ts`](https://github.com/RooCodeInc/Roo-Code/blob/main/src/services/ripgrep/index.ts). When `filePattern` is provided, the service converts it into a `--glob` argument for the `rg` command:

```typescript
// Inside ripgrep service, lines L21‑L23 and L157‑L158
const rgArgs = ["--glob", filePattern, ...];

```

This ensures that even if a mode grants access to `search_files`, the operation is physically restricted to files matching the glob pattern (for example, `**/*.ts` limits results to TypeScript files).

## Complete Runtime Flow

The enforcement pipeline operates sequentially during mode activation:

1. **Mode selection**: The user selects a mode (or a custom mode is inferred), triggering `filterNativeToolsForMode` with the current mode slug, custom definitions, experiment flags, and service states.
2. **Group expansion**: Mode groups are expanded to tool lists via `getToolsForMode`.
3. **Alias resolution**: Tool names are normalized using `ALIAS_TO_CANONICAL`.
4. **Permission validation**: `isToolAllowedForMode` filters the list to only those tools belonging to enabled groups.
5. **Override application**: Model customizations, disabled tool lists, and feature flags prune the set further.
6. **Tool exposure**: The resulting array of `OpenAI.Chat.ChatCompletionTool` objects is injected into the LLM context.
7. **Per‑call enforcement**: When the assistant invokes `search_files`, the optional `file_pattern` is validated and passed to ripgrep, which applies the `--glob` filter at the filesystem level.

## Key Implementation Files

- **[`packages/types/src/tool.ts`](https://github.com/RooCodeInc/Roo-Code/blob/main/packages/types/src/tool.ts)**: Defines canonical `toolGroups`, tool names, and Zod schemas (**L07‑L10**).
- **`src/core/prompts/tools/filter‑tools‑for‑mode.ts`**: Orchestrates whitelist construction, alias resolution, and runtime filtering (**L45‑L100**).
- **[`src/core/tools/validateToolUse.ts`](https://github.com/RooCodeInc/Roo-Code/blob/main/src/core/tools/validateToolUse.ts)**: Provides `isToolAllowedForMode` for group‑membership validation.
- **[`src/core/tools/SearchFilesTool.ts`](https://github.com/RooCodeInc/Roo-Code/blob/main/src/core/tools/SearchFilesTool.ts)**: Implements `search_files` and forwards patterns to the ripgrep service (**L58‑L60**).
- **[`src/services/ripgrep/index.ts`](https://github.com/RooCodeInc/Roo-Code/blob/main/src/services/ripgrep/index.ts)**: Executes searches with `--glob` arguments when file patterns are specified (**L21‑L23**, **L157‑L158**).

## Summary

- **Roo Code** enforces tool access through a **mode‑centric permission model** that validates every tool against configurable group memberships.
- The **`filterNativeToolsForMode`** function in `src/core/prompts/tools/filter‑tools‑for‑mode.ts` constructs the runtime whitelist by expanding mode groups, resolving aliases, and applying model‑specific and user‑specific overrides.
- **Alias resolution** occurs before validation, ensuring legacy tool names are mapped to canonical groups without bypassing restrictions.
- **File‑pattern restrictions** are enforced at the execution layer; the `search_files` tool forwards glob patterns to ripgrep, which filters results via `--glob` arguments.
- The entire pipeline ensures that even if an LLM attempts to invoke a restricted tool or access excluded files, the operation is blocked by the mode configuration or the filesystem search boundary.

## Frequently Asked Questions

### How does `filterNativeToolsForMode` determine which tools are available?

The function first calls `getToolsForMode(modeConfig.groups)` to expand the mode’s groups into concrete tool names (**L45‑L46**). It then iterates over these candidates, uses `isToolAllowedForMode` to verify group membership (**L48‑L60**), and applies subsequent filters for disabled tools, model customizations, and MCP availability (**L71‑L100**). The result is a deduplicated array of tools the LLM is permitted to call.

### What happens when a tool alias is used in a mode‑restricted context?

Before validation, the system checks the `ALIAS_TO_CANONICAL` map (constructed from `TOOL_ALIASES` at **L14‑L22**) to resolve the alias to its canonical name. For example, `search_and_replace` resolves to `edit`. The permission check then evaluates against the canonical group, ensuring aliases cannot bypass group restrictions while preserving backward compatibility (**L96‑L99**).

### How does Roo Code handle file pattern restrictions in `search_files`?

The `search_files` tool accepts an optional `file_pattern` parameter that is forwarded directly to `regexSearchFiles` in [`src/core/tools/SearchFilesTool.ts`](https://github.com/RooCodeInc/Roo-Code/blob/main/src/core/tools/SearchFilesTool.ts) (**L58‑L60**). The ripgrep service in [`src/services/ripgrep/index.ts`](https://github.com/RooCodeInc/Roo-Code/blob/main/src/services/ripgrep/index.ts) converts this into a `--glob` argument for the underlying `rg` command (**L21‑L23**), filtering the search to matching paths only.

### Can model‑specific customizations override mode‑based tool restrictions?

Yes. After the mode‑based whitelist is constructed, `filterNativeToolsForMode` invokes `applyModelToolCustomization` to add or remove tools based on the specific LLM’s capabilities. However, this occurs **after** the mode group validation, meaning model customizations can only further restrict or supplement the base set; they cannot grant access to tools outside the mode’s allowed groups unless explicitly intended by the broader override logic.