Gemini CLI Policy Engine: Control Tool Calls with TOML Rules

Gemini CLI’s policy engine decides, rule by rule, whether a tool call is allowed, denied or sent to you for confirmation. You write the rules as [[rule]] blocks in .toml files under ~/.gemini/policies/; Gemini CLI loads and combines every .toml file in that directory, and the highest-priority matching rule wins (policy engine reference).

Applies to: Gemini CLI 0.66.0 (npm), policy engine reference as published on geminicli.com. Last checked: November 1, 2026.

On this page

Your first rule

The documentation’s quick start creates the user policy directory and a rule that blocks rm -rf in the shell tool (quick start):

mkdir -p ~/.gemini/policies

On Windows (PowerShell):

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.gemini\policies"

Then save any file ending in .toml there, for example ~/.gemini/policies/my-rules.toml:

[[rule]]
toolName = "run_shell_command"
commandPrefix = "rm -rf"
decision = "deny"
priority = 100

The three decisions

Each rule ends in one decision (decisions):

Google recommends a deny rule for excluding tools; the older tools.exclude setting in settings.json is deprecated in its favour (decisions).

What a rule can match

A rule applies only when all its conditions match (TOML rule schema):

• toolName: a built-in tool name, an array of names, or a wildcard such as * (any tool) or mcp_* (any MCP tool). Built-in names and their argument keys are listed in the tools reference.
• argsPattern: a regular expression tested against the tool’s arguments serialized as a stable JSON string.
• commandPrefix / commandRegex: shorthands for run_shell_command. They are policy fields, not arguments of the shell tool, and cannot be used together in one rule.
• mcpName, subagent, toolAnnotations: the MCP server, the calling subagent, or tool metadata hints.
• modes: the approval modes where the rule is active (default, autoEdit, plan, yolo); omitted means all modes.
• interactive: true limits the rule to interactive sessions, false to headless runs.

Two optional fields change what happens on a match: denyMessage is returned to the model and the user when the rule blocks a call, and allowRedirection = true lets a matching shell command use >, >>, <, << or <<<, which otherwise triggers a confirmation even when a rule matches (schema).

One rule can cover several tools with an array, as in the documentation’s example (using arrays):

[[rule]]
toolName = ["write_file", "replace"]
decision = "ask_user"
priority = 10

MCP tools: use mcpName

For MCP servers the documentation recommends the mcpName field over hand-written fully qualified names. With mcpName, toolName is the tool’s simple name (MCP syntax):

# Allows the `search` tool on the `my-jira-server` MCP
[[rule]]
mcpName = "my-jira-server"
toolName = "search"
decision = "allow"
priority = 200

Leaving out toolName applies the rule to every tool on that server, and mcpName = "*" targets all MCP servers. Google warns against underscores in MCP server names: the parser splits mcp_server_tool on the first underscore after mcp_, so my_server can be misread and wildcard or security rules can fail silently. Use my-server instead (MCP syntax).

Where policies live and which one wins

Within a file, priority runs from 0 to 999 and higher wins. Across files, tiers decide first: Admin overrides User, User overrides Workspace and Extension, and all of them override the built-in Default policies (priority system and tiers).

The workspace tier is marked non-functional: policies in a project’s .gemini/policies directory have no effect, and Google says to use User or Admin policies instead (issue #18186).

The standard admin directory is ignored if it fails security checks. On Linux and macOS it must be owned by root and not writable by group or others; on Windows standard users must not have Write, Modify or Full Control. Extra admin paths can be passed with --admin-policy or the adminPolicyPaths setting, but they are ignored when the standard system location already contains .toml policy files (system-wide policies). The policyPaths and adminPolicyPaths settings both require a restart (configuration reference).

Extensions can ship rules in a policies/ directory. They sit below user and admin policies, and Gemini CLI ignores any allow decisions or yolo mode configuration in extension policies, so an extension cannot auto-approve tool calls (extension reference).