allowedTools Allowed It
So Why Does the Agent Get permission denied

We configured an AI agent to read a shared knowledge folder. We set Read(<path>/**) in allowedTools, done. On the actual run, the agent reported it couldn't read the files, permission denied, even in a mode that never prompts. The confusing part: Glob on the same path found the files and returned their names fine, but Read and Grep on that same path were both denied. The tool was allowed, the files were really there, so why still no read?

Part 1allowedTools and --add-dir are separate layers

The trap is reading allowedTools as "file access." It isn't. Allowing a tool isn't accessing a file, and you have to clear both:

• allowedTools is the list of tools that run without a permission prompt. The docs put it as "tools that execute without prompting for permission." It answers only whether the agent may call Read, Grep, or Bash, and against which path patterns.
• --add-dir is the filesystem scope. The docs describe it as "add additional working directories for Claude to read and edit files," and note that it "grants file access." It says which folders the agent can see beyond cwd.

Claude Code keeps file reads scoped around cwd by default. A file outside cwd, even with a matching pattern in allowedTools, still needs its folder added with --add-dir first before Read passes. Miss either one and it fails. The permission side unlocks "you may call this tool"; --add-dir unlocks "you may touch files there." Two different questions.

Part 2The tell: Glob finds it, Read is denied

What ate the debug time is that Glob and Read aren't gated the same way. Glob only enumerates filenames, so it returns paths as usual, but opening the contents of a file outside the filesystem scope is denied. Seeing Glob hand back a path, you assume access already works, when you can't read a single byte yet.

The symptom sends you to the wrong place. You blame a mistyped path, then a malformed allowedTools pattern, cycling between the two because that's where instinct points, while the real cause is on the other side: the folder isn't in the sandbox. Keep this pair as the bug's signature: if Glob finds a file but Read and Grep on the same path are denied in dontAsk mode, suspect --add-dir first, before you touch a single pattern.

Part 3The fix: pair allow with add-dir, and keep it narrow

The fix is to line up both places: set Read(<dir>/**) in allowedTools and pass --add-dir <dir>. Once the two agree, Read passes. To make the directory stick across sessions, the docs suggest setting permissions.additionalDirectories in a settings file instead of typing the flag each run.

What makes this a real guardrail, not just a workaround, is keeping it narrow. Only --add-dir the folders the agent genuinely should see, such as the shareable knowledge. Private data and secrets never get added to the sandbox, so they stay unreadable by default. You get least privilege for free, because both have to agree anyway: a folder you didn't add is a folder the agent can't reach, with no extra deny rule to maintain.

Part 4The lesson: allowed is not the same as reachable

The lesson that generalizes past the flags: don't trust that written config equals real behavior. The word "allow" in a settings file is only half the equation. The other half is the actual filesystem scope the agent can see. The two are set separately, and they fail quietly when they disagree.

The reliable move is to confirm at runtime, not on paper. Have the agent Read one real file that should work, and watch it pass. Then have it Read a file in a private folder that should be off-limits, and watch it get denied. That's a positive and a negative control together. Config that looks right on paper and an agent that can actually reach the files are two different claims until you see both run.

Three lines to remember:

1. allowedTools = which tools run without prompting · --add-dir = which folders are visible. You need both before Read passes.
2. The symptom that means this case: Glob finds the file, but Read and Grep are denied in dontAsk mode. Suspect --add-dir first.
3. When an agent reads outside cwd, always pair --add-dir with allowedTools, add only what's needed, then probe both the readable and the denied side.