Class WorkspaceFunctionScope

Whether path comparisons should be case-sensitive on the current backend. Windows and macOS default to case-insensitive file systems (NTFS, HFS+, APFS); Linux is treated as case-sensitive. This is a heuristic — a case-sensitive APFS volume on macOS or a case-insensitive volume mounted on Linux will be misclassified, but querying the actual file system would require a backend round-trip.

Asserts the target URI is reachable by AI tools that honor the external allow-list. Allowed when the URI is inside any workspace root, or when it is covered by an entry of the ai-features.workspaceFunctions.allowedExternalPaths preference. Workspace-scoped overrides of that preference are dropped when the workspace is not trusted.

The target URI is normalized before the check so that literal .. segments and percent-encoded equivalents (e.g. %2e%2e) are resolved away — otherwise the path-prefix comparison would admit traversals.

Note: symlinks within allow-listed directories are NOT canonicalized before the check. Only allow-list directories whose contents you trust.

── Access control ──────────────────────────────────────────────────

Resolves the configured external allow-list to URIs. Reads via the trust-aware preference reader so workspace-scoped overrides are dropped when the workspace is untrusted. Awaits the reader's ready promise so that the trust state is resolved before the first preference read. Non-string entries, blanks, and entries that don't parse to a file:// URI are filtered out; URIs are returned in normalized form.

Returns the workspace root that contains the given URI. If nested roots exist, returns the most specific (deepest) one.

Returns a mapping of root names to root URIs.

Root names are always the directory basename. When multiple roots share the same basename, only the first (by URI sort order) is addressable by name — the others are still reachable via the resolveRelativePath supra-relative check (which examines path segments against all roots).

Known limitation: duplicate basenames are not disambiguated with synthetic suffixes because agents observe real filesystem paths in terminal output, compiler errors, stack traces, etc. Synthetic names like app-1 would conflict with those observations and cause more confusion than they solve. A future improvement could let users assign display names to roots.

Returns the root name for a given root URI based on the cached mapping.

Resolves a relative path to a URI using a deterministic, synchronous algorithm. No filesystem I/O is performed — the agent is expected to use <rootName>/<relativePath> format. If the path cannot be resolved deterministically, an error is thrown.

Resolution order:

1. Root+relative: first segment matches a root name → resolve rest relative to that root.
2. Supra-relative: a root's basename appears as a segment, and any preceding material matches the preceding path components of the root → resolve the trailing portion.
3. Single-root fallback: if exactly one workspace root, resolve relative to it.
4. Error: tell the agent how to format the path.

Converts a URI to a workspace-relative path with root name prefix. Format: /

Whether the already-separator-normalized path contains .. as a path segment (not merely as a substring of a filename like my..file.json).

Whether an already-separator-normalized path is absolute on either platform: POSIX /foo, UNC //host/share, or Windows drive C:/foo.