macOS Permissions (TCC)
macOS gates per-app, per-resource access through TCC (Transparency, Consent, Control). TCC records permission decisions in its databases and controls what a process can do. Several common traps need different fixes:
| Trap | Symptom | Fix lives in |
|---|---|---|
| Wrong subject granted | Dialog names python3.11/2.1.232/node; you granted that but it still prompts | The attribution trap below |
| Grant doesn't survive | Worked, then a binary/uv/CLI update → prompt returns | references/uv-fda-trap.md |
| Silent denial | Feature "unavailable", no dialog, grant looks ON | references/tcc-mechanics.md § auth_value |
| Can't read TCC.db | Permission denied reading the DB; need FDA to diagnose FDA | references/tcc-mechanics.md § SIP |
The attribution trap
The name in the dialog does not prove who to grant. macOS attributes a request to the responsible process in the process tree, but displays the name of the accessing executable — and for an unsigned binary with no bundle (uv-managed python, per-version CLI, node helpers) that display name is just the last path component, which changes with every version. Granting the displayed name is the mistake that costs the most rounds.
Before touching System Settings, inspect the request and any readable grant state:
bash# 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>%';"
Use from Sub: to identify a candidate requester, then verify its exact path and a real
protected read before choosing what to authorize. An unreadable TCC.db leaves grant state
unknown; its FDA bootstrap is in references/tcc-mechanics.md.
Decision tree
| The situation is… | Go to |
|---|---|
| User asks to complete Full Disk Access repair automatically, or a background job needs protected files | references/automated-full-disk-access.md (reuse a verified existing grant first; otherwise drive System Settings and read back) |
Dialog reappears after clicking Allow; or a LaunchAgent / uv run job prompts every few minutes | references/uv-fda-trap.md (identify the requester; follow the automated repair route before adding a grant) |
Need the full kTCCService catalog, schema, auth_value/auth_reason semantics, tccutil | references/tcc-mechanics.md |
| Reading TCC.db gives "Permission denied" | references/tcc-mechanics.md § SIP and the FDA bootstrap |
| A granted permission silently stopped working after an update | references/tcc-mechanics.md § common failure modes (toggle off/on, or tccutil reset <Service> <bundle-id>) |
| Grant won't stick for Automation / Apple Events | references/tcc-mechanics.md — BOTH controller AND target need the grant |
Core rules (each from a real incident)
- Dialog name ≠ responsible process.
from Sub:in the TCC log is the requester; the title is the accessing binary's basename and it drifts with versions. Grant by the real path. (2026-09-19: auvFDA dialog showedpython3.11; authorizing python, changing session type, and pinning the version all failed because the requester was~/.local/bin/uv.) - Grants are keyed to the exact binary path, not identity. An unsigned executable (uv-managed python, per-version CLI, node helper) is a new app to TCC every time its path changes. This is why "worked yesterday, prompts today" after any update. Same root cause as Claude Code issues #74234 / #84948 / #86706.
- "0 hits / can't catch it" is an instrument problem, not a conclusion.
fs_usagecan emit 0 bytes on some machines; short-lived processes fall between log time windows; an empty grep file looks identical to a real zero. To pin which operation triggers a prompt, use in-processsys.addaudithookto logopenevents aligned to the tccd timestamp — notfs_usage. - SIP protects the system TCC.db read-only. You cannot
INSERT/UPDATEa grant from the command line — authorization must go through the GUI.auth_valueis readable, writable is not. - After granting, restart the requesting process. Grants are read at launch; a running process keeps its old (denied) state until relaunched.
Scope
This skill owns permission diagnosis and repair. It does not own: building an app's
permission-onboarding UX (app-development work, out of scope here), launchd job design (macos-watchdog),
or disk cleanup (macos-cleaner) — those link here when they hit a TCC wall.
