Policy engine

概要

ツール実行に対する細かい制御を与える仕組み。ツール呼び出しを allow / deny / ユーザー確認のいずれにするかを決めるルールを、ユーザーと管理者が定義できる。ルールは .toml ファイルで書く。

仕様

ルールの構成

Conditions: ルールが適用される条件（ツール名、引数、現在の approval mode など）
Decision: 一致したときの動作（allow / deny / ask_user）
Priority: 優先度の数値。大きいほど勝つ

decision

値	挙動
`allow`	ユーザー操作なしで自動実行する
`deny`	ブロックして実行しない。`argsPattern` を持たないグローバルなルールでは、拒否されたツールはモデルのメモリから完全に除外される（モデルはその選択肢自体を見なくなる）
`ask_user`	承認を求める。非対話モードでは `deny` として扱われる

deny がツールを除外する推奨手段。settings.json の legacy な tools.exclude は deprecated で、deny のポリシールールが推奨される

条件

toolName: 呼ばれるツール名と一致する必要がある。ワイルドカード
- *: 任意のツール（組み込み・MCP を問わず）
- mcp_server_*: 特定 MCP サーバーの任意のツール
- mcp_*_toolName: すべての MCP サーバーにわたる特定のツール名
- mcp_*: 任意の MCP サーバーの任意のツール
- FQN のワイルドカードも使えるが、MCP ツールには mcpName フィールドの使用が推奨されている
argsPattern: ツールの引数を安定した JSON 文字列に変換し、正規表現で照合する。一致しなければルールは適用されない
interactive: true で対話モードのみ、false で非対話（headless）のみ。省略すると両方に適用される

優先度のティア

Workspace ティア（プロジェクトレベルのポリシー）は現時点で機能しない。 ワークスペースの .gemini/policies にポリシーを置いても効果が無い（GitHub issue #18186）。User または Admin のポリシーを使う。

ティア	Base	説明
Default	1	Gemini CLI に同梱される組み込みポリシー
Extension	2	extension が定義するポリシー
Workspace	3	（現在無効）現在のワークスペースの設定ディレクトリのポリシー
User	4	ユーザーが定義するカスタムポリシー
Admin	5	管理者が管理するポリシー

TOML 内の priority は 0〜999
最終優先度の式: final_priority = tier_base + (toml_priority / 1000)
これにより Admin > User > Workspace > Default の順が保証され、同一ティア内でも細かく順序付けできる
注意: 出典のこの節に載っている計算例（Default の priority 50 → 1.050、Workspace の 10 → 2.010、User の 100 → 3.100、Admin の 20 → 4.020）は、上のティア表の Base 値と一致していない。例では Workspace=2 / User=3 / Admin=4 となり、表より 1 ずつ小さい
- さらに、出典の散文も例の側に一致している。 同じページの Admin ポリシーの説明は「Administrators can enforce system-wide policies (Tier 4)」「the same Admin tier (Base 4)」と書いており、Admin を 4 として扱っている
- つまり ティア表だけが他（計算例・散文）と食い違っている構図。表の Base 値が誤植である可能性が高いが、出典内で確定できないため、具体的な数値に依存する設計をする前に実機で確認すること

approval mode

ルールは 1 つ以上のモードに紐づけられる。モードを指定しないルールは常に有効。

モード	内容
`default`	標準の対話モード。ほとんどの write ツールが確認を要する
`autoEdit`	自動的なコード編集向け。一部の write ツールが自動承認されうる
`plan`	調査・設計のための厳格な read-only モード
`yolo`	すべてのツールが自動承認される（極めて慎重に使う）

永続的な承認はコンテキストを意識する。「Allow for all future sessions」を選ぶと、現在のモードとそれより緩いモードすべてがルールに含まれる（階層は plan < default < autoEdit < yolo）。

plan モードでの承認は、そのツールをグローバルに信頼する意図的な選択と見なされ、全モード（plan / default / autoEdit / yolo）を含む
default での承認は default / autoEdit / yolo に適用される
autoEdit での承認は autoEdit / yolo に適用される
yolo での承認は yolo にのみ適用される

ルールの照合

優先度の高いものから照合し、最初に一致したルールが結果を決める
すべての条件（toolName、argsPattern など）を満たすときに一致する

ポリシーファイルの場所

ティア	種別	場所
User	Custom	`~/.gemini/policies/*.toml`
Workspace	Custom	（無効） `$WORKSPACE_ROOT/.gemini/policies/*.toml`
Admin	System	OS 依存（下記）

ディレクトリ内の .toml はすべて読み込まれて結合される

管理者ポリシーの標準の場所:

OS	パス
Linux	`/etc/gemini-cli/policies`
macOS	`/Library/Application Support/GeminiCli/policies`
Windows	`C:\ProgramData\gemini-cli\policies`

補助的な管理者ポリシー:

