Module pathjail_scope 

Path-jail scope: which directories the jail treats as the user’s own code.

The jail used to admit only the session’s project root (plus allow-lists). Anyone working on several repositories at once hit “path escapes project root” on every cross-project read, and the suggested fixes — one allow entry per directory, or env vars that need an MCP restart — did not scale.

• projects (default; also the default of 3.11.1 and 3.11.2): only paths inside a project below ~ (a directory between it and ~ holds .git, Cargo.toml, …) are admitted, for reading; loose personal files are not, and writes stay in the session’s project, host-declared roots and allow entries — an agent working in repo A cannot plant ~/code/B/.git/hooks/pre-commit.
• home (opt-in; the default of 3.11.3 to 3.12.0): everything below the user’s home directory is admitted for reading and writing, except the protected zones where credentials and other programs’ private state live (every top-level dot entry such as ~/.ssh, ~/.aws, ~/.config, ~/.zshrc or other agents’ ~/.claude, plus ~/Library on macOS, ~/AppData and the NTUSER.DAT* registry hive on Windows). Paths outside the home directory stay jailed. It admits writes wherever it admits reads, so it is reported as a jail relaxation.
• project: the classic boundary — the project root plus allow-lists.

Explicit allow-lists (allow_paths, extra_roots, read_only_roots) and lean-ctx’s own state dir still widen every scope, so lean-ctx allow-path ~/.config/foo reopens one protected directory without dropping the zone. path_jail = false keeps disabling the jail entirely.

Resolution precedence (first hit wins): LEAN_CTX_PATH_JAIL_SCOPE env → path_jail_scope in the global config.toml → projects. Like path_jail it is global-only: a project-local .lean-ctx.toml is never merged for it.

Enums

PathJailScope

Functions

maybe_show_default_notice

Tells a user once that the default scope narrowed to projects, on the first interactive command. Never for MCP, hooks or piped use, and never when the user chose a scope or turned the jail off: an explicit choice is kept.

with_request_write_roots

Runs one tool call with its project and host-declared roots writable.