Policy Engine Builder

🚨 MANDATORY: Invoke gemini-cli-docs First

STOP - Before providing ANY response about Gemini policy engine:

1. INVOKE gemini-cli-docs skill
2. QUERY for the specific policy topic
3. BASE all responses EXCLUSIVELY on official documentation loaded

Overview

This skill provides guidance for configuring Gemini CLI's Policy Engine using TOML rules. The policy engine controls tool execution with fine-grained allow/deny/ask rules.

When to Use This Skill

Keywords: policy engine, policy toml, tool policy, allow deny, gemini rules, security policy, mcp policy

Use this skill when:

• Restricting which tools Gemini can use
• Creating enterprise security policies
• Controlling MCP server permissions
• Setting up approval workflows
• Auditing tool execution rules

Policy File Locations

User Policies

~/.gemini/policies/
├── default.toml          # User default rules
└── security.toml         # Additional security rules

Project Policies

.gemini/policies/
├── project.toml          # Project-specific rules
└── team.toml             # Team conventions

System Policies (Enterprise)

/etc/gemini-cli/policies/         # Linux
/Library/Application Support/GeminiCli/policies/  # macOS
C:\ProgramData\gemini-cli\policies\               # Windows

Rule Structure

Basic Rule

[[rule]]
toolName = "run_shell_command"
decision = "ask_user"
priority = 100

Rule Fields

Field	Type	Description
toolName	string/array	Tool name(s) to match
mcpName	string	MCP server name
argsPattern	string	Regex for tool arguments
commandPrefix	string/array	Shell command prefix(es)
commandRegex	string	Regex for shell commands
decision	string	allow, deny, or ask_user
priority	number	0-999 within tier
modes	array	Optional: yolo, autoEdit

Decision Types

Allow

Automatically approve without prompting:

[[rule]]
toolName = "read_file"
decision = "allow"
priority = 100

Deny

Block execution entirely:

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

Ask User

Prompt for confirmation:

[[rule]]
toolName = "write_file"
decision = "ask_user"
priority = 100

Priority System

Three Tiers

Tier	Base	Source
Default	1	Built-in defaults
User	2	User policies
Admin	3	System/enterprise

Priority Calculation

The formula is: final_priority = tier_base + (toml_priority / 1000)

Example:

• User rule with priority 100 → 2 + (100/1000) = 2.100
• Admin rule with priority 50 → 3 + (50/1000) = 3.050

Higher tier always wins, then higher priority within tier.

Priority Guidelines

Priority	Use Case
0-99	Low priority defaults
100-499	Normal rules
500-799	Important restrictions
800-999	Critical security rules

Tool Matching

Single Tool

[[rule]]
toolName = "run_shell_command"
decision = "ask_user"

Multiple Tools

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

All Tools

[[rule]]
toolName = "*"
decision = "ask_user"

Shell Command Patterns

Command Prefix

# Match commands starting with "git"
[[rule]]
toolName = "run_shell_command"
commandPrefix = "git "
decision = "allow"
priority = 100

Multiple Prefixes

[[rule]]
toolName = "run_shell_command"
commandPrefix = ["npm ", "yarn ", "pnpm "]
decision = "allow"
priority = 100

Command Regex

# Match destructive commands
[[rule]]
toolName = "run_shell_command"
commandRegex = "^(rm|rmdir|del|rd)\\s"
decision = "deny"
priority = 999

Argument Patterns

JSON Argument Matching

Tool arguments are JSON strings:

# Deny writes to sensitive paths
[[rule]]
toolName = "write_file"
argsPattern = ".*\\.(env|key|pem|crt)$"
decision = "deny"
priority = 900

Complex Patterns

# Allow reads only from src/
[[rule]]
toolName = "read_file"
argsPattern = "^\\{\"path\":\"src/.*\"\\}$"
decision = "allow"
priority = 100

MCP Server Rules

Server-Level Control

# Deny all tools from untrusted server
[[rule]]
mcpName = "untrusted-server"
decision = "deny"
priority = 500

Tool-Level Control

# Allow specific tool from server
[[rule]]
mcpName = "my-server"
toolName = "safe_tool"
decision = "allow"
priority = 100

Wildcards

# All tools from server pattern
[[rule]]
toolName = "my-server__*"
decision = "ask_user"
priority = 100

Approval Modes

YOLO Mode Rules

Apply only in YOLO mode (--yolo):

[[rule]]
toolName = "write_file"
decision = "allow"
modes = ["yolo"]
priority = 100

Auto-Edit Mode Rules

Apply in auto-edit mode:

[[rule]]
toolName = "replace"
decision = "allow"
modes = ["autoEdit"]
priority = 100

Template Library

Secure Development Environment

# Allow read operations
[[rule]]
toolName = ["read_file", "glob", "search_file_content", "list_directory"]
decision = "allow"
priority = 100

# Ask for writes
[[rule]]
toolName = ["write_file", "replace"]
decision = "ask_user"
priority = 100

# Allow safe git commands
[[rule]]
toolName = "run_shell_command"
commandPrefix = ["git status", "git diff", "git log", "git branch"]
decision = "allow"
priority = 200

