worktree.bgIsolationでバックグラウンド編集を直接許可する仕組み

Claude Codeのバックグラウンドセッションは、既定でメインの作業コピーとは別のgit worktreeへ移動してからファイルを編集します。並列で走る複数のセッションが同じチェックアウトを壊さないための仕組みです。この隔離自体を止める設定がworktree.bgIsolationで、"none"にするとバックグラウンドジョブは.claude/worktrees/へ移動せず、開いている作業コピーを直接編集します。

worktree.bgIsolationは何を切り替えるのか

worktree.bgIsolationはsettings.jsonのworktreeオブジェクトに入る文字列型の設定で、値は"worktree"と"none"の2つです。ユーザー・プロジェクト・ローカルのどの設定ファイルにも書けます(設定リファレンスのScopeはAny file)。

{
  "worktree": {
    "bgIsolation": "none"
  }
}

設定リファレンスは"none"の使いどころを「git worktreeが実用的でないリポジトリ」と書くだけで、具体例までは挙げていません。worktreeの作成に時間がかかるリポジトリや、追加のチェックアウトを置く余裕がない環境が候補になりますが、これは記述からの推測で、閾値の目安は公式にありません。

bgIsolationはworktreeオブジェクトが持つ4キーの1つです。残りのbaseRef・symlinkDirectories・sparsePathsは「worktreeをどう作るか」を調整し、bgIsolationだけが「そもそも隔離するか」を決めます。"none"にしても、worktreeを作らなくなるのはバックグラウンドセッションだけです。--worktreeやEnterWorktree、isolation: worktreeのサブエージェントが作るworktreeには、この3つが引き続き効きます。

設定を変えなくても隔離されない4つの場面

bgIsolationが"worktree"のままでも、バックグラウンドセッションが最初からworktreeへの移動をスキップする場面があります。Claude Codeの公式ドキュメントは次の4つを挙げています。

設定は「隔離を試みない」という宣言で、4つの場面は「今回は隔離する意味がない」という個別の判定です。"worktree"のままなのに特定のセッションだけ直接編集していても、設定ミスとは限りません。逆に、"none"にして最初から直接編集になっていることを、4つの場面のどれかと取り違えるのも危険です。

手元のclaude v2.1.287で確認できる範囲

bgIsolationは設定ファイルの値なので、claude --helpにフラグは出ません。ヘルプに出るのは、隔離と後片付けの周辺コマンドです。v2.1.287のclaude --helpでは、バックグラウンド起動と削除まわりが次のように表示されます。

claude --help

  --bg, --background   Start the session in the background and return
                       immediately. Prints the id that `claude attach`,
                       `logs`, `stop` and `rm` take; `claude agents` lists them.
  -w, --worktree [name]  Create a new git worktree for this session
                       (optionally specify a name)
  ...
  rm <id>              Delete a background session, and its worktree
                       when that is safe. Works on sessions that have
                       already exited

-w, --worktreeは対話セッションを自分のworktreeで始めるためのフラグで、バックグラウンドセッションのbgIsolationとは別の入口です。claude rm <id>の説明に「worktreeを消すのは安全なときだけ」とあるのは、"worktree"運用で生まれるworktreeの後始末が前提だからです。"none"のセッションは自動ではworktreeへ移らないため、通常は消すworktreeがありません。

claude rm --helpでは、未pushのコミットが残るworktreeの扱いも確認できます。

Usage: claude rm <id> [--discard-unpushed <commit>@<worktree-id>]
                      [--force-remove-worktree <worktree-id>]

未pushのコミットを捨てるには--discard-unpushedに、前回のclaude rmが報告した値を渡す仕様です。claude rmは消えるものがあるときに値を報告して再実行を求める形になっています。確認できたのはヘルプの文面までで、bgIsolationを切り替えた実セッションの挙動は、モデルを呼ぶ操作になるため試していません。

隔離中にClaude Codeが止める操作

隔離されたセッションでは、Editなどの書き込みだけでなく、シェルまわりも4種類の検査を受けます。

• メインチェックアウトを指すEdit・Write・NotebookEdit
• 作業ディレクトリがメインチェックアウトに解決される、または外にとどまると確認できないBash・PowerShell・Monitorのコマンド
• git -CやGIT_DIRなどでgitをメインチェックアウトへ向けるコマンド
• gitがworktreeの外へ出ないとコマンド文から確認できない形のコマンド

最後の検査は無効にできません。サブエージェントにも同じ検査がかかり、拒否は「ツールエラー」として返ります。"none"は隔離そのものを外す設定なので、この検査の前提が成り立ちません。公式ドキュメントはこの検査を「隔離中」の動作として書いており、"none"のセッションにも同じ検査が効くとは書いていません。

