macos-permissions

macOS の権限ダイアログ

まず報告された問題を観察し、分類します

実行中のエージェントは、ユーザーの症状をそのまま保持します。クリック、入力、または閉じることができないダイアログは、パスワード欄が含まれていても、操作に関する診断が必要です。その報告を、パスワードを入力するよう促す指示に置き換えないでください。

サブシステムを選択したり、担当者を特定したりする前に、実際のダイアログを確認してください。ホストで許可されている観察ツールを使用します。画面全体の観察が許可されている場合は、ウィンドウを前面に出さずに、capture-screen の全画面ルートを使用してください。保護されたアプリの操作を拒否されても、見えていないダイアログの特定にはならず、あらゆる観察方法が利用できないことの証明にもなりません。拒否の適用範囲を尊重し、ホストの制限や GUI ロックを回避するためにツールを切り替えないでください。

観察されたダイアログまたは問題	対応先
キーチェーン項目へのアクセス失敗、login キーチェーンのパスワード、またはブロックされたキーチェーンウィンドウが確認された場合	キーチェーンの復旧を参照してください
プライバシーリソースの要求、または可視のダイアログを伴わない保護対象の操作の失敗	以下の TCC 手順に進んでください
スクリプト、Git フック、またはアプリケーション固有の確認	そのタスク／ツールの担当者を通じて要求を調べてください。TCC またはキーチェーンの設定は変更しないでください
内容または担当者がまだ不明	不明のままにしてください。不足している許可された観察情報だけを取得するか、表示されたテキストをユーザーに尋ねてください

これらはオペレーターによる判断であり、自動的なダイアログ分類ではありません。

TCC の診断

macOS は TCC（Transparency, Consent, Control）を通じて、アプリごと、リソースごとのアクセスを制御します。TCC は権限の決定をデータベースに記録し、プロセスが実行できる操作を制御します。よくある落とし穴には、それぞれ異なる対処が必要です。

落とし穴	症状	対処方法
誤った対象に許可を付与	ダイアログに python3.11／2.1.232／node と表示される。その対象に許可を付与しても、再びプロンプトが表示される	以下の帰属の落とし穴
許可が維持されない	動作していたが、バイナリ／uv／CLI の更新後にプロンプトが再び表示される	references/uv-fda-trap.md
サイレントな拒否	機能が「利用不可」と表示され、ダイアログはなく、許可は ON に見える	references/tcc-mechanics.md § auth_value
TCC.db を読み取れない	DB の読み取り時に Permission denied が発生する。FDA を診断するために FDA が必要	references/tcc-mechanics.md § SIP

帰属の落とし穴

まず報告された拒否を再現します

実行エージェントは、タスク専用のハンドルと保持されている結果を使って、最初に元の保護対象の操作を確認します。同じリソース、要求元、実行コンテキストについて、現在の証拠を再利用します。実行中のリクエストは既存の期限内に収め、終端状態が不明な間は代わりのリクエストを開始しないでください。現在の証拠がないか古くなっている場合は、権限を修復する方法を選ぶ前に、実際に失敗した要求元とコンテキストを通じて、期限を設けた読み取りを1回実行します。ファイル一覧、別のターミナル、SSHアクセス、フォアグラウンドでの実行では、その操作の代わりになりません。パス／リソース、要求元、コンテキスト、結果を記録してください。これは診断手順であり、機械的に権限を分類するものではありません。

その読み取りが成功した場合は、現在はアクセス可能。以前の原因は不明と報告し、特定の必要な読み取りにまだ失敗している場合を除いて、権限の変更をやめます。原因とその修正を示す証拠がない限り、原因が修復されたとは言わないでください。また、過去のエラーを消すためだけにフルディスクアクセスを追加したり、ACLを変更したり、共有マウントに再接続したり、共有ホストを再起動したりしないでください。読み取りが引き続き失敗する場合は、以下の原因特定チェックに進んでください。Operation not permittedだけでは、原因がTCCだとは断定できません。

ダイアログに表示された名前は、誰に権限を付与すべきかを示すものではありません。 macOSはプロセスツリー内の責任プロセスにリクエストを帰属させますが、表示するのはアクセスしている実行ファイルの名前です。また、バンドルのない署名なしバイナリ（uvが管理するpython、バージョンごとのCLI、nodeヘルパー）の場合、表示名はパスの最後の要素にすぎず、バージョンごとに変わります。表示された名前に権限を付与するのは、最も多くのやり直しを招く間違いです。

システム設定に触れる前に、リクエストと読み取り可能な付与状態を確認してください：

# 1. Who is actually requesting — the responsible process in the attribution chain
/usr/bin/log show --last 30m --predicate 'subsystem == "com.apple.TCC"' --info --debug \
  | grep -E 'from Sub:|responsible=|accessing=' | tail -20

# 2. Grant candidates, if this terminal can read the system database
sudo -n sqlite3 '/Library/Application Support/com.apple.TCC/TCC.db' \
  "select service, client, auth_value from access where service='kTCCServiceSystemPolicyAllFiles' and client like '%<name>%';"

from Sub:を使って要求元の候補を特定し、許可する対象を決める前に、その正確なパスと保護対象の実際の読み取りを確認してください。TCC.dbを読み取れない場合、権限付与状態は不明です。FDAのブートストラップについてはreferences/tcc-mechanics.mdを参照してください。 プリフライトログや許可された付与レコードを解釈する場合は、権限を修復する方法を選ぶ前に、プリフライトと権限付与の証拠を照合するを最初に読み込んでください。