# Ask for other git commands
[[rule]]
toolName = "run_shell_command"
commandPrefix = "git "
decision = "ask_user"
priority = 150

# Deny destructive commands
[[rule]]
toolName = "run_shell_command"
commandRegex = "^(rm|rmdir|del|rd|format|mkfs)\\s"
decision = "deny"
priority = 999

Read-Only Mode

# Allow all reads
[[rule]]
toolName = ["read_file", "glob", "search_file_content", "list_directory", "web_fetch"]
decision = "allow"
priority = 100

# Deny all writes
[[rule]]
toolName = ["write_file", "replace", "run_shell_command"]
decision = "deny"
priority = 500

NPM/Node.js Safe

# Allow npm read commands
[[rule]]
toolName = "run_shell_command"
commandPrefix = ["npm list", "npm outdated", "npm audit"]
decision = "allow"
priority = 200

# Ask for npm install/run
[[rule]]
toolName = "run_shell_command"
commandPrefix = ["npm install", "npm run", "npm exec"]
decision = "ask_user"
priority = 150

# Deny npm publish
[[rule]]
toolName = "run_shell_command"
commandPrefix = "npm publish"
decision = "deny"
priority = 900

MCP Server Restrictions

# Deny all external MCP servers by default
[[rule]]
toolName = "*__*"
decision = "deny"
priority = 100

# Allow specific trusted server
[[rule]]
mcpName = "trusted-internal-server"
decision = "allow"
priority = 200

# Allow specific tools from another server
[[rule]]
toolName = ["other-server__read_docs", "other-server__search"]
decision = "allow"
priority = 200

Enterprise Lockdown

# System-level (Admin tier)
# Block all network access
[[rule]]
toolName = ["web_fetch", "google_web_search"]
decision = "deny"
priority = 999

# Block all MCP servers
[[rule]]
toolName = "*__*"
decision = "deny"
priority = 999

# Allow only reads
[[rule]]
toolName = ["read_file", "glob", "search_file_content"]
decision = "allow"
priority = 100

# Block all shell commands except safe ones
[[rule]]
toolName = "run_shell_command"
decision = "deny"
priority = 500

[[rule]]
toolName = "run_shell_command"
commandPrefix = ["ls ", "cat ", "echo ", "pwd"]
decision = "allow"
priority = 600

Validation

Check TOML Syntax

python -c "import tomllib; tomllib.load(open('policy.toml', 'rb'))"

Common Errors

Error	Cause	Fix
Parse error	Invalid TOML	Check quotes, brackets
Rule ignored	Lower priority	Increase priority
Rule conflicts	Overlapping patterns	Refine patterns
Regex fails	Bad escape	Use \\ for backslash

Debug Rules

# Test which rule matches
gemini "Test shell command" --debug-policy

Best Practices

1. Start Restrictive

# Default deny, then allow specific
[[rule]]
toolName = "*"
decision = "ask_user"
priority = 1

[[rule]]
toolName = "read_file"
decision = "allow"
priority = 100

2. Use Clear Priorities

# Security rules at 900+
[[rule]]
commandRegex = "^rm\\s"
decision = "deny"
priority = 999

# Normal rules at 100-499
[[rule]]
commandPrefix = "git "
decision = "allow"
priority = 200

3. Document Rules

# SECURITY: Block destructive file operations
# Reason: Prevent accidental data loss
# Author: security-team
# Date: 2025-11-30
[[rule]]
toolName = "run_shell_command"
commandRegex = "^(rm|rmdir)\\s+-r"
decision = "deny"
priority = 999

4. Test Before Deploy

# Test in interactive mode first
gemini --policy-file ./test-policy.toml

5. Layer Policies

System policies (enterprise defaults)
  └── User policies (personal preferences)
       └── Project policies (project-specific)

Related Skills

• gemini-cli-docs - Official policy documentation
• toml-command-builder - Custom command creation

Keyword Registry

Topic	Keywords
Basic	policy engine, toml rules, tool policy
Decisions	allow, deny, ask_user, decision
Matching	toolName, commandPrefix, commandRegex, argsPattern
Priority	priority tier, rule priority, precedence
MCP	mcp policy, mcpName, server rules
Modes	yolo mode, autoEdit, approval mode

Test Scenarios

Scenario 1: Create Policy Rule

Query: "How do I create a Gemini policy to block rm commands?" Expected Behavior:

• Skill activates on "policy engine" or "tool policy"
• Provides TOML rule with commandPrefix/commandRegex Success Criteria: User receives working deny rule for destructive commands

Scenario 2: Priority Configuration

Query: "How do Gemini policy priorities work?" Expected Behavior:

• Skill activates on "priority tier" or "rule priority"
• Explains tier system and calculation Success Criteria: User understands tier-based priority (Admin > User > Default)

Scenario 3: MCP Server Policy

Query: "How do I restrict MCP server tools in Gemini?" Expected Behavior:

• Skill activates on "mcp policy" or "server rules"
• Provides mcpName and wildcard patterns Success Criteria: User receives MCP-specific policy rules

Version History

• v1.1.0 (2025-12-01): Added MANDATORY section, Test Scenarios, Version History
• v1.0.0 (2025-11-25): Initial release