Claude Code の Sandbox 挙動を実測で確認する — allowUnsandboxedCommands と built-in ツールの振る舞い

はじめに

Claude Code の Sandbox 機能は、Bash コマンドの実行環境を制限し、プロジェクトディレクトリ外への書き込みやネットワークアクセスを制御する仕組みです。しかし、Sandbox を有効にした際の具体的な挙動、特にデフォルト設定での振る舞いや built-in ツールとの関係については、公式ドキュメントだけでは十分に把握しにくい部分があります。

本記事では、Claude Code v2.1.97 の Sandbox 挙動を実測で確認した結果を記録します。Hook や Sandbox の基本的な仕組みについては、hsaki 氏の「課題ベースで学ぶClaude Code便利機能」（Zenn）が体系的に整理しています。本記事はその前提の上で、Sandbox の実測面を補足するものです。

Claude Code の機能全体像については nogataka 氏の「Claude Code 完全リファレンス」（Qiita）が、MCP を含む包括的な解説については oga_aiichiro 氏の「0から分かる Claude Code 完全ガイド」（Zenn Books）がそれぞれ参考になります。

Sandbox の基本

Sandbox は .claude/settings.json で有効化します。

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true
  }
}

Sandbox が制限する範囲は大きく2つです。

制限対象	内容
filesystem	プロジェクトディレクトリ外への書き込みをブロック（Read-only file system）
network	外部ホストへの接続時に確認プロンプトを表示

重要な点として、これらの制限は Bash ツール経由のコマンド実行にのみ適用 されます。この点は後述します。

allowUnsandboxedCommands のデフォルト挙動

Sandbox の設定には allowUnsandboxedCommands というパラメータがあります。実測の結果、このパラメータは明示的に設定しない場合 true として動作することが確認されました。

デフォルト（true）の場合に何が起きるか

allowUnsandboxedCommands: true の状態で Sandbox が有効な場合、以下の挙動が確認されました。

1. Claude が Bash コマンドを実行する
2. Sandbox の filesystem 制約によりコマンドが拒否される（例: プロジェクトディレクトリ外への書き込み）
3. Claude が自動的に dangerouslyDisableSandbox パラメータを付与してコマンドを再実行する
4. この再実行にユーザーの追加承認は求められない

つまり、Sandbox を有効にしていても、デフォルト設定のままでは Sandbox の filesystem 制約で拒否されたコマンドが sandbox 外で自動的に再実行される場合があります。

実測で確認した挙動

Sandbox 有効環境で、プロジェクトディレクトリ外（例: /tmp）への書き込みを伴う Bash コマンドを実行させたところ、以下の流れが観測されました。

1回目: Bash(echo test > /tmp/sandbox-test.txt)
  → Read-only file system（Sandbox による拒否）

2回目: Bash(echo test > /tmp/sandbox-test.txt) [dangerouslyDisableSandbox: true]
  → 成功（Sandbox 制約なしで実行）

2回目の実行時、ユーザーへの追加の確認プロンプトは表示されませんでした。1回目の実行で承認済みのコマンドが、Sandbox を迂回して再実行された形です。

対策

.claude/settings.json で allowUnsandboxedCommands を明示的に false に設定します。

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

この設定により、Sandbox の filesystem 制約で拒否されたコマンドは再実行されず、そのままエラーとして処理されます。

この挙動の背景

allowUnsandboxedCommands のデフォルトが true であることは、段階的な Sandbox 導入における設計選択と考えられます。パラメータ名自体が allowUnsandboxedCommands（Sandbox 外コマンドを許容する）と明示的であり、ユーザーが設定で制御可能です。

Sandbox はまだ opt-in の機能であり、既存のワークフローとの互換性を維持しながら段階的に導入を進めるための移行用デフォルト値として、この設計が採用されていると推測されます。ただし、これは公開されている情報からの推測であり、Anthropic が公式に説明したものではありません。

built-in ツールと Sandbox の関係

Sandbox の filesystem 制約は、すべてのツールに一律に適用されるわけではありません。

Write ツール vs Bash ツール

同じ /tmp ディレクトリへの書き込みでも、使用するツールによって結果が異なります。

ツール	操作	結果
Bash	echo test > /tmp/test.txt	Read-only file system（ブロック）
Write	Write(/tmp/test.txt)	成功（Sandbox 制約を受けない）

この挙動は、built-in ツール（Read / Edit / Write）が Sandbox の filesystem 制約の対象外として設計されていることに起因します。

設計上の整理

Claude Code のツールは、Sandbox の観点から以下の2層に分かれています。

