claude -pのallowedToolsは道具を絞らない

claude -pのallowedToolsは道具を絞らない

Claude Code を claude -p で動かすとき、--allowedTools "Read" を付ければ Read しか使えなくなる、と読みたくなります。

ところが公式の CLI リファレンスでは、--allowedTools は「確認なしで実行する道具」の一覧で、使える道具を絞りたいなら --tools を使う、と書かれています。

手元の Claude Code 2.1.234 で、モデルに送られる道具の定義を数えてみました。

--allowedTools "Read" を付けても、送られた道具は何も付けないときと同じ 23 個のままでした。

道具の扱いには「見せる」「確認なしで通す」「消す」の 3 つの層があり、フラグごとに受け持つ層が違うと分かると、CI や定期ジョブで道具を絞る設定を組み立てやすくなります。

--allowedToolsは確認を省くリスト

--allowedTools は、許可ルール(allow ルール)をコマンドラインから渡すフラグです。

CLI リファレンスの説明は「許可の確認なしで実行される道具」で、同じ行に「使える道具を制限するには代わりに --tools を使う」と添えられています。

書き方は設定ファイルの permissions.allow と同じ権限ルールの構文で、"Bash(git log *)" のようにコマンドの形まで指定できます。

紛らわしいのは claude --help の表示です。

手元の 2.1.234 では、--allowedTools の説明が「許可する道具名の一覧(list of tool names to allow)」の 1 行だけでした。

「allow」を「使ってよい道具だけを残す」と読むと、Read 以外は消えると勘違いしやすくなります。

公式の headless のページには、一覧に無い道具の呼び出しも、承認が要らないものならそのまま実行されると書かれています。

承認が要る呼び出しは、Manual モードの claude -p では、hook や --permission-prompt-tool が承認しない限り拒否されます。

Claude Code v2.1.302 以降は、権限モードをどこでも指定していない claude -p は Manual モードで始まるのが既定です。

--allowedTools が決めるのは、確認なしで通すかどうかで、モデルに見せる道具の数は変わりません。

Run Claude Code programmatically(公式ドキュメント)

Run Claude Code programmatically - Claude Code Docs

見せる道具を決めるのは--tools

モデルに見せる組み込みの道具を決めるのが --tools です。

"" で全部を外し、"default" で既定の一式に戻し、"Bash,Edit,Read" のように名前を並べるとその道具だけが残ります。

一覧から外した道具は定義ごと送られないので、モデルからは見えず、呼び出す手段がありません。

許可だけを絞った場合は道具が見えたままなので呼び出しは起こりえて、承認が要るものがそこで止められます。

見えている道具の数だけ定義がリクエストに載るので、使わない道具を外すとその分の入力も減ります。

既定の一式は OS で違い、macOS・Linux・WSL では Glob と Grep が既定から外れ、find と grep を Bash から使う形になります。

Windows では Glob と Grep が既定の一式に入っていて、手元の計測でも両方が送られていました。

CLI reference(公式ドキュメント)

CLI reference - Claude Code Docs

MCPの道具は--toolsでは消えない

--tools が絞るのは組み込みの道具だけで、MCP サーバーの道具には効きません。

CLI リファレンスの --tools の行にも、MCP の道具まで外すなら --disallowedTools "mcp__*" を使うと書かれています。

MCP の道具をサーバーの単位で選びたいときは、--mcp-config と --strict-mcp-config を組み合わせます。

--strict-mcp-config を付けると、--mcp-config で渡したサーバーだけを使い、ユーザー設定やプロジェクトの設定にある MCP サーバーは読み込みません。

付けないと、--mcp-config で渡したサーバーに、ユーザー設定などのサーバーが足されます。

--tools で組み込みの道具を絞っても、ユーザー設定に入れた MCP サーバーの道具は残ります。

--disallowedToolsは書き方で効き方が変わる

--disallowedTools は拒否ルールを渡すフラグで、書き方によって「消す」と「止める」に分かれます。

"Edit" のように道具の名前だけを書くと、その道具はモデルの文脈から取り除かれます。

"*" は全部の道具、"mcp__*" は全部の MCP の道具を取り除く指定です。

一方、"Bash(rm *)" のように中身まで指定すると、Bash は見えたまま残り、当てはまる呼び出しだけが拒否されます。

拒否はどこか 1 か所で決まると、ほかの層からは許可できません。

権限の公式ページには、管理者の設定(managed settings)で拒否された道具は --allowedTools でも許可できない、という例が載っています。

Configure permissions(公式ドキュメント)

Configure permissions - Claude Code Docs

手元で道具の一覧を数えた

ここまでの説明が手元の版でもそのとおりかを、モデルに届くリクエストで確かめました。

環境は Windows 11 の Git Bash と Claude Code 2.1.234 で、API の宛先を 127.0.0.1 の小さなスタブに向け、届いたリクエストの tools に並ぶ名前を記録しています。