--admin-policy コマンドラインフラグ、または system settings ファイルの adminPolicyPaths 設定で追加パスを指定できる
これらも標準の場所と同じ Admin ティアとして扱われる
セキュリティガード: 標準のシステム上の場所に .toml ポリシーファイルが 1 つでもあると、補助的な管理者ポリシーは無視される。 中央のシステムポリシーが確立済みのときにフラグでの上書きを防ぐため

標準のシステムポリシーディレクトリに対するセキュリティ要件（満たさない場合、そのディレクトリのポリシーは無視される）:

Linux / macOS: root（UID 0）所有で、group・others に書き込み権限が無いこと（例: chmod 755）
Windows: C:\ProgramData 配下にあり、標準ユーザー（Users、Everyone）が Write / Modify / Full Control を持たないこと
補助的な管理者ポリシー（--admin-policy / adminPolicyPaths）は、この厳格な所有権チェックの対象外

TOML のルールスキーマ

フィールド	説明
`toolName`	ツール名、または名前の配列
`subagent`	（任意）この subagent が行うツール呼び出しにのみルールを適用する
`mcpName`	（任意）MCP サーバー名。`toolName` と組み合わせると内部的に `mcp_mcpName_toolName` の FQN を作る
`toolAnnotations`	（任意）ツールが提供するメタデータのヒント。ここに書いた key-value がすべてツールの annotations に存在するとき一致する
`argsPattern`	（任意）引数に対する正規表現
`commandPrefix`	（任意）シェルコマンドの先頭に一致する文字列または配列。`toolName = "run_shell_command"` と `argsPattern` の糖衣構文
`commandRegex`	（任意）シェルコマンド全体に対する正規表現。引数の JSON 表現（`{"command":"<your_command>"}`）に対して照合され、先頭に `"command":"` が付くため実質コマンド先頭から一致する。`^` や `$` は JSON 文字列全体に効くので `^` は通常避ける。`commandPrefix` と同一ルール内で併用できない
`decision`	`"allow"` / `"deny"` / `"ask_user"`
`priority`	0〜999
`denyMessage`	（任意）このルールで拒否されたときに表示するメッセージ。モデルとユーザーの両方に返る
`modes`	（任意）このルールが有効な approval mode の配列。省略または空ならすべてのモードに適用
`interactive`	（任意）対話（`true`）／非対話（`false`）への限定
`allowRedirection`	（任意）`true` でシェルのリダイレクト演算子（`>`、`>>`、`<`、`<<`、`<<<`）を許す。既定では、ルールが一致してもリダイレクトを検出すると確認を求める。この許可はそのルール限りで、チェーンしたコマンドでは各コマンドのルールがそれぞれリダイレクトを許可する必要がある

toolName と commandPrefix は文字列の配列も受け付ける

MCP ツール向けの構文

mcpName を使うのが推奨。FQN やワイルドカード文字列を手書きするより堅牢
MCP サーバー名にアンダースコア（_）を使わない。 ポリシーパーサーは FQN（mcp_server_tool）を mcp_ 接頭辞の直後の最初のアンダースコアで分割するため、サーバー名にアンダースコアがあるとサーバーの識別を誤り、ワイルドカードルールやセキュリティポリシーが黙って機能しなくなる
mcpName を使うとき、toolName は単純名を書く（FQN ではない）
mcpName だけを指定すると、そのサーバーのすべてのツールに適用される（allow / deny / ask_user すべての decision で有効）
mcpName = "*" で、登録済みの任意の MCP サーバーのすべてのツールを対象にできる

subagent 向けの構文

subagent 名を toolName として扱うことで、標準のポリシールールで統治できる
メインエージェントが subagent を呼ぶとき（統合された invoke_agent ツールなど）、Policy Engine は対象の agent_name を仮想的なツールのエイリアスとして照合する
後方互換: 過去の 1:1 の subagent ツール名を対象に書いたルールも透過的に一致し続ける
「誰が呼んでいるか」でルールを作るには subagent フィールドを使う

既定のポリシー

read_file、glob などの read-only ツールは概ね allow
agent の委譲は既定 ask_user（リモートエージェントが確認を求められるようにするため）。ただしローカルの sub-agent の動作は黙って実行され、個別にチェックされる
write_file、run_shell_command などの write ツールは既定 ask_user
yolo モードでは高優先度のルールがすべてのツールを許可する
autoEdit モードでは、一部の write 操作を確認なしに行うルールがある

設定

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

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

# 特定 MCP サーバーの特定ツールを許可する
[[rule]]
mcpName = "my-jira-server"
toolName = "search"
decision = "allow"
priority = 200

# 任意の MCP サーバーの任意のツールに確認を求める
[[rule]]
toolName = "*"
mcpName = "*"
decision = "ask_user"
priority = 10

# subagent へのアクセスを拒否する
[[rule]]
toolName = "codebase_investigator"
decision = "deny"
priority = 500
deny_message = "Deep codebase analysis is restricted for this session."