層	ツール	Sandbox filesystem 制約
built-in ツール	Read, Edit, Write 等	対象外
Bash ツール	Bash（シェルコマンド実行）	対象

built-in ツールは Claude Code 自体が直接実行するファイル操作であり、Sandbox とは別の信頼モデル（trust prompt による承認）で制御されています。一方、Bash ツールはシェルプロセスを起動して外部コマンドを実行するため、Sandbox の制約が適用されます。

Glob や Grep は読み取り専用ツールのため、filesystem 書き込み制約の影響を受けません。この区別は公式仕様として設計されたものであり、Sandbox が保護するのは Bash コマンドの実行範囲です。

Sandbox と trust prompt は独立している

Sandbox を有効にすると trust prompt（信頼確認プロンプト）の挙動が変わると思われるかもしれませんが、実測の結果、両者は独立して動作することが確認されました。

sandbox.enabled: true を設定した状態でも、以下の挙動は非 Sandbox 時と同一でした。

項目	Sandbox 有効時の挙動
Hook（PreToolUse）の発火タイミング	変化なし
Hook の stdin JSON 構造	変化なし
.claude/ 配下の trust-sensitive プロンプトの出現条件	変化なし
Option 2（セッショントラスト）の適用範囲	変化なし

Sandbox は Bash コマンドの実行環境を制限する仕組みであり、trust prompt はツール実行前のユーザー承認を管理する仕組みです。両者は異なるレイヤーで動作する独立した安全機構です。

Sandbox 固有のプロンプト

ただし、Sandbox 有効時に固有のプロンプトが1つ追加されます。外部ホストへのネットワーク接続時に表示される確認プロンプトです。

────────────────────────────────────────────────────────
 Network request outside of sandbox

   Host: example.com

   Do you want to allow this connection?
   > 1. Yes
     2. Yes, and don't ask again for example.com
     3. No, and tell Claude what to do differently (esc)

このプロンプトは通常の trust prompt とは構造が異なり、Sandbox 有効時にのみ出現します。

推奨設定

Sandbox を有効にする場合は、以下の設定を推奨します。

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

各パラメータの役割は以下の通りです。

パラメータ	値	効果
enabled	true	Sandbox を有効化
failIfUnavailable	true	Sandbox 環境が利用できない場合にエラーにする（サイレントに非 Sandbox で実行されることを防ぐ）
allowUnsandboxedCommands	false	Sandbox で拒否されたコマンドの自動再実行を無効化

allowUnsandboxedCommands: false を設定しない場合、Sandbox を有効にしていてもデフォルト設定では sandbox 外での再実行が自動で試みられる点に注意してください。

まとめ

本記事で確認した Sandbox の挙動を整理します。

項目	挙動
allowUnsandboxedCommands: true（デフォルト）	Sandbox で拒否された Bash コマンドが dangerouslyDisableSandbox 付きで自動再実行される。追加承認なし
allowUnsandboxedCommands: false	Sandbox で拒否されたコマンドはエラーのまま処理される
built-in ツール（Read/Edit/Write）	Sandbox の filesystem 制約の対象外として設計されている
Bash ツール	Sandbox の filesystem 制約の対象
trust prompt	Sandbox の有無で挙動は変化しない（独立した安全機構）
Hook（PreToolUse）	Sandbox の有無で発火タイミング・stdin 構造は変化しない
Sandbox 固有プロンプト	外部ネットワーク接続時に「Network request outside of sandbox」が表示される

Sandbox は Bash コマンドの実行環境を制限する仕組みであり、built-in ツールや trust prompt とは独立して動作します。デフォルト設定の挙動を正確に把握した上で、allowUnsandboxedCommands: false の明示設定を検討することをお勧めします。

検証環境

項目	値
Claude Code	v2.1.97
モデル	Opus 4.6 (1M context)
対話環境	tmux セッション + claude CLI
OS	Ubuntu (Linux)

関連記事

• 本記事の前編: Claude Code の trust prompt を実測で分類した — 5ファミリの識別と Hook との関係 — trust prompt の5ファミリ分類、Hook との関係、Option 2 のスコープを実測で検証
• hsaki 氏「課題ベースで学ぶClaude Code便利機能」（Zenn） — Hook / MCP / Skill / SubAgent を課題ベースで整理した記事
• nogataka 氏「Claude Code 完全リファレンス」（Qiita） — Claude Code の全機能を網羅したリファレンス
• oga_aiichiro 氏「0から分かる Claude Code 完全ガイド」（Zenn Books） — MCP を含む Claude Code の包括的な入門書