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

Reproduce the reported denial first

The executing agent repeats the named protected read through the actual failing requester and execution context before changing permissions. A file listing, another terminal, SSH access or a foreground run cannot substitute for the denied file read or background job. Record the path/resource, requester, context and result; this is a diagnostic step, not a mechanical permission classifier.

If that read now succeeds, report currently accessible; earlier cause unknown and stop permission changes unless a specific required read still fails. Do not call the cause repaired without evidence of the cause and its correction, or add Full Disk Access, change ACLs, reconnect shared mounts or restart a shared host merely to clear a historical error. If it still fails, follow the attribution checks below; Operation not permitted alone does not establish TCC as the cause.

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:

# 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: a uv FDA dialog showed python3.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_usage can 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-process sys.addaudithook to log open events aligned to the tccd timestamp — not fs_usage.
• SIP protects the system TCC.db read-only. You cannot INSERT/UPDATE a grant from the command line — authorization must go through the GUI. auth_value is 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.