Claude Codeの制限モード(--restricted)の使い方

--restricted(またはCLAUDE_CODE_RESTRICTED=1)は、Claude Code v2.1.248で追加された起動フラグです。コマンドやコードを実行する組み込みツールとWebFetchを外し、ファイルツールを作業ディレクトリの内側に閉じ込め、ユーザー・プロジェクト・ローカルの設定ファイルを一切読まずに起動します。想定される使い方は、評価用のハーネスが共有マシン上でclaudeを動かし、そのマシンのユーザー設定やプロジェクト設定を読ませたくない場面です。

はじめに — 制限モードで何が変わるか

claude --restricted -p "query"

v2.1.248より前のバージョンでは、このフラグ自体が未知のオプションとして拒否されます。

v2.1.285のclaude --helpでは、--restrictedは次のように説明されています(読みやすさのため改行を詰めて引用します)。

$ claude --version
2.1.285 (Claude Code)
 
$ claude --help
  --restricted   Restricted mode: removes the built-in tools that run commands
                 or code (Bash, PowerShell, REPL and the other code-running
                 tools) and WebFetch unless --tools names them, and ignores
                 user, project and local settings files (managed settings and
                 --settings still apply; add --strict-mcp-config to skip MCP
                 servers too). Also confines the file tools to the working
                 directories (--add-dir included), refuses bypassPermissions,
                 and lets only a person or the configured permission handler
                 approve writes to settings, git and tool-configuration files.

WebFetch以外にPowerShellやREPLも外れる点と、MCPサーバーは--strict-mcp-configを足さない限り対象外になりうる点は、cli-referenceの表だけでは読み取りにくい部分です。MCPが実際に読み込まれるかどうかは、この記事では実機で確認していません。

制限モードは、名前が似た2つの機能と混同しやすいので先に区別しておきます。--safe-modeはCLAUDE.md・skills・MCPサーバー・hooksといったカスタマイズを無効化して起動する診断用のモードで、ツールの利用可否やファイルアクセス範囲は変えません。切り分け手順はClaude Code safe modeで「壊れた」設定を1コマンドで切り分けるで扱っています。もう1つはBashサンドボックスによるOSレベルの分離で、こちらは後述します。

ステップ1 — --restrictedで起動する

もっとも単純な使い方は、フラグを付けて-p(非対話モード)で起動することです。

claude --restricted -p "リポジトリのテストを実行して結果を要約して"

このコマンドを実行しても、コマンド実行系のツールが外れているためテストを実行できません。制限モードは既定でコマンドを一切実行させない状態から始まるためです。実行系ツールが必要な場面は、ステップ3の--toolsとの組み合わせで扱います。

bypassPermissionsを同時に指定しようとしても拒否されます。Claude Codeは、--restrictedで始めたセッションでbypassPermissionsモードを拒否します。この拒否はv2.1.248以降の挙動です。

ステップ2 — 環境変数で有効にしてCIに組み込む

フラグの代わりにCLAUDE_CODE_RESTRICTED=1という環境変数でも同じ効果があります。CI側でフラグを渡しにくい構成のときに使います。

CLAUDE_CODE_RESTRICTED=1 claude -p "query"

共有マシン上で評価ハーネスからclaudeを呼ぶ構成では、ハーネス専用の設定ファイルを--settingsで明示的に指定します。それ以外のローカル設定を読ませない形が基本パターンです。

CLAUDE_CODE_RESTRICTED=1 claude --settings ./harness-settings.json -p "query"

この構成では、共有マシン側にどんな~/.claude/settings.jsonや.claude/settings.jsonがあっても読み込まれません。評価対象のリポジトリに紛れ込んだ.claude/settings.jsonが勝手に権限ルールを広げる、といった経路を塞げます。

ステップ3 — 特定のツールだけ再び使えるようにする

評価ハーネスがテストコマンドの実行を必要とする場合は、--restrictedで外れたツールを--toolsで戻します。外れたツールは、--toolsで個別に名前を挙げれば戻ります(defaultプリセットを渡しても戻りません)。

claude --restricted --tools "Bash,Read" -p "テストスイートを実行して失敗したケースだけ報告して"

