Atlas pauses for an external_directory permission prompt because assertExternalDirectoryEffect checks containsPath against the instance context and anything outside it triggers ctx.ask with the permission external_directory and a glob pattern for the parent directory, so the fix is to approve the prompt once, approve with `always` to persist the directory glob, or add an allow rule for external_directory scoped to that directory in your config. Rejecting the prompt fails the tool call, which is the intended outcome. Before you approve anything, check the path: a stray absolute path that should have been inside the project is the usual cause, and the real fix there is to correct the path rather than widen the permission.
Why does Atlas ask for permission on a path outside the project
Atlas asks because assertExternalDirectoryEffect checks containsPath against the instance context, and any path outside it triggers ctx.ask with the permission external_directory. Leaving the workspace is always an explicit decision, so all 6 path tools, read, edit, glob, grep, lsp, and apply_patch, pause at the boundary.
The prompt is a workspace boundary, not a failure. Atlas resolves the target path, compares it against the instance context with containsPath, and when the path falls outside, it stops and asks you rather than quietly reaching into your home directory, a sibling repository, or the system. The prompt carries a glob pattern for the parent directory, which is what lets a single approval cover a whole directory instead of one file at a time. Six tools sit behind the same check: read, edit, glob, grep, lsp, and apply_patch. Rejecting the prompt fails the tool call, which is the correct behavior when the access was not intended in the first place.
How to approve an Atlas external_directory prompt once or forever
An Atlas external_directory prompt has 2 approval forms. Approve once and the single tool call proceeds. Approve with `always` and Atlas persists the glob pattern for the parent directory, so later calls under that directory stop pausing. Both routes are decisions you make explicitly, on purpose.
Pick the form that matches how often you actually need the access. A one-time approval is right for a single look at a file outside the workspace, such as reading a config from another checkout. Approving with `always` is right when you are working across two directories for a whole session and do not want to answer the same question repeatedly. The persisted unit is the directory glob that Atlas showed you in the prompt, not the individual file, so understand the scope you are granting before you choose `always`. The honest caveat: an `always` approval means Atlas can reach that entire directory tree without asking again, so read the glob in the prompt before you accept it.
How to add an external_directory allow rule in the Atlas config
Add an allow rule for external_directory scoped to 1 specific directory in your Atlas config when the access is permanent and part of how you work. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, so the rule stops the prompt at the source.
A config rule is the durable, reviewable version of an `always` approval, and it has one real advantage: it lives in a file you can read, diff, and reason about later, rather than in an approval you clicked through weeks ago. Scope the rule to the directory you actually need. An external_directory allow with a broad pattern gives Atlas standing access to everything under it, and unlike the interactive prompt, a config rule never surfaces the glob to you again for a second look. Keep the pattern tight, name the directory explicitly, and re-check the rule whenever the surrounding project layout changes.
When the external_directory prompt means your path is wrong
An unexpected Atlas external_directory prompt is often a bug report about the path, not a permissions problem, and 1 stray absolute path is the usual cause. If the file was supposed to live inside the project, fix the path rather than approving access to a directory you never meant to touch.
Treat the prompt as a free correctness check. Atlas is telling you, before anything runs, that the target of this read, edit, glob, grep, lsp, or apply_patch call is not inside the workspace. When you expected the file to be inside the project, that mismatch is the actual finding. Common shapes include an absolute path pasted from another machine, a path built from the wrong root, or a relative path that resolved against something other than the instance context. Approving such a prompt hides a real defect and lets the tool operate on the wrong file. Correct the path first, re-run, and the prompt should not appear at all.
Why the external_directory prompt appears on Windows paths
On Windows, Atlas normalizes the path with FSUtil.normalizePath before the containment check runs, so the choice between the 2 separators, backslash and forward slash, is never the reason an external_directory prompt appeared. If Atlas prompts on Windows, the normalized path genuinely resolved outside the instance context.
Windows developers reasonably suspect separator handling when a path they believe is inside the project triggers the prompt. Rule that out immediately: FSUtil.normalizePath runs first, and containsPath compares the normalized path against the instance context. A prompt therefore means the path really is outside the workspace once normalized, and the next thing to check is the root the path was built from, not its slashes. Drive letters, paths pointing at another checkout, and paths anchored somewhere above the project root are the realistic candidates. The remedy is the same as everywhere else: correct the path if the target should have been internal, or approve deliberately if the external access is genuinely what you want.
How to verify the external_directory fix worked
Verify the fix by re-running the exact tool call that paused. With a correct external_directory allow rule or a persisted `always` approval, Atlas runs the call without pausing across all 6 path tools: read, edit, glob, grep, lsp, and apply_patch. A repeat prompt means the glob does not cover your path.
The signals are easy to read. No prompt and normal tool output means the permission now resolves to allow for that directory. Another prompt means the scope you granted is narrower than the path you are hitting, so compare the glob pattern Atlas is showing you against the actual target path, and widen the rule to the correct parent directory if the access is intended. If you fixed a stray absolute path instead of granting permission, the confirmation is different and better: the call runs with no prompt at all, because the target now falls inside the instance context and assertExternalDirectoryEffect never reaches ctx.ask.
How to fix it
- 01Look at the path in the prompt first. If the path should have been inside the project, fix the path instead of approving; a stray absolute path is the usual cause.
- 02Approve the prompt once if the access is legitimate and one-off.
- 03Approve with `always` to persist the directory glob, so Atlas stops asking for that directory on future calls.
- 04Or add an allow rule for external_directory scoped to that directory in your Atlas config, which is the durable, reviewable version of the same decision.
- 05On Windows, note the path is normalized with FSUtil.normalizePath before the containment check, so separator style is not the reason the prompt appeared.
- 06Re-run the tool call and confirm the read, edit, glob, grep, lsp, or apply_patch proceeds without pausing.
Frequently asked questions
- why does Atlas ask permission to read a file outside my project
- Atlas checks containsPath against the instance context in assertExternalDirectoryEffect. Any path outside that context triggers ctx.ask with the permission external_directory and a glob for the parent directory, so leaving the workspace is always an explicit decision.
- how do I stop Atlas from asking about external directories
- Approve the prompt with `always` to persist the directory glob, or add an allow rule for external_directory scoped to that directory in your Atlas config. Keep the scope tight, because both routes grant standing access to the whole directory.
- what happens if I reject the external_directory prompt in Atlas
- Rejecting the external_directory prompt fails the tool call. Nothing is read, edited, or patched. Rejection is the correct outcome when the path was not supposed to leave the project in the first place.
- which Atlas tools trigger the external_directory permission
- The read, edit, glob, grep, lsp, and apply_patch tools all pass through assertExternalDirectoryEffect, so any of them can pause for an external_directory prompt when the target path falls outside the instance context.
- why does Atlas prompt for external_directory on Windows
- On Windows, Atlas normalizes the path with FSUtil.normalizePath before the containment check, so slash style is not the cause. A prompt means the normalized path really did resolve outside the instance context, so check the root the path was built from.
- is the external_directory prompt a bug in Atlas
- No. The external_directory prompt is the workspace boundary working as designed. An unexpected prompt usually means a stray absolute path, so inspect the path in the prompt before approving anything.
- does approving with always in Atlas grant access to one file or the whole directory
- Approving with `always` persists the directory glob that Atlas shows in the prompt, not the single file. Read that glob before accepting, because the approval covers everything under the parent directory.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Self-Review Your Working Diff Before Committing with Atlas (2026 Workflow)
How to self-review your working diff before committing with Atlas in 2026: bash produces the diff, read checks each file, grep finds leftovers, session revert undoes bad edits.
Atlas for Blazor: Terminal-Native AI Coding for .razor Components in 2026
Atlas is a terminal-native AI coding agent for Blazor developers in 2026. Work across .razor components, render modes, and the C# and JS interop boundary safely.
Atlas with Gemma 3 4B Instruct: A Triage Model, Not a Builder (2026)
Gemma 3 4B Instruct in Atlas via Amazon Bedrock: $0.04 per Mtok input, $0.08 per Mtok output, a 128K context, and a 4,096 token output cap that rules out diffs.
Atlas for Ruby on Rails in 2026
Atlas is a terminal-native AI coding agent for Ruby on Rails in 2026. Run it in a Rails app with a config/application.rb and review every diff before it lands.
Atlas with Magistral 24B (Ollama): A Local Reasoning Model for the Plan Agent in 2026
Run Atlas on Magistral 24B (Ollama): Mistral's 14GB reasoning model with a 39K context, free self-hosted. Use it as the plan agent, then hand edits to a coder.
Atlas for Perl: A Terminal-Native AI Coding Agent for CPAN Distributions in 2026
Atlas is a terminal-native AI coding agent for Perl in 2026. It reads cpanfile deps and @EXPORT lists, writes Test2::V0 cases, runs prove -lr t/, and runs perltidy on the diff.
Atlas with Liquid AI LFM2-24B-A2B in 2026
Liquid AI LFM2-24B-A2B in Atlas, 2026: a liquid neural network MoE at $0.03/$0.12 per Mtok on Together AI, with a 32,768 token context and matching output.
Atlas with Mixtral 8x7B: Running the Original Sparse MoE in 2026
Mixtral 8x7B put sparse mixture-of-experts on the map in December 2023. In Atlas it gives 32,000 tokens at $0.70 / 1M input tokens. Setup, limits, and honest fit.