Root isolation

The effective workspace.roots list comes from environment overrides, project and global TOML, or the selected MCP workspace roots. When no source configures roots, the selected project root is the only boundary.

Resolution rules

• Server-side top-level paths rules are authoritative; client-advertised MCP roots provide only a host baseline.
• Exact files outrank directories, then the deepest directory/include literal prefix wins. Equal specificity resolves deny, then request, then allow.
• Exclusions override includes inside a rule, and delete inherits write when omitted.
• Project rules that broaden the host baseline are reduced from allow to request; persistent grants belong only in user-level configuration.
• Version 2 never grants OS temporary-directory access implicitly. Add a narrow rule when a workflow requires it.
• Reads, hashes, and intelligence calls require read; writes and metadata changes require write; deletion requires delete; rename requires source delete and destination write.
• A symbolic link and its resolved target must both be authorized, and the winning rule must enable symlink traversal.
• Active global and project configuration files are protected targets: model-initiated mutation always requires approval.
• Version 1 safety booleans remain readable with deprecation diagnostics and can be translated with ast-mcp config migrate.

One canonical policy engine serves file tools, AST intelligence, hooks, previews, and migration validation. Mutation batches are completely preflighted before the first side effect, so one denied or unapproved target rejects the entire batch.

Multiple workspaces

When a client advertises multiple roots, an absolute request path selects the containing root; pathless and relative requests use the first root. Calls spanning roots fail if their effective safety, formatting, or dependency policies conflict. This prevents one project from silently weakening another project's write policy.

Prefer one repository root per server when possible. Multiple roots remain available for deliberate multi-repository work, but they increase the filesystem state exposed to the connected agent.

Linked git worktrees

Hosts typically start a project-local MCP server against the primary checkout. Linked git worktrees of that repository sit outside a literal workspace.roots = ["."] path, so ast-mcp discovers them from .git without invoking git on the hot path.

[workspace] worktrees selects how those trees participate:

• include (default): linked worktrees join the filesystem baseline and trusted roots. Relative [[paths]] anchors such as path = "." remap onto each worktree.
• request: the same remapping applies, but paths inside a sibling worktree require approval unless an explicit rule already denies them.
• ignore: sibling worktrees stay outside the baseline unless an absolute [[paths]] rule covers them.

projectRoot remains the config-bearing checkout. Intelligence calls that target an absolute worktree path use that worktree as the ast-bro root. Relative paths resolve against PWD when it is a linked worktree.