docs: document the macOS Files & Folders permission family - #470
Merged
Conversation
The troubleshooting guide covered only the seven entitlement-gated services, and said that a missing permission means tccd never prompts and agterm never appears in the matching Privacy pane. Desktop, Documents, Downloads and removable/network volumes work differently: no entitlement or usage string takes part, the grant is per app and is never inherited, and it is set under Files & Folders or Full Disk Access. A user whose listing fails in ~/Downloads read the existing section and had reason to think he was in the unfixable class. Also names the diagnostic that separates the two causes: /bin/ls -la answers a privacy denial with "Operation not permitted" and ordinary permission bits with "Permission denied", while some ls replacements print the same wording for both. Related to #468
macOS does define a usage-description string per protected folder; agterm simply ships none, so the prompt falls back to Apple's generic wording. Saying no string takes part reads as "nothing here is agterm's to change", which is wrong in the one respect that is: WezTerm ships two of these keys and names the terminal in its prompt. The diagnostic also had no operand. A privacy denial blocks reading the protected directory itself, not its entry in the parent, so a bare `/bin/ls -la` run from home lists Downloads normally and tells the reader nothing.
"The grant is never inherited" contradicted the paragraph below it, which says Full Disk Access gives every program in a session the same reach. Both were reaching for one fact: the answer is recorded against the application macOS holds responsible, so kitty's grant is not agterm's while every command inside agterm rides on agterm's. Two other statements were wider than the evidence. The absence of an entitlement gate means a missing entitlement cannot suppress this family's prompt, not that agterm's signature plays no part at all: TCC still names the client and persists the decision by the responsible app's signed identity. And errno is a strong clue rather than an oracle, since other policies can also answer EPERM, so /bin/ls "usually" tells the two apart.
Investigating #468 established the strings are not what gates folder access, so they fix nothing and were left out of the docs change. What remains is that the user is asked why agterm wants his Downloads and told nothing, which is worth keeping a note of even though it is not worth a signed-bundle change on its own.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
documents the macOS Files & Folders permission family, which the troubleshooting guide did not cover at all.
docs/troubleshooting.mdexplains the seven entitlement-gated services and says that when a permission is missingtccdnever prompts, records nothing, and agterm never appears in the matching Privacy pane. Desktop, Documents, Downloads and removable/network volumes are a different mechanism: agterm is not sandboxed and no missing entitlement can suppress that prompt, the answer is recorded against the app macOS holds responsible, and the switches live under Files & Folders or Full Disk Access. A user whosels ~/Downloadsfails read the existing section and had reason to conclude he was in the unfixable class, which is what #468 looks like.New section plus a cross-linking bullet in "Other common issues", and the same case in the bundled skill copy at
plugins/agterm/skills/agterm/troubleshooting.mdso an agent asked about it does not file an issue. It also names the diagnostic:/bin/ls -la ~/Downloadsagainst the folder itself usually reads asOperation not permittedfor a privacy denial andPermission deniedfor ordinary permission bits, whileezaprints the same wording for both, which is why the report in #468 does not settle which one it is.The last commit adds a backlog note rather than code. agterm ships none of the five optional per-folder usage strings, so macOS falls back to its own request copy, measured in
TCC.framework/Versions/A/Resources/Localizable.loctable. The strings are not a gate - agterm obtains these grants without them - so adding them repairs nothing and was deliberately left out.Related to #468