サブエージェントと/forkはbgIsolationをどう扱うか

バックグラウンドセッションが起動するサブエージェントは、セッションの作業ディレクトリを引き継ぎます。編集はセッションのworktree("none"なら作業コピーそのもの)に入ります。サブエージェントだけ別のworktreeに隔離したいときは、frontmatterでisolation: worktreeを指定するか、起動時にisolation: "worktree"を渡します。

/forkでセッションを複製したときのコピーは、作業コピーを直接編集する場合を除いて、自分専用のworktreeを作ってから変更を始めるよう指示されます。セッションのコピーを作る/forkはv2.1.212以降です。v2.1.161〜v2.1.211では、同じ名前で別物のフォークされたサブエージェントが起動していました。この旧動作は現在/subtaskが担い、エージェントビューを無効にしている場合の/forkも旧動作のままです。git管理外では、フックで作ったworktreeから移ったコピーだけが指示を受けます。WorktreeCreateフックがなければ、コピーはその場で編集します。コピーの開始位置は、複製元の状況で4通りに分かれます。

1. 複製元がまだworktreeへ移動していない通常のバックグラウンドセッションなら、コピーも自分専用のworktreeへ移動してから編集します
2. 複製元がセッション開始後にリンク済みworktreeへ移動していたら、コピーは移動前の場所から始まり、そこで自分のworktreeを作ります。複製元のブランチは複製元のworktreeに残ったままなので、複製元の作業を土台にするタスクでは、そのブランチを起点に新しいブランチを切る指示が付きます
3. 複製元をリンク済みworktreeの中で起動していて、そのリポジトリにメイン作業ツリーがあるなら、コピーはメイン作業ツリーで始まります。自分専用のworktreeを作る点は2と同じですが、ブランチの起点についての指示は付きません
4. ベアリポジトリ構成のworktreeで起動された場合は、戻るメイン作業ツリーがなく、コピーはその場にとどまります

bgIsolationが"none"で、複製元がリンク済みworktreeの外にいる場合も、コピーは開いている作業コピーをそのまま編集します。このとき/forkの確認メッセージにはedits this checkoutと出ます。また、複製元がworktreeへ移動済みだったコピーは、そのworktreeでの編集・コマンド実行・立ち入りをしないよう指示されます。この禁止は隔離設定の値によらず付きます。

gitを使わないリポジトリでは何が起きるか

worktreeの隔離はgitを前提にしています。SVNやPerforceなどでは、WorktreeCreateとWorktreeRemoveのフックで作成・削除のロジックを肩代わりさせると、gitと同じ形で隔離できます。

フックのないgit管理外のディレクトリでは、バックグラウンドセッションは作業ディレクトリへ直接書き込み、互いに隔離されません。同じファイルを触る並列ジョブは避けるよう、公式ドキュメントも注意しています。

フックを設定していて失敗した場合の結果は、場所で分かれます。git管理外では、ブロックが解除されて作業ディレクトリへの直接編集に切り替わります。この解除はv2.1.203以降です。gitリポジトリの内部では逆に、セッションがworktreeへ移るまで共有チェックアウトへの書き込みがブロックされたままになります。

"none"にしたときの確認の挟まり方

隔離されたセッションがコードを変更したとき、Claude Codeはコミットして、リモートがあればブランチをpushするよう指示します。ドラフトプルリクエストはタスクの内容次第で開きます。main・masterへのpushとforce-push、マージは対象外で、タスクの指示やCLAUDE.md、メモリーでgit操作を自分で担当すると書いてあれば、そちらが優先されます。

bgIsolationが"none"のとき、worktreeへの移動に失敗したとき、すでに存在するworktreeの中でセッションが始まったときは、事情が変わります。この場合のセッションは、コミットやブランチ切り替えの前に確認を求めます。直接編集を許す代わりに、変更の確定は人の確認に戻す設計です。

"none"を選ぶと、この積み上げのうち確認なしのコミット・pushを手放すことになります。

利用形態ごとの効き方

まとめ

"none"は並列セッションの衝突回避とコミット確認の自動化を手放す代わりに、worktreeの作成コストを払わない選択です。切り替える前に、手元のセッションが4つの場面のどれかですでに直接編集になっていないかを確かめると、設定が実際に何を変えるのかを見誤りません。

worktree運用の全体像はClaude Code Worktree実践ガイドにまとめています。バックグラウンドセッションをスクリプトから操作する場合はclaude agents --jsonでバックグラウンドセッションを操作する、設定の全体像はClaude Code settings.json完全ガイドを参照してください。bgIsolationが追加された版の詳細はClaude Code v2.1.143にあります。隔離を外しても書き込みエラーが出る場合は、「path names a network location」の原因と対処が参考になります。