worktree.bgIsolationでバックグラウンド編集を直接許可する仕組み
worktree.bgIsolationを"none"にするとバックグラウンドセッションが作業コピーを直接編集します。設定を変えなくても隔離が外れる4条件と、サブエージェント・/forkとの相互作用を扱います。
Claude Codeのバックグラウンドセッションは、既定でメインの作業コピーとは別のgit worktreeへ移動してからファイルを編集します。並列で走る複数のセッションが同じチェックアウトを壊さないための仕組みです。この隔離自体を止めたいときに使うのがworktree.bgIsolationという設定で、"none"にするとバックグラウンドジョブは.claude/worktrees/へ移動せず、開いている作業コピーを直接編集するようになります。
worktree.bgIsolationとは何か
worktree.bgIsolationはsettings.jsonのworktreeオブジェクトに含まれる文字列型の設定で、値は"worktree"と"none"の2つです。既定値は"worktree"で、セッションがEnterWorktreeツールを呼んで自分のworktreeへ移るまで、メインの作業コピーへのEdit・Writeはブロックされます。"none"にすると、この移動とブロックの両方が発生せず、バックグラウンドジョブは最初から開いている作業コピーへ直接書き込みます。
設定できる場所: ユーザー(~/.claude/settings.json)・プロジェクト(.claude/settings.json)・ローカル(.claude/settings.local.json)・管理設定のいずれでも指定できます。組織全体でworktree運用を統一したい場合は管理設定側に置けば、個々の開発者が上書きできない形で固定できます。
{
"worktree": {
"bgIsolation": "none"
}
}公式ドキュメントが挙げる"none"の使いどころは、git worktreeの作成・破棄自体が実用的でないリポジトリです。巨大なモノレポでworktreeを作るたびにビルド成果物や依存関係の再構築が走って重い場合や、CIサンドボックスのようにworktree用のディスク領域を確保できない環境が該当します。
同じworktreeオブジェクトの他の設定との違い
bgIsolationはworktreeオブジェクトが持つ4キーの1つです。残り3つ(baseRef・symlinkDirectories・sparsePaths)とは役割がはっきり分かれます。worktree.baseRefは新しいworktreeをorigin/<default-branch>から作るか(既定の"fresh")、ローカルのHEADから作るか("head")を選ぶ設定、worktree.symlinkDirectoriesはnode_modulesのような大きなディレクトリを複製せずシンボリックリンクする設定、worktree.sparsePathsはgitのsparse-checkoutで必要なディレクトリだけをworktreeにチェックアウトする設定です。この3つはいずれも「worktreeをどう作るか」を調整するのに対し、bgIsolationだけが「そもそもworktreeへ隔離するかどうか」を切り替えます。"none"にすると他の3設定は意味を持たなくなります(worktree自体が作られないため)。
"none"にしなくても直接編集になる4つの条件
bgIsolationの値を変えなくても、Claude Codeが最初からworktreeへの移動をスキップする場面が4つあります。
- セッションがすでにリンク済みのgit worktreeの中にいる(Claude Codeが
.claude/worktrees/配下に作った場合も、git worktree addで自分で作った場合も対象) - 編集対象のファイル自体がリンク済みのgit worktreeの中にある(セッションやサブエージェントが
git worktree addで作ったものを含む) - 作業ディレクトリがgitリポジトリでなく、
WorktreeCreateフックも設定されていない - 書き込み先が作業ディレクトリの外にある
この4条件はbgIsolationによる設定全体での隔離の無効化とは別物です。設定は「そもそも隔離を試みない」という宣言であるのに対し、4条件は「今回のケースでは隔離する意味がない」という個別の判定です。両者を混同すると、bgIsolationを"worktree"のままにしているのに特定のセッションだけ直接編集される挙動を、設定ミスと誤解しかねません。
サブエージェントと/forkはbgIsolationをどう継承するか
バックグラウンドセッションが起動するサブエージェントは、既定でセッションの作業ディレクトリをそのまま引き継ぎます。つまりサブエージェントの編集は親セッションのworktree(またはbgIsolation: "none"なら作業コピーそのもの)に入ります。サブエージェントだけを別のworktreeに隔離したい場合は、frontmatterでisolation: "worktree"を指定するか、起動時に同じ値を渡します。
/forkでセッションを複製したときの挙動もbgIsolationと連動します。複製されたコピーは、作業コピーを直接編集する場合を除いて、自分専用のworktreeを作ってから変更を始めるよう指示されます。どこから複製が始まるかは、複製元のセッションが今どこで動いているかで4通りに分かれます。
- 複製元がまだworktreeへ移動していない通常のバックグラウンドセッションの場合、コピーも他の起動経路と同じく自分専用のworktreeへ移動してから編集を始めます
- 複製元がセッション開始後にリンク済みworktreeへ移動していた場合、コピーは複製元が移動する前にいた場所から始まり、そこで自分専用のworktreeを作ります。複製元のブランチがそのworktreeにチェックアウトされたままなので、複製元の作業を土台にするタスクではそのブランチを起点に新しいブランチを作るよう指示されます
- 複製元がメイン作業ツリーを持つリポジトリのリンク済みworktree内で起動されていた場合、コピーはそのメイン作業ツリーで始まり、自分専用のworktreeを作るところは2と同じです
- ベアリポジトリ構成のworktree内で起動されていた場合はメイン作業ツリー自体が存在しないため、コピーはその場にとどまります。
bgIsolationが"none"でworktree隔離自体がオフになっているセッションから複製した場合も、コピーは開いている作業コピーをそのまま編集するという同じ扱いになります
さらに、複製元自身がworktreeの外(通常のバックグラウンドセッションが最初にいる場所)から移動済みだった場合、コピーはその複製元のworktreeを編集・コマンド実行・立ち入りのいずれも行わないよう指示されます。これはbgIsolationの値に関係なく適用される規則で、"none"にしていても複製元と複製先が互いのworktreeを踏み荒らさない仕組みは別に効いています。
gitを使わないリポジトリでの扱い
bgIsolationのworktreeベースの隔離はgitの機能を前提にしています。SVNやPerforceなど別のバージョン管理システムを使っている場合は、WorktreeCreateとWorktreeRemoveのフックを設定することで同じ仕組みの隔離を再現できます。フックが作業コピー相当のディレクトリを作成・削除するロジックを肩代わりする形です。
フックを設定していないgit以外のリポジトリでは、隔離自体が働かず、バックグラウンドセッションは作業ディレクトリへ直接書き込みます。この場合、並列で複数のバックグラウンドセッションを同じファイルへ向けて走らせると衝突を自分で管理する必要があります。フックを設定していてもそのフックが失敗した場合は、Claude Codeがブロックを解除して作業ディレクトリでの直接編集に切り替わります。この解除はClaude Code v2.1.203以降で有効です。gitリポジトリの内部でフックが失敗した場合は逆に、セッションがworktreeへ移動するまで共有チェックアウトへの書き込みがブロックされたままになります。
bgIsolationを切り替えても残る安全弁
隔離されたセッションが変更を終えるとき、Claude Codeはコミットとpushを確認なしで行い、リポジトリにリモートがあればブランチをpushし、タスクの内容次第でドラフトプルリクエストを開きます。mainやmasterへのpushやマージ、force-pushは行いません。CLAUDE.mdやメモリーでgit操作の扱いが指示されている場合はそちらが優先されます。
一方、bgIsolationが"none"になっている、worktreeへの移動が失敗した、あるいはセッションが既存のworktreeの中で始まった場合は、この「確認なしでコミット・push」という扱いにはならず、コミットやブランチ切り替えの前に確認を挟みます。隔離を外すことは、直接編集を許可する代わりに、変更の確定操作については人手の確認を残すという設計になっています。
worktree.bgIsolationはどのリポジトリで使う価値があるか
隔離まわりの挙動はbgIsolationが入った版から段階的に補強されてきました。
| バージョン | 変更内容 |
|---|---|
| v2.1.143 | 変更内容worktree.bgIsolation設定が追加される |
| v2.1.198 | 変更内容worktreeで隔離されたバックグラウンドセッションが、確認なしでコミット・pushし、必要ならドラフトPRを開くようになる |
| v2.1.203 | 変更内容非gitディレクトリでWorktreeCreateフックが失敗したとき、ブロックを解除して直接編集に切り替わるようになる |
| v2.1.221 | 変更内容/forkのコピーに隔離の指示が入り、複製元のworktreeや作業コピーを荒らさないようになる |
bgIsolation単体は「隔離するかしないか」の二択ですが、この表が示すのは隔離まわりの安全策(コミット確認・フック失敗時のフォールバック・forkコピーの立ち入り制限)が別々のタイミングで積み上げられてきたという流れです。"none"を選ぶ判断は、この安全策の一部(確認なしのコミット・push)を手放す判断でもあります。
利用形態によって、"none"が持つ価値ははっきり分かれます。
| リポジトリ・運用の形態 | おすすめ度 | 理由 |
|---|---|---|
| 数百MB超のモノレポでworktree作成が遅い | おすすめ度◎ | 理由worktreeの作成・破棄コストを毎回払わずに済む |
| ディスク領域が限られたCIサンドボックス | おすすめ度◎ | 理由worktree用の追加チェックアウトを持てない環境で隔離自体を諦められる |
gitを使わないリポジトリ(WorktreeCreateフック未設定) | おすすめ度条件次第 | 理由隔離自体が最初から効かないため、bgIsolationの値によらず直接編集になる |
| 複数のバックグラウンドセッションを同じファイル群に同時実行する運用 | おすすめ度△ | 理由隔離を外すと衝突管理が自己責任になるため、同じファイルを触りうるセッションを同時に走らせない運用が前提になる |
| 通常サイズのgitリポジトリで単発のバックグラウンドタスクを回す | おすすめ度ほぼ影響なし | 理由既定の"worktree"のままでworktree作成コストは無視できる水準 |
まとめ
worktree.bgIsolationは、バックグラウンドセッションによるworktreeへの隔離を丸ごと止めるためのsettings.jsonの設定で、既定値は"worktree"、"none"にすると作業コピーへ直接編集します。ただし"none"にしなくてもリンク済みworktreeの内部にいる場合など4つの条件では最初から隔離がスキップされ、逆に"none"にしても、隔離されなかったセッションはコミットやブランチ切り替えの前に確認を求められます。サブエージェントは親セッションの作業ディレクトリをそのまま継承し、/forkのコピーはv2.1.221以降、複製元のworktreeや作業コピーを荒らさない指示を受け取ります。設定を触る前に、この4条件と安全弁の存在を押さえておくと、"none"が実際に何を変え、何を変えないのかを見誤りません。
worktree運用の全体像はClaude Code Worktree実践ガイドにまとめています。バックグラウンドセッションをスクリプトから操作する場合はclaude agents --jsonでバックグラウンドセッションを操作する、設定の全体像はClaude Code settings.json完全ガイドを参照してください。bgIsolationが追加された版の詳細はClaude Code v2.1.143にまとめています。隔離を外した状態で書き込みエラーに遭遇した場合は「path names a network location」の原因と対処も参考になります。