Practical agent workflows · · 16 min read
Agent permission denied on macOS: find the actual boundary
A focused file-access investigation: identify the path, process, owner, system permission and provider policy before changing access.
An agent reports permission denied while the same file opens normally in Finder. The obvious explanation is that the agent needs more access. That explanation is incomplete. The file may belong to a different user, the operation may target another checkout, macOS privacy controls may govern the responsible application, or the coding provider may have refused the tool before the operating system tried to read anything. Each explanation calls for different evidence.
This guide uses a harmless fixture in a dedicated test folder to separate those layers. GrantTap can expose supported provider decisions and computer controls, but a phone approval does not automatically grant a macOS privacy permission or alter filesystem ownership. The examples are a diagnostic method, not a report of changes made to your Mac. Begin with the exact operation, the computer performing it and the smallest path that reproduces the problem. That gives you a useful result without widening access to unrelated files or changing every permission in a project.
Try a focused check
Use a dedicated test Task and the intended authorized working directory.
Observe without modifying permissions
Run these read-only commands in the affected working directory. Review path names locally before sharing output.
pwd -P id ls -ld .Name the failing operation
Distinguish reading, creating, replacing and deleting. A successful read does not prove a write is permitted.
Verify the same process
Retest the narrow harmless operation from the agent process, then confirm that unrelated folders remain outside the intended scope.
Identify which component actually refused the action
Keep the original error and the name of the operation that produced it. A provider policy refusal, an operating-system file error and an external service's HTTP authorization error are different outcomes. If a tool was refused before execution, changing a folder's ownership is unlikely to help. If a process cannot read a local file, signing into an unrelated model account is not the relevant first experiment. Start by locating the boundary that generated the refusal, even when the mobile interface displays a short summary rather than the complete native error.
For the practice case, ask the agent to read one clearly named fixture and report whether it could obtain its known marker. Use a file that contains no secrets and no customer information. Preserve the route to the intended computer and the native execution identity. This check is more informative than asking the agent to scan an entire home directory, because a broad scan can encounter several independent restrictions and produce a confusing mixture of success and failure. One recognizable file makes a changed outcome easy to verify.
Write down the expected result before changing settings: the selected execution can read that fixture through its normal supported tool, while unrelated protected locations keep their existing rules. This is a narrow acceptance criterion. It does not demand that every process on the Mac acquire the same access. A diagnosis that ends with the intended read working under a known identity is useful. A diagnosis that merely makes an error disappear after several global changes leaves the cause and the new access boundary uncertain.
Prove the path before examining permissions
Check the working directory reported by the actual execution. In a normal shell, pwd identifies the current directory, and pwd -P can help expose the physical directory when the shell's logical path includes a symbolic link. Do not assume the path displayed by a project card is the path used by every child process. A provider started from a parent folder may later operate on a repository below it. Conversely, a second checkout can have the same repository name while containing different files and a different set of local changes.
Compare the requested file with the file you opened in Finder. Name, relative path, parent folder and a small non-sensitive marker are usually sufficient for the exercise. A similarly named file in another worktree is not evidence that the intended file is readable. If a cloud-backed folder exposes an unavailable placeholder, confirm that the required content is locally available before treating the situation as an ordinary permission problem. The useful distinction is between absent data, the wrong location and a genuine refusal to access existing local content.
When a path resolves outside the expected folder, stop interpreting tests against the original display name. Follow the actual target and examine its boundary separately. A project directory can contain links to another location whose access rules differ. Document that relationship without copying private directory names into a public report. The same principle applies to an application container, an external volume or a network-mounted location. A permission result belongs to the resolved object and the requesting process, not merely to the friendly project label shown on the phone.
Distinguish the account and process that execute the tool
A shell opened by you, a persistent helper and a provider launched by that helper need not inherit the same environment or application context. Establish which user account owns the process and which application is responsible for the request. The id command can identify the effective shell user in a controlled local check. A process inventory should be bounded to the relevant executable rather than a dump of every command line, because arguments can contain private paths or data. Record only the identity facts needed to explain the access boundary.
Run the fixture check from the failing execution, not only from a convenient terminal. A successful read in Terminal proves that Terminal's particular process context can read the file. It does not automatically establish access for a separate background helper or an editor-launched provider. This is why repeating the same visible command in two different places can produce different results without either observation being false. Keep both observations and their process identities. Their difference is the clue that lets you decide which configuration deserves attention.
Avoid treating a restart as evidence of authorization. Restarting may pick up a legitimate configuration change, replace an old executable or simply alter timing. After a required restart, repeat the same fixture through the original supported route and record the new outcome. If a different process now owns execution, note that change too. The result should explain which identity succeeded, rather than imply that every future child process on the computer has inherited the same access. A process transition is an event to verify, not an access guarantee.
Inspect filesystem facts without changing them first
For an ordinary local folder, a bounded listing of the relevant file and its parent can show basic ownership and permission information. Commands such as ls -ld operate on the named directory itself rather than recursively printing its contents. On macOS, additional listing options can expose ACL or flag information when that detail is relevant. Use the options documented by the installed system and preserve only a redacted excerpt in a support report. Reading metadata first makes it possible to recognize whether a later change actually addressed a filesystem restriction.
Separate the ability to traverse a parent directory from the ability to read a file. A readable-looking file inside an inaccessible parent can still fail to open through that path. Likewise, reading a file and creating a sibling file are different operations. Choose the smallest operation required by the user's task. If the agent only needs to inspect source, a write probe adds an unrelated requirement. If the task genuinely requires an edit, perform a disposable write-and-read check inside the dedicated fixture folder before interpreting the production project's behavior.
If ownership is unexpectedly different, investigate how that copy was created before applying a recursive repair. A copied archive, a privileged build command and a mounted volume can lead to different situations. The point is to recover the intended working arrangement, not to make every path writable by every user. Preserve the original metadata and choose a targeted remedy appropriate to the confirmed cause. If you cannot explain what a proposed permission change grants, the diagnostic evidence is not yet sufficient to justify applying it across an entire repository.
Understand macOS privacy controls as another layer
macOS has privacy controls governing an application's access to protected file locations. Apple's Files and Folders guide describes the relevant System Settings route. These controls are distinct from ordinary ownership and file mode bits. A file may be readable under its filesystem metadata while the responsible application still lacks the required privacy permission. Conversely, a privacy grant does not repair a missing path or automatically make a file owned by another account writable.
Use the actual responsible application and the location involved in the failure to guide the investigation. Giving one convenient terminal application access does not prove that a separately launched helper is covered. The exact attribution of a request can depend on how the process was started, so observe the failing route rather than guessing from the executable's name alone. If the system presents a native permission request, read the application identity and requested scope there. A screenshot of another application's settings should not be substituted for that evidence.
After a targeted setting change, repeat the same harmless fixture operation through the same execution route. Keep the before-and-after result and note any required application restart. If access still fails, return to the path and process facts instead of immediately granting broader access. This sequence keeps the experiment interpretable. A successful read then demonstrates a concrete property under a known configuration. It does not imply that all protected locations are available, that write access was established or that every coding provider uses an identical application context.
Keep provider policy separate from operating-system permission
A coding client may require approval for a tool or deny an operation under its own policy even when macOS would allow the underlying file access. Project rules can introduce another explicit boundary. In GrantTap, Governance and the provider's native permission mode remain distinct concepts. A supported phone decision answers the correlated request; it is not a command to erase every other rule. When a global deny or an unsupported control remains effective, preserve that outcome and its explanation instead of interpreting it as a broken folder permission.
For a useful test, choose a permitted read of the fixture and an intentionally disallowed operation in a dedicated test context. Observe which component reports each result. Do not broaden a global policy to make a single example easier to run. If an override is part of the authorized task, scope it to that task and verify its reported application on the computer. An interface showing a desired setting is different from a confirmed effective revision. The coverage guide explains why observed, enforced and unknown must remain distinguishable.
When the provider refuses a tool before it reaches the operating system, keep that refusal as the current fact. It may be the correct outcome under the chosen rules. Ask whether the user intended that category of action to be permitted in this Task, and inspect the existing instruction before requesting anything new. A permission problem is not automatically a defect. The engineering task is to make the outcome accurate and understandable, then change only the boundary that the user actually authorized you to change.
Interpret reads, edits and process launches independently
Suppose the agent can read a source file but cannot save a formatted version beside it. That observation narrows the problem to a different operation; it does not invalidate the successful read. A save may involve creating a temporary sibling and replacing the original file, so the parent directory can matter. Reproduce the intended editing behavior on a disposable fixture rather than assuming that any successful read proves the complete workflow. Preserve a known copy of the fixture so the experiment can be repeated without affecting real source changes.
Launching an executable introduces further conditions. The process may encounter an unavailable binary, an unsupported runtime or a system launch restriction before file access relevant to the task begins. Keep that failure separate from source-file permissions. If the provider itself did not launch, the next useful check is its documented readiness and sign-in state on the selected computer. See Devices for supported GrantTap controls. Repeatedly approving a file operation on the phone cannot repair a local executable that never started the tool required to perform it.
Cloud and removable storage deserve their own small trial. Confirm the content is present on the execution computer, then test the needed operation while the location is available. A later disconnection or provider-specific file update can change the result independently of your coding-agent policy. Record that dependency in the task note. The goal is not to classify every storage system as unreliable. It is to avoid describing the state of one file at one time as a permanent access property of a folder whose backing service can change.
Repair one confirmed boundary at a time
Once the evidence identifies the cause, choose a targeted repair. That may mean selecting the correct checkout, restoring locally available fixture content, completing a native privacy request or applying an already authorized task rule. Keep the repair's scope in the note. A small verified change is easier to roll back and easier to review than a bundle of unrelated access changes. If several boundaries fail independently, address them in a named order and repeat the fixture between steps so each result remains attributable.
Broad filesystem permission changes and blanket privacy grants can hide the original distinction while creating a wider access surface. They also make a future failure harder to explain because the baseline has disappeared. This is why the fixture's narrow acceptance criterion matters: the intended execution needs the intended operation on the intended resource. The task does not usually require universal access to the entire home directory. If broader access is genuinely required for a separate workflow, document that requirement and verify it as a separate change with its own user authorization.
After applying a repair, repeat the original failed operation once and inspect its actual result. If a stale interface still shows the earlier error, distinguish that display problem from execution. If the operation now reaches a later boundary and fails differently, keep both findings. Progress through one boundary is useful evidence even when the whole workflow is not complete. Reporting the new failure accurately helps the next person continue from the correct place instead of undoing the successful repair and restarting the entire troubleshooting process.
Prepare a small support packet
A useful report includes the intended operation, the relevant computer and provider, a redacted path shape, the original error category and the smallest fixture result. Add the before-and-after observations for any targeted setting change. Exclude tokens, pairing material and unrelated file contents. A support engineer should be able to understand the boundary without gaining access to the original private project. If the issue depends on a filename or path character, reproduce that characteristic in the fixture instead of forwarding the real sensitive name.
Keep product settings and system settings identified by their owner. A screenshot of GrantTap's approval controls belongs to one layer; a macOS privacy setting belongs to another. Include the observation time when comparing them. A current native refusal is more relevant than a screenshot from before an update or restart. If the report mixes several computers, label each observation explicitly. Two screenshots of similarly named projects on different hosts can otherwise create a misleading story in which the same process appears both authorized and denied.
Make the next requested action concrete. Ask for a supported check of the responsible application or for confirmation that a particular tool was refused before execution. Avoid a general request to fix all permissions. The smaller question lets another person answer with evidence and keeps them from applying a broad change simply to demonstrate effort. If the fixture cannot reproduce the problem, preserve that finding too. It may point to a property of the original storage location, checkout or process context that the simplified example did not yet include.
Accept the repair by behavior
The final check should repeat the user's intended operation through the intended execution route. For a read-only task, the correct fixture marker is a concrete result. For an editing workflow, the disposable fixture should be saved and reopened as intended. Verify that the selected Task and computer remained the same and that unrelated permissions were not changed as part of the experiment. This acceptance test demonstrates the property you needed rather than merely confirming the presence of a checkbox in a settings window.
Document the boundary that actually changed and the limits that remain. For example, the selected helper can now read the test project in the chosen location, while a different protected folder was not part of the test. That statement is more durable than permission denied is fixed everywhere. When the process launcher, storage location or user account changes later, you can identify which assumption needs a new check. Routine code edits inside the same tested arrangement do not automatically require repeating every system-permission experiment from the beginning.
The successful outcome is a clear explanation as well as a working read or edit. You know which component produced the refusal, which identity requested access, which resource was involved and what targeted repair changed the result. GrantTap's mobile decision remains part of its supported control path, macOS privacy remains its own boundary and the filesystem retains its explicit ownership. Once those facts are separated, permission denied becomes a tractable diagnostic event rather than a reason to grant every application access to everything.