この例で使えるのはBashとReadです。--toolsは使えるツールの一覧を指定するオプションなので、一覧にないWebFetchや書き込み系ツールは使えないままです。ファイルツールが作業ディレクトリの外へ出られない制約や、設定ファイルを読まない制約は--toolsとは無関係にそのまま残ります。

評価ハーネスの構成は、次の順で決めると抜けが出にくくなります。

--restrictedはBashの到達範囲までは狭めない

--restrictedでBashを--toolsに戻すと、そのBashはOSレベルでは隔離されません。--restrictedの説明には、ファイルツールを作業ディレクトリに閉じ込めるという記述はあります。一方、Bashサブプロセスが触れるファイルシステムやネットワークの範囲を狭めるという記述は、--helpにもcli-referenceにも見当たりません。OSレベルでの隔離を担うのはBashサンドボックス(sandbox.enabled)という別の仕組みで、こちらはBashサブプロセスを対象にファイルシステム分離とネットワーク分離をかけます。

つまり--restricted --tools Bashだけでは、「Claude Codeのツールとしてどこまで動けるか」は狭まります。「復活させたBashが実際に何に触れられるか」までは狭まりません。評価ハーネスでテスト実行のためにBashを戻すなら、Bashサンドボックスも併用すると、OSレベルの隔離まで届きます。サンドボックスの設計はClaude Codeのサンドボックス設計、DevContainerでの隔離運用はClaude CodeをDevContainerで安全に動かす完全実装で扱っています。読み取りの再許可を管理設定だけに絞りたいならallowManagedReadPathsOnlyも選択肢です。

制限モードと他の権限系機能の使い分け

Claude Codeには権限まわりの機能がいくつも並んでおり、名前だけでは違いが分かりにくいので早見表にまとめます。

dontAskモードはツールを削除せず、承認ルールに合わないものをその場で拒否するのに対し、--restrictedは該当ツールをセッションから取り除きます。両者は組み合わせられますが、性格が異なる制限です。

dontAskはCI向けのモードとして位置づけられています。確認が必要になる呼び出しは自動拒否され、セッションが入力待ちで止まることはありません。一方で、作業ディレクトリ内のファイル読み取りや読み取り専用のBashコマンド、permissions.allowに一致する呼び出し、PreToolUse hookが承認した呼び出しは通ります。ハーネス専用の--settingsにallowルールを書いておけば、--restrictedの締め方に加えて「許可済みの操作だけ通り、それ以外は待たずに拒否される」動きを重ねられます。

もう1点、.claudeディレクトリや.gitのような保護対象パスへの書き込みについては、--restrictedはauto modeより厳格です。通常のauto modeでは、保護対象パスへの書き込みであってもauto modeの分類器が内容を判定して承認できる場合があります。--restrictedセッションでは、この分類器による承認自体が働きません。--helpの説明では、設定・git・ツール設定ファイルへの書き込みを承認できるのは人間か、設定された権限ハンドラーに限られます。

よくあるつまずき

クラウドセッションを作ろうとする — --restrictedセッションからは拒否されます。エラーメッセージはCloud sessions cannot be created from a --restricted session: they would not enforce it.です。新しいクラウドセッションは制限セッションのプロセスの外で動き、制限モードを強制できないためです。拒否はサーバーに接続する前にクライアント側で行われるので、クラウドセッションは作られません。クラウドセッションが必要なら、タスクをローカルの制限セッション内で完結させるか、--restrictedなしの別セッションから作成します。

保護対象パスへのシンボリックリンク経由の書き込み — 分類器に保護パスの書き込みを回すモードでは、要求されたパス自体は保護対象でなくても、シンボリックリンクの解決先が保護対象パスになる書き込みは、分類器ではなく人間への確認になります。

まとめ

--restrictedは、評価ハーネスや共有マシンでClaude Codeを動かすときに、実行系ツール・WebFetch・ローカル設定ファイルという3つの経路をまとめて締めるフラグです。使う機能を分けるのは、設定の読み込み元を固定したいのか、コマンドの到達範囲を閉じたいのかという問いです。前者なら--restrictedと--settings、後者ならBashサンドボックスが答えになります。同じv2.1.248では、この制限モードを含む49項目の更新が入りました。全体像はClaude Code v2.1.248で確認できます。同じ時期に追加されたhookとして、PreModelSwitch hookとPostModelSwitch hookでモデル切り替えを制御するもあります。