Claude Code 2.1.314 如何限制目錄外寫入？

Claude Code 的工作目錄邊界若只在命令列工具上生效，代理仍可能透過另一種檔案工具把內容寫到預期目錄之外。Anthropic 在 2026 年 10 月 30 日發布的 Claude Code v2.1.314 加入 permissions.blockWritesOutsideWorkingDirectories，讓 Write、Edit 與 NotebookEdit 在各種 permission mode 下拒絕工作目錄以外的路徑。採用前要核對專案路徑與自動化流程。

一、Claude Code 的工作目錄外寫入，曾在哪種流程造成問題？

GitHub issue #88038 的作者回報，Claude Code 在 worktree 中執行自動化任務時，Write 將檔案寫入另一個同專案檢出區，後續提交因而落到非預期分支；這是單一使用者的重現描述，不代表官方確認的普遍行為。

Git worktree 自動化中的越界寫入回報

issue 作者描述的情境是：每項工作各自啟動一個 Claude Code 命令列工作階段，並以 Git worktree 隔開任務。作者在 macOS、非互動模式及 acceptEdits 權限模式下，比較 Bash 與 Write 對同一個 worktree 外絕對路徑的寫入；依其回報，Bash 被拒絕，Write 卻成功建立檔案。作者另提到，真實自動化工作中，檔案落到同一專案的另一個 checkout，後續 git commit 將它提交到人員當時使用的分支，形成重複且非預期的提交。issue 說明該次情況沒有資料遺失，也沒有推送出去。

這個案例的讀者回報集中在工具邊界不一致：啟動目錄雖是 worktree，流程卻同時使用不同寫入工具；若只測 Bash，就無法知道 Write 或 Edit 是否遵守相同路徑限制。可參考站內的Claude Code 權限更新檢查項目，再依目前版本實測。

從 issue 報告區分個案與普遍行為

#88038 在 GitHub 上標示為「not planned」關閉，issue 狀態只能說明該討論串如何結束，不能用來證明所有版本都存在同一問題，也不能當成 v2.1.314 已普遍修復的證明。較早的 #7150 也有使用者回報代理修改工作目錄之外的檔案，之後以重複問題關閉；但環境、版本與重現方式不同。

這些回報可用來設計測試案例，不能代替版本說明與本機驗收。核心問題有三層：專案路徑、Claude Code 認定的工作目錄、實際寫入工具。若三者未對齊，只看啟動路徑容易誤判寫入範圍。

二、2.1.314 新設定實際限制哪些檔案操作？

Anthropic 的發布說明列出 permissions.blockWritesOutsideWorkingDirectories，並指明 Write、Edit、NotebookEdit 在各 permission mode 下會拒絕工作目錄以外的路徑；說明沒有把 Bash、MCP 或其他外部程序列入這項承諾。

設定名稱與官方列出的工具範圍

v2.1.314 的官方發布說明將這項功能描述為新增權限設定。依發布文字，需逐一檢查 Write（建立或覆寫檔案）、Edit（修改檔案）和 NotebookEdit（編輯筆記本）。發布說明沒有交代符號連結如何解析、所有路徑正規化細節，也沒有宣稱這一項設定等於作業系統層級的完整檔案系統隔離。

Anthropic 的 v2.1.314 發布說明列明：「Write, Edit and NotebookEdit refuse paths outside the working directories in every permission mode.」這段文字確認的是列出的工具與工作目錄邊界，不能延伸解讀為所有檔案操作都必然受限。

已經熟悉 Claude Code 權限規則的讀者，也可搭配Claude Code 沙箱啟動與 Bash 檢查方式理解兩者差異：Bash 沙箱與此設定並非同一個驗證項目。應以本機版本文件及測試結果為準，不要因其他工具受限，就推論檔案工具也具備相同行為。

工作目錄與額外工作目錄如何影響邊界

工作目錄是 Claude Code 工作階段使用的主要路徑；額外工作目錄是使用者加入的其他路徑。Git repo、worktree、共用規格檔、測試輸出、建置產物和暫存目錄可能各在不同位置。設定提到「working directories」時，實務上要先盤點目前工作階段實際納入的路徑，並以目前版本說明確認額外目錄的處理方式。

不要把 repo 根目錄、worktree 路徑和系統理解的「整個檔案系統」當成同一個範圍。若 Claude Code 在子目錄啟動，任務卻要更新上層共用檔案，預期允許與否必須先在該環境測試；加入額外目錄也會改變工作階段能接觸的路徑清單。可把路徑記錄在啟動文件或自動化設定中。

三、為什麼加上寫入限制仍要盤點專案流程？

限制工作目錄外寫入可能擋下原本需要跨目錄的操作，例如 Git worktree 共用的 Git 內部資料或產生到專案外的輸出；而 Bash、MCP 與外部程序也須分開驗證，不能由三種檔案工具的說明代為推定。

Git worktree 共用資料與跨目錄需求

Git worktree 讓同一個 Git 專案可以同時檢出多個工作樹，但部分版本庫內部資料仍由不同 worktree 共用。GitHub issue #26262 的作者回報，在其啟用 Claude Code sandbox 的環境中，worktree 執行 git add、commit 或 push 時，因 Git 需要寫入工作目錄以外的共享資料而失敗。作者提及的錯誤包括無法建立 index.lock，案例涵蓋 bare repo 及一般 clone 配置。這是使用者對 sandbox 工作流的回報，不能當成新設定的測試結果；它提醒開發者檢查禁止越界與允許必要跨目錄寫入，可能同時牽涉一套流程。

