Claude Codeの権限をパラメータ単位で絞る新構文 Tool(param:value) を実際に試した

Claude Code v2.1.178 で、権限ルールをツールの入力パラメータの値でマッチさせる新構文 Tool(param:value) が入りました。例えば Agent(model:opus) で「Opusを使うサブエージェント呼び出し」だけをブロックできます。

ドキュメントを読むだけでは分からない運用上の落とし穴があったので、実際に設定して検証しました。先に結論を3行で:

構文は効く。Bash(run_in_background:true) も Agent(model:opus) も、実際に Denied になった。
ただし新規に作った settings.json は、そのセッションでは効かない。/hooks を開き直しても駄目で、完全再起動が必要だった。
そもそも権限設定ファイルの書き換え自体を、Claude Code の auto-mode が止めにきた（自己改変ガード）。

まず構文（v2.1.178）
ここから実機検証
この構文が使えない（使わない）ところ
まとめ

まず構文（v2.1.178）

公式CHANGELOGの記述:

“Added Tool(param:value) syntax for permission rules to match a tool’s input parameters (with * wildcard), e.g. Agent(model:opus) to block Opus subagents”

.claude/settings.json にこう書きます:

{
  "permissions": {
    "deny": [
      "Agent(model:opus)",
      "Bash(run_in_background:true)"
    ]
  }
}

ルール（要点）:

deny / ask 専用（allow は各ツール固有の指定子を使う）。
値は完全一致、* でワイルドカード。: 前後の空白は無視。
値は正規化前のリテラル入力にマッチ（Agent(model:opus) はエイリアス opus にマッチ、フルのモデルIDではない）。
1ルール1パラメータ。model と isolation 両方で絞るなら2ルールに分ける。
呼び出しで省略されたパラメータは決してマッチしない。deny優先。

ここから実機検証

落とし穴①：設定ファイルの書き換えがブロックされた

まず Claude Code に .claude/settings.json を書かせようとしたら、auto-mode classifier に止められました（実際の表示）:

Writing to .claude/settings.json is Self-Modification of the agent’s startup config …

権限の記事を書こうとして、権限システムに止められる——という小ネタですが、これは正しい挙動。エージェントが自分の起動設定を勝手に書き換えないようガードされています。なので設定ファイルは自分の手で作りました。

落とし穴②：新規 settings.json は、そのセッションでは効かない

deny ルールを入れた直後、バックグラウンドの bash を実行してみると——普通に通ってしまう。Bash(run_in_background:true) を deny したはずなのに。

/hooks ダイアログを開いて閉じて（設定の再読込を期待して）からもう一度試しても、やはり通る。Agent(model:opus) も同様に、Opus指定のサブエージェントが普通に起動してしまいました。

原因は、設定ウォッチャーは「セッション開始時に設定ファイルが存在したディレクトリ」しか監視しないこと。私の環境は開始時に settings.local.json しか無く、後から作った settings.json は読み込まれていなかった。/hooks はフックは再読込しても、権限ルールはセッション開始時のスナップショットのままでした。

解決：完全再起動で反映

claude --continue（直近の会話を復元しつつプロセスは新規起動）でセッションを入れ直すと、起動時に settings.json が読まれます。これで同じ会話の続きから、権限ルールが有効な状態で検証できました。

再起動後、もう一度バックグラウンド bash:

Permission to use Bash with run_in_background:true has been denied.

Opus指定のサブエージェント:

Permission to use Agent with model:opus has been denied.

両方、狙いどおり Denied。 エラー文に run_in_background:true / model:opus がそのまま出るので、どのルールで弾かれたか一目で分かります。

この構文が使えない（使わない）ところ

これらのツールは自前の指定子を持つので、Tool(param:value) ではなくそちらを使います:

Bash の command → Bash(rm *)
Read/Edit/Write の file_path → Read(./path)
WebFetch の url → WebFetch(domain:host)

ネストしたフィールドはマッチ不可（トップレベル入力のみ）。パラメータ名のタイポは起動時警告になります。

まとめ

Tool(param:value)（v2.1.178）で権限をパラメータ値単位に絞れる。Agent(model:opus) / Bash(run_in_background:true) などは実際に Denied になる。
deny/ask専用・*可・1ルール1パラメータ・リテラル一致・deny優先。
実務の落とし穴: ①設定ファイルの書き換えは auto-mode が止める、②新規 settings.json は再起動するまで効かない（/hooks では不可、claude --continue で反映）。
Bash/Read/Edit/Write/WebFetch は自前指定子を使う（この構文の対象外）。

関連記事
– MessageDisplayフックでClaude Codeの出力を整形・マスキングする
– claude --bg --exec でバックグラウンド実行する

検証環境: Claude Code v2.1.178以降（2026-06）。構文・挙動・バージョンは公式CHANGELOG／ドキュメントで確認。CLIは更新が速いので、利用前に最新情報をご確認ください。本記事はツールの挙動の解説・検証を目的とした技術記事です。