Refusing to read symlink resolution changedの意味と対処

Refusing to read symlink resolution changedは何を拒否しているのか

Refusing to read <path>: its symlink resolution changed after permission was checked は、Claude Codeがファイルを開く直前に「権限チェックで承認したときと、パスの行き先が違う」と判断して、読み取りそのものを実行しなかったことを示す表示です。ファイルの中身は読まれていません。

メッセージはツールの結果としてClaudeに返ります。原文は次の形です。

Refusing to read /path/to/file: its symlink resolution changed after permission was checked (a link on the way now leads somewhere the check did not see). If a link in the working directory is being rewritten concurrently, stop that and retry.

後半の「作業ディレクトリ内のリンクが並行して書き換えられているなら、それを止めて再試行する」が、公式が示す基本の対処です。

権限チェックのあとに、開く瞬間にもう一度確かめる

Claude Codeはファイルパスに対して権限ルールを照合し、そのあとツールがファイルを開く時点、または検索を始める時点でも、パスの解決先を確認し直します。承認した場所と同じ場所を指していると確認できなければ、リンクをたどらずに拒否します。

パスにシンボリックリンクが含まれる場合、権限チェックは2つのパスを見ます。Claudeが要求したパスと、それが解決される実ファイルです。許可ルールは両方が一致したときだけ当てはまり、拒否ルールはどちらかが一致すれば当てはまります。

この仕組みが必要になる理由は、チェックと実行のあいだに時間差があることです。チェックの時点では作業ディレクトリ内の無害なファイルを指していたリンクが、開く直前に別の場所へ張り替えられると、承認した範囲の外を読んでしまいます。チェック時と使用時のずれを突くこの種の問題はTOCTOU(time-of-check to time-of-use)と呼ばれます。開く瞬間の再確認は、そのずれを閉じるための動作です。

このメッセージは不具合ではなく、v2.1.251で追加された確認が働いた結果です。

文言ごとに止まっている理由が違う

Refusing to で始まる表示は1種類ではありません。同じ節に載っている文言を、対象ツールと状況で分けます。

最初の行が、このページで扱う文言です。読み取りの拒否では、括弧の中の語句が「どの比較に失敗したか」を表します。errorsページには括弧内の語句を列挙した表がありません。実際に出た文面をそのまま控えておくと、再現や問い合わせのときに役立ちます。

文言が permission check expired のときは、リンクが原因ではありません。ファイル操作が同時に多数走ったことで承認の記録が先に破棄された状態で、再試行すると権限チェックが新しくやり直されます。

自分の環境で出たときの切り分け

読み取りの拒否は、頻度で原因が分かれます。1回だけなら一過性の差し替え、同じパスで繰り返すなら誰かがリンクを書き換え続けています。次の順に確かめます。

Windowsでは別の症状もあります。AppContainerまたは制限付きトークンのサンドボックス内でClaude Codeを動かしていると、すべてのファイルで同じ拒否が出る不具合があり、v2.1.265以降で修正されています。1ファイルではなく全ファイルで出るなら、まずバージョンを確かめます。

繰り返すときの調べ方と、実パスで読ませる方法

パスの途中に何があるかは、シェルから確かめられます。次のコマンドは、対象ファイルの実体と、作業ディレクトリ内のリンクを一覧にします。<path> は拒否されたパスに置き換えてください。

realpath <path>
ls -ld <path>
find . -type l -ls

realpath の結果と元のパスが違えば、途中にリンクがあります。find . -type l -ls は、作業ディレクトリ配下のリンクとその向き先を並べます。同じリンクの向き先が時間をおいて変わるなら、張り替えている主体がいます。公式は例として、ビルドツールとファイル監視を挙げています。

張り替えを止められない場合は、Claudeへの指示で実パスを渡します。例えば次のような形です。

./current/report.md は symlink です。realpath で実体のパスを調べて、
そのパスを指定して読み直してください。

実体のパスで読めば、再確認の対象となるリンクを経由しません。ただし実体が作業ディレクトリの外にあると、許可ルールが両方のパスの一致を求めるため、別の許可が要ります。実体パスを Read ルールに書くときの起点の違いは、/path と //path の違いを扱った記事にあります。

版ごとに変わってきた拒否の範囲

この拒否は、一度にできたものではありません。変更履歴から、読み取りの拒否に関わる版を並べます。

別の警告との見分け方

シンボリックリンクと権限の話は、他のメッセージとも並んで出ます。名前が近いものを分けておきます。

• is not matched by file permission checks: 起動時の警告で、Write や NotebookEdit に書いたルールが参照されない設定上の問題です。書き換え先は専用の記事で扱っています
• Refusing to read 系: 実行時に、特定のファイル操作が拒否された結果です。設定の誤りではなく、そのときのパスの状態が原因です

前者は設定ファイルを直すことで消え、後者は設定を触っても消えません。リンクの状態か、張り替えている主体を見ます。

symlinkを通した権限判定は、その後もv2.1.268でdeny・askルールの適用範囲が広がりました。経緯はv2.1.268の記事にあります。リンクそのものを作れないworktreeの失敗は、worktree作成のsymlink失敗が別の原因を説明しています。

対処のまとめ

拒否は一度なら実害がありません。操作は実行されず、結果がClaudeに返るだけです。繰り返すときはリンクを張り替えている主体を探して止め、止められないときは実パスで読ませます。Windowsで全ファイルが拒否されるなら、v2.1.265以降へ更新します。macOSで何も書き換えていないのに出るなら、v2.1.273以降です。