設定フォルダは CLAUDE_CONFIG_DIR で空の一時フォルダにし、echo という道具を 1 つだけ持つ MCP サーバーを自作して demo の名前で渡しました。

測ったのは CLI がモデルに見せた道具の一覧で、モデルがその道具をどう使うかは測っていません。

export CLAUDE_CONFIG_DIR="$PWD/cfg"                  # 空の設定フォルダ
export ANTHROPIC_BASE_URL="http://127.0.0.1:18765"   # 届いたリクエストを記録するスタブ
claude -p "hi" --mcp-config ./mcp.json --allowedTools "Read"
claude -p "hi" --mcp-config ./mcp.json --tools "Read"
claude -p "hi" --mcp-config ./mcp.json --tools "Read" --disallowedTools "mcp__*"
# 略(下の表の組み合わせを順に実行)
付けたフラグ送られた道具
指定なし組み込み 22 個+mcp__demo__echo(計 23 個)
--allowedTools "Read"指定なしと同じ 23 個
--tools "Read"Read・mcp__demo__echo
--tools "Read" --disallowedTools "mcp__*"Read
--tools "Read"(ユーザー設定に MCP サーバー other を追加)Read・mcp__demo__echo・mcp__other__echo
上と同じ+--strict-mcp-configRead・mcp__demo__echo
--tools "Read,Bash" --disallowedTools "Bash(rm *)"Bash・Read
--tools "Read,Bash" --disallowedTools "Bash"Read

--allowedTools "Read" を付けても、Bash・Edit・Write・WebFetch と MCP の道具はすべて送られていました。

--tools で組み込みを 1 つにしても MCP の道具は残り、mcp__* の拒否か --strict-mcp-config で初めて外れています。

--disallowedTools も公式の説明どおりで、Bash(rm *) では Bash が残り、Bash だけを書くと一覧から消えました。

確認待ちになった呼び出しの行き先

見せる道具と許可を決めても、承認が要る呼び出しは残ります。

無人で動かすときの受け皿として、公式ドキュメントには権限モードの dontAsk が載っています。

dontAsk では、確認を求めるはずの呼び出しがすべて拒否され、許可ルールに当てはまるものと、作業フォルダ内の読み取りのような承認の要らない操作だけが実行されます。

v2.1.259 で足された --permission-prompts none は、確認を出すはずの呼び出しを拒否したうえで、誰も承認できないことをモデルに伝えて実行を続けさせるフラグです。

v2.1.319 の CHANGELOG には、確認待ちになる呼び出しを拒否してそのターンを続ける permissions.denyInsteadOfPrompting の設定が追加されたとあります。

この 2 つは手元の 2.1.234 より新しい版の機能なので、試していません。

Choose a permission mode(公式ドキュメント)

Choose a permission mode - Claude Code Docs

CHANGELOG.md(anthropics/claude-code)

claude-code/CHANGELOG.md at main · anthropics/claude-code

3つの層を分けて組み立てる

フラグごとの受け持ちを表にすると、次のようになります。

層決めること使うもの
見せる(組み込み)モデルに定義を送る道具--tools
見せる(MCP)読み込む MCP サーバーと道具--mcp-config・--strict-mcp-config・--disallowedTools "mcp__*"
消す名前で指定した道具を文脈から外す--disallowedTools(名前だけ)
止める当てはまる呼び出しだけを拒否する--disallowedTools(中身まで指定)
通す確認なしで実行する呼び出し--allowedTools
残りの扱い確認待ちになった呼び出し--permission-mode など

たとえば、差分を読んでレビューを書くだけのジョブなら、次のように層ごとに分けて書けます。

# 書式の例(モデルを動かしての確認はしていない)
claude -p "直近のコミットの差分をレビューして" \
  --tools "Read,Glob,Grep,Bash" \
  --allowedTools "Bash(git diff *)" "Bash(git log *)" \
  --strict-mcp-config --mcp-config ./ci-mcp.json \
  --permission-mode dontAsk

見せる道具を --tools と MCP の指定で先に決め、確認なしで通すものを --allowedTools で足し、残りを権限モードで落とす順に考えると、どのフラグに何を書くかで迷いにくくなります。

許可ルールが期待どおりに効かない場面は、別の記事で実例を書きました。

Claude Codeでallowルールが効かない理由

権限の設定とサンドボックスの違いは、こちらで整理しています。

AIエージェントのサンドボックスとは?権限設定との違い

最後に

--allowedTools は確認を省くリストで、道具の一覧そのものは変えません。

モデルに見せる道具を絞るのは組み込みなら --tools、MCP なら --strict-mcp-config と mcp__* の拒否です。

道具が多すぎると感じたら、まず「見せる層」と「通す層」のどちらを触っているのかを確かめてみてください。

以上です。