.claude/settings.json の permissions を、Bash(npm *) のようなコマンド文字列のパターンだけで書いていませんか。文字列マッチだけの防御は、コマンドの書き方を少し変えられただけですり抜けます。2.1.178 で追加された Tool(param:value) 構文は、コマンド文字列ではなくツールの入力パラメーターの値でルールを書けるようにするものです。この記事では、wildcard 世代のルールを param:value 世代へ段階的に upgrade する手順を、空のディレクトリから通しで作り、実機の出力で確認まで行います。
permission ルールはこの半年で3回変わっている
まず、いま自分が書いているルールが「どの世代の書き方か」を確認します。CHANGELOG から確認できる変化は、大きく3つです。
第1世代(2.1.0): Bash コマンド文字列の wildcard
Added wildcard pattern matching for Bash tool permissions using
2.1.0 で、Bash ツールの permission にワイルドカード * によるパターンマッチングが追加され、ルール内の任意の位置に * を置けるようになりました(Bash(npm *)、Bash(* install)、Bash(git * main))[1]。多くのプロジェクトの settings.json はいまだにこの世代で止まっています。
第2世代(2.1.162 / 2.1.166 の整備): グロブとドメインの穴が塞がれた
wildcard domain rules never matching subdomains in allow, deny, and ask position
2.1.162 で、WebFetch(domain:*.example.com) 形式のワイルドカードドメインルールが allow・deny・ask のいずれのポジションでもサブドメインに一致しないバグが修正されました。同時に、
file permission rules with mid-pattern wildcards
つまり Read(secrets-*/config.json) のようにパターンの途中にワイルドカードを含むファイルルールが起動時に拒否される問題も修正されています[1]。もしあなたが以前これらを試して「効かない」と諦めていたなら、それは書き方ではなく実装側の問題だった可能性があります。
さらに 2.1.166 では、
Added glob pattern support in deny rule tool-name position
deny ルールのツール名の位置にグロブが使えるようになり、"*" で全ツールを拒否できます。ただし同じ変更で、
allow rules reject non-MCP globs
allow ルールは非 MCP のグロブを受け付けません。加えて、
unknown tool names in deny rules warn at startup
deny ルールに存在しないツール名を書くと起動時に警告が出ます[1]。この3点はセットで理解しないと、後述する「全部閉じてから穴を開ける」設計で必ず詰まります。
第3世代(2.1.178): パラメーターの値でマッチする
syntax for permission rules to match a tool's input parameters
2.1.178 で Tool(param:value) 構文が追加され、任意のツールの入力パラメーター名と値でマッチングできるようになりました。* ワイルドカードも使え、例として Agent(model:opus) で Opus モデルを使うサブエージェントをブロックできます[1]。文字列としてのコマンドではなく、ツールに渡る構造化された入力そのものが対象になったのがこの世代の変化です。
なお Bash(cmd:*) という Bash 固有の param 指定は、一般構文の導入より前から存在していました。2.1.98 で、
wildcard permission rules failing to match commands with extra spaces or tabs
Bash(cmd:*) と Bash(git commit *) のワイルドカードルールが、余分なスペースやタブを含むコマンドに一致しないバグが修正されています[1]。文字列マッチはスペース1個で壊れうるという事実の記録として、この修正は覚えておく価値があります。
実装: 空のディレクトリから permission ポリシーを組む
0. 前提
- Claude Code 2.1.186(本稿の実機確認バージョン。2026-07-12 時点)
- Linux(WSL2 含む)。
python3が使えること -
Tool(param:value)構文は 2.1.178 以降でのみ有効です[1]。それ未満なら先に更新してください
claude --version
1. 作業ディレクトリを作る
mkdir -p ~/tmp/perm-upgrade/.claude
cd ~/tmp/perm-upgrade
git init -q
2. v1: wildcard 世代の settings.json を置く
.claude/settings.json:
{
"permissions": {
"allow": [
"Bash(npm *)",
"Bash(git * main)"
],
"deny": [
"Bash(echo *)"
]
}
}
Bash(npm *) / Bash(git * main) は 2.1.0 で追加された位置自由のワイルドカード形式です[1]。まず JSON として妥当かを、Claude Code を起動する前に確認します。
python3 -c "import json; json.load(open('.claude/settings.json')); print('settings.json: valid JSON')"
このコマンドは、JSON が壊れていなければ settings.json: valid JSON と表示し、壊れていれば例外で落ちます。この1行を CI に入れる理由は §「壊れた settings.json はファイルごと捨てられる」で説明します。
3. deny が本当に効いているかを、実行して確認する
claude を起動し、次を依頼します。
echo hello-from-deny-test を実行して
deny ルール Bash(echo *) が効いていれば、実行は拒否され、次のテキストが返ります(2.1.186 実機)。
Permission to use Bash with command echo hello-from-deny-test has been denied.
拒否メッセージが出ずにコマンドが走ってしまった場合、ルールが読まれていません。設定ファイルの置き場所(.claude/settings.json)と、次節の JSON エラーを疑ってください。
4. v2: param:value へ upgrade する
.claude/settings.json を書き換えます。
{
"permissions": {
"deny": [
"Bash(echo *)",
"Agent(model:opus)",
"Read(secrets-*/config.json)"
],
"ask": [
"WebFetch(domain:*.example.com)"
],
"allow": [
"Bash(npm *)",
"Bash(git * main)"
]
}
}
3行が新しい世代です。
-
Agent(model:opus): サブエージェントの入力パラメーターmodelの値で拒否します。CHANGELOG が挙げているのがまさにこの例です[1]。コマンド文字列では表現できなかった「どのモデルを使うか」がルールになります -
Read(secrets-*/config.json): パターン途中のワイルドカードを含むファイルルール。2.1.162 より前は起動時に拒否されていました[1] -
WebFetch(domain:*.example.com): サブドメインへの一致は 2.1.162 で修正済みです[1]
Agent(model:opus) の綴りを間違えて Agnet(model:opus) と書いた場合、deny ルールの未知のツール名は起動時に警告されます[1]。警告であって拒否ではない点が重要です。タイポしたルールは黙って無効化されるのではなく、起動時に気づける形で表面化します。
5. 「全部閉じてから穴を開ける」は、そのままでは成立しない
deny のツール名位置に "*" を書くと全ツールを拒否できます[1]。ここから「deny で全部閉じ、allow で必要な分だけ開ける」というホワイトリスト運用を思いつきますが、allow ルールは非 MCP のグロブを受け付けません[1]。つまり allow 側は個別列挙になります。
さらに、deny "*" と allow の個別ルールが衝突したときにどちらが勝つかは、CHANGELOG の記述だけでは確定できません(2026-07-12 時点で筆者は逐語の出典を確認できていません)。この点は推測で運用に入れないでください。 確認方法は §3 と同じで、deny "*" を入れた状態で allow 済みのはずの npm --version を依頼し、拒否メッセージが返るかどうかを1回見ればわかります。返れば deny が勝ち、ホワイトリスト運用は成立しません。
壊れた settings.json は「そのファイルごと」捨てられる
ここが、この記事でいちばん伝えたい落とし穴です。.claude/settings.json を意図的に壊してみます。
printf '{ "permissions": { "deny": ["Bash(echo *)"] ' > .claude/settings.json
閉じ括弧が足りない JSON です。この状態で claude を起動すると、次が表示されます(2.1.186 実機)。
Settings Error
<your-project>/.claude/settings.json
└ Invalid or malformed JSON
Files with errors are skipped entirely, not just the invalid settings.
❯ 1. Fix with Claude
2. Exit and fix manually
3. Continue without these settings
Enter to confirm · Esc to cancel
読むべきは3行目です。エラーのあるファイルは丸ごとスキップされ、壊れた設定項目だけが飛ぶのではありません。つまりカンマ1個の打ち間違いで、そのファイルに書いた deny ルールが全部消えます。しかも 3 番の選択肢を選べば、設定なしで作業を続行できてしまいます。permission は、設定ファイルの構文エラーに対して fail-open に倒れるということです。
docs に無い1節: deny は「壊れても残る場所」に置く
以上を踏まえた、筆者の設計上の判断を3つ書きます(事実主張ではなく設計意見です)。
1. deny を、頻繁に編集するファイルと同居させない。
settings.json はモデル設定や env の追加で頻繁に触ります。触る回数が多いファイルほど JSON を壊す確率が上がり、壊れた瞬間に deny が全部消えます。私は deny を、日常的に編集しない別ファイル(プロジェクト共有の settings.json)に隔離し、個人の実験設定は settings.local.json 側に置きます。片方が壊れてももう片方は生き残ります。ファイル単位でスキップされるという挙動は、裏を返せばファイル分割が唯一の防御になるということです。
2. python3 -c "import json; json.load(...)" を pre-commit と CI に入れる。
起動時ダイアログは人間が見ていないと機能しません。ヘッドレスや cron で Claude Code を回すなら、壊れた JSON は「気づかないまま権限が全開」に直結します。§2 の1行を機械判定の床として置いておけば、壊れた設定は commit の時点で止まります。
3. deny は文字列マッチではなく param:value に寄せる。
2.1.98 の修正が示すのは、コマンド文字列のワイルドカードは余分なスペースやタブという些細な差で一致に失敗しうる、という事実です[1]。修正された今でも、Bash(rm -rf *) のような文字列 deny は、シェルの表現の自由度(クォート、変数展開、パイプ、env 経由の起動)に対して原理的に弱いままです。禁止したい対象がツールの入力パラメーターとして表現できるなら(モデル名、ドメイン、ファイルパス)、Tool(param:value) 側で書くほうが表現の揺れに強くなります。逆に、シェルコマンドの中身を文字列で網羅的に禁止しようとする設計は、いつまでも穴が残る前提で運用してください。
詰まりどころ
-
ルールを書いたのに効かない: まず
python3 -c ...で JSON を検証します。次に §3 の deny テスト(echo hello-from-deny-test)で、そもそもファイルが読まれているかを切り分けます -
Tool(param:value)が無視される: 2.1.178 未満のバージョンです[1]。claude --versionを確認してください -
WebFetch(domain:*.example.com)がサブドメインに当たらない: 2.1.162 で修正済みの既知バグです[1]。更新してください -
Read(secrets-*/config.json)が起動時に弾かれる: 同じく 2.1.162 で修正済みです[1] - allow にグロブを書いたら怒られる: allow は非 MCP のグロブを受け付けません[1]。個別に列挙してください
応用
Agent(model:opus) は、CHANGELOG が明示する「Opus サブエージェントをブロックする」用途です[1]。これは安全のためのルールというより、コスト制御をルールとして書けることを意味します。サブエージェントを多用するワークフローで、上位モデルの使用箇所を人間が明示的に選んだ場所だけに限定したい場合、deny に1行足すだけで構造的に効きます。同じ発想で、ask に置けば毎回確認になります。
パラメーターの値でマッチできるということは、ツールの入力スキーマがそのままポリシーの語彙になるということです。禁止したいものを「コマンドの書き方」ではなく「ツールに何が渡るか」で言い直せないか、既存の deny を一度読み直してみてください。
限界と未確認事項(2026-07-12 時点)
- 本稿の仕様記述の出典は Claude Code の CHANGELOG です。マッチングの厳密なセマンティクス(部分一致か完全一致か、複数 param の AND 条件など)は、CHANGELOG からは確定できません
- deny の
"*"と allow の個別ルールの優先関係は未確認です(§5)。手元で1コマンド試して確認してください - captured 出力は 2.1.186 の実機のものです。表示文言はバージョンで変わりえます
References
[1] https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md