判断ツリー

状況	参照先
ユーザーがフルディスクアクセスの修復の自動完了を求めている、またはバックグラウンドジョブが保護されたファイルを必要としている	references/automated-full-disk-access.md（まず確認済みの既存の権限付与を再利用し、なければシステム設定を操作して結果を読み返します）
「許可」をクリックしてもダイアログが再び表示される、またはLaunchAgent／uv runジョブで数分ごとにプロンプトが表示される	references/uv-fda-trap.md（要求元を特定し、権限を追加する前に自動修復の手順に従います）
kTCCServiceの全カタログ、スキーマ、auth_value／auth_reasonの意味、tccutilが必要	references/tcc-mechanics.md
TCC.dbを読み取ろうとすると「Permission denied」と表示される	references/tcc-mechanics.mdの「SIPとFDAのブートストラップ」
付与済みの権限がアップデート後に突然機能しなくなった	references/tcc-mechanics.mdの「一般的な失敗パターン」（オフ／オンを切り替える、またはtccutil reset <Service> <bundle-id>を実行する）
Automation／Apple Eventsの権限付与が保持されない	references/tcc-mechanics.md — コントローラーとターゲットの両方に権限が必要です

中核となるルール（実際に発生した事例に基づく）

• ダイアログ名 ≠ 要求元のプロセス。 TCC ログの from Sub: は要求元を示します。タイトルはアクセスしているバイナリのベース名であり、バージョンによって変わります。実際のパスを指定して許可してください。 （2026-09-19：uv の FDA ダイアログには python3.11 と表示されましたが、要求元は ~/.local/bin/uv だったため、python の許可、セッションタイプの変更、バージョンの固定はいずれも失敗しました。）
• 許可は識別情報ではなく、バイナリの正確なパスに紐づきます。 署名されていない実行ファイル（uv 管理の python、バージョンごとの CLI、node ヘルパー）は、パスが変わるたびに TCC にとっての 新しい アプリになります。そのため、更新後に「昨日は動いたのに、今日は許可を求められる」ということが起こります。Claude Code の問題 #74234 / #84948 / #86706 と同じ根本原因です。
• 「ヒット数が 0／捕捉できない」は計測上の問題であり、結論ではありません。 マシンによっては fs_usage が 0 バイトを出力することがあり、短時間で終了するプロセスはログの時間範囲から外れることがあります。また、空の grep ファイルは実際にゼロ件の場合と見分けがつきません。どの操作が許可ダイアログを引き起こすか特定するには、fs_usage ではなく、プロセス内で sys.addaudithook を使って open イベントを記録し、tccd のタイムスタンプと照合してください。
• SIP によってシステムの TCC.db は読み取り専用で保護されています。 コマンドラインから許可を INSERT／UPDATE することはできません。許可は GUI から行う必要があります。auth_value は読み取れますが、書き込みはできません。
• 許可した後は、再起動を検討する前にリクエストの結果を確認してください。 以下のリクエストのライフサイクルに従ってください。再起動が必要かどうかは、許可をクリックしたかではなく、権限とアプリケーションによって異なります。

許可またはリセット後

実行中のエージェントは、タスクが所有するプロセス／ツールのハンドルを通じて元のリクエストを確認し、同じ要求元と実行コンテキストで、指定された保護対象の操作を再試行します。 これらはオペレーターが行う確認です。この Skill がプロセスのライフサイクルを自動的に管理することはありません。

1. 元のリクエストがまだ実行中の場合は、そのまま動作させ、既存の期限内で実際の結果が返るのを待ちます。Automation／AppleEvent のリクエストは、要求元を再起動しなくても許可後に完了することがあります。ダイアログが閉じたことやスイッチが有効になったことは、成功を意味しません。
2. 待機がタイムアウトした場合は、再試行する前に元のリクエストの最終結果を確認します。ツールの待機が終了しても、それだけでは基盤となるリクエストが終了した証拠にはなりません。結果を確認できない場合は、状態を不明のままにしてください。後から許可しても、期限切れのリクエストを成功させることはできません。元のリクエストが終了したら、アクセスを確認する必要に応じて、読み取り専用のクエリを制限時間付きで一度だけ新たに実行してください。業務上の処理を繰り返す前に、副作用がすでに完了していないか確認してください。
3. アクセスに引き続き失敗する場合は、正確な要求元、権限、アプリケーション固有の再起動要件を確認します。必要な要件、または観測された失敗によって必要と判断される場合に限り、タスクが所有するプロセス、または作業が保全されることが明示的に許可された対象だけを再起動してください。別のセッションのプロセスを終了する前、または共有サービスを再起動する前に、その操作自体への明示的な許可と、実行中の作業を保全することの両方を確認してください。両方が確認できない場合は、その修復を保留したまま、独立した診断を続けてください。
4. 必要な再起動後は、実際のコンテキストで保護対象の操作を再実行します。成功したら権限の変更を止めてください。許可の記録があるだけでは、処理が動作する証明にはなりません。

対象範囲

このスキルが担当するのは権限の診断と修復です。次の事項は対象外です：アプリの権限オンボーディング UX の構築（アプリ開発作業のため、ここでは対象外）、launchd ジョブの設計（macos-watchdog）、ディスクのクリーンアップ（macos-cleaner）。これらは TCC の壁に突き当たった場合に、ここへ案内します。