生成文件、匯出報告、更新 monorepo 內相鄰套件、寫入快取或暫存檔，也可能依賴工作目錄之外的路徑。啟用限制前，先問每個自動化任務：讀取哪些路徑、由哪個工具寫入、產物應落在哪裡、Git 元資料存在哪裡。若必要操作遭拒，先釐清路徑與工具，再調整工作目錄或流程，不宜立刻擴大允許範圍。

檔案工具、命令列與外部工具要分開驗證

官方發布說明明列 Write、Edit 與 NotebookEdit。Bash 執行的命令、MCP（模型上下文協定）工具、IDE 外掛或其他外部程序各有不同執行路徑；這份版本說明不足以證明它們都會被 blockWritesOutsideWorkingDirectories 攔截。Bash 若另受 sandbox 或命令權限約束，也應當作獨立控制來測。如此可分辨成功或拒絕由哪道規則造成。

#26262 的 issue 作者寫道，worktree 的 Git 寫入會因共享內部資料位於工作目錄之外而失敗。這則個案支持「先盤點跨目錄需求」的測試方向，不證明新設定會以相同方式影響所有 Git 工作流。

安全邊界不只一個設定開關。目錄權限、版本控制隔離、容器或作業系統沙箱、工具授權與人工審核都可能位於不同層次。要防止代理更動敏感檔案，需依威脅模型安排多層控制，再逐一驗證；單一設定不能代表所有工具和路徑。

四、整合前如何驗證代理的寫入範圍？

在隔離的測試 repo 中準備目錄內外的哨兵檔案，逐一用 Write、Edit、NotebookEdit 測試相對與絕對路徑，再測額外目錄、符號連結及既有自動化命令，並記錄每次允許或拒絕的結果。

建立目錄內外的測試路徑

先建立可丟棄的測試專案，不要用正式程式碼或重要資料測試。至少建立三個位置：工作目錄內的檔案、工作目錄旁的檔案，以及另一個無關目錄中的檔案。為每個位置放入不同文字的哨兵檔案，記下測試前內容和雜湊；每次操作後檢查檔案是否建立或改動，不只看代理回覆。

1. 記下 Claude Code 版本、permission mode、啟動工作目錄、額外工作目錄及作業系統。
2. 對同一組測試路徑，分別透過 Write、Edit、NotebookEdit 嘗試建立與修改檔案。
3. 以相對路徑與絕對路徑各跑一次，逐一確認工作目錄內、外的結果。
4. 加入實際使用的額外目錄、符號連結、worktree 與生成檔案路徑，確認允許範圍是否符合預期。
5. 單獨測試 Bash、MCP 或其他外部工具，再執行原有自動化流程，確認 git add、commit 及產物輸出位置。
6. 清除測試檔並保存結果，升級 Claude Code 後重跑相同案例。

檢查相對路徑、絕對路徑、符號連結與額外目錄

相對路徑依執行時的目錄解析；絕對路徑則直接指定完整位置。測試時應涵蓋 ./inside.txt、指向上層的相對路徑，以及工作目錄外的絕對路徑。符號連結另建在測試目錄中，分別指向目錄內和目錄外位置，觀察工具實際採用的路徑判定。結果只適用於測試的版本與環境。

額外工作目錄需分兩組驗證：先不加入該路徑，再透過團隊實際採用的設定或啟動方式納入，確認預期寫入是否相應改變。若某工具拒絕寫入，記錄錯誤訊息、工具名稱、目標路徑和設定狀態；若工具成功，也檢查檔案真正落點。不要把模型說「已完成」當成檔案寫入證據。

記錄允許與拒絕結果，確認既有流程仍可運作

測試記錄至少保留四項：Claude Code 版本、permission mode、主工作目錄與額外目錄設定。再補上工具名稱、輸入路徑形式、實際目標位置和結果。設定或版本變更後，用同一組案例重跑，並加測 worktree 建立、報告產生及提交變更。

• v2.1.314 發布說明明列的工具是 Write、Edit 與 NotebookEdit。
• GitHub issue 是個別使用者的問題回報，可用來設計測試，不能視為官方對普遍行為的確認。
• 先盤點工作目錄、額外路徑與跨目錄需求，再逐工具測試並檢查實際檔案落點。
• Bash、MCP 與外部程序須獨立驗證；測試結果要附版本、權限模式及目錄設定。

設定是否適用，取決於專案目錄與工具如何協作。列出工作階段會接觸的路徑，再以目錄內外測試核對限制和流程。跨目錄產檔時，可分享配置與驗證紀錄。

常見問題

Q1: Claude Code 2.1.314 的寫入限制管到 Bash 嗎？

發布說明列出的是 Write、Edit 與 NotebookEdit。Bash 是否受其他 sandbox 或命令權限控制，需另外測試，不能由這項設定推定。

Q2: 工作目錄以外的額外目錄能不能寫？

要依目前版本、工作階段目錄配置及實測結果判斷。先測未加入額外目錄的情況，再測加入後的差異，並確認檔案實際落點。

Q3: 啟用限制會不會讓 Git worktree 不能提交？

是否影響提交取決於工作目錄、Git 內部資料位置及使用的控制機制。#26262 是舊 sandbox 情境中的使用者回報，不是 blockWritesOutsideWorkingDirectories 的普遍測試結論；應在隔離環境測試 git add、commit 等必要操作。

Q4: 測試要記錄哪些條件？

至少記下 Claude Code 版本、permission mode、工作目錄、額外目錄設定、使用工具、目標路徑及允許或拒絕結果。版本或配置改變時，以同一組測試重新核對。