Module pathjail 

Structs

JailRelaxation

A single active relaxation of the path jail. Each one widens or disables what tools can reach beyond the project root, so it is surfaced loudly (GH security audit, finding 3): the MCP/HTTP server inherits its process env from the IDE/launchd, so a globally-set LEAN_CTX_ALLOW_PATH / LEAN_CTX_EXTRA_ROOTS / LEAN_CTX_ALLOW_IDE_DIRS (or path_jail = false) silently loosens the boundary with no in-band signal otherwise.

Functions

active_relaxations

Collect every currently-active path-jail relaxation. An empty result means the jail is fully in force. This is the single source of truth shared by the startup warning (warn_if_relaxed) and lean-ctx doctor.

allow_paths_from_env_and_config

canonicalize_or_self

Heuristic canonicalize — honours the #356 TCC guard. Used by the jail-disabled bypass and by external callers (session/startup/server roots) that must not pop a privacy prompt on their own initiative.

detect_language_cache_root

If candidate sits inside a known language cache, return (label, root) where root is the path truncated at the end of the marker directory (no trailing slash). resolve_path uses this to auto-register a session read-only root so the retry resolves without a config edit or a subprocess (#899).

enforce_writable

Default-deny write guard for the read-only tier (#475): returns an error if candidate is inside a configured read-only root, Ok(()) otherwise.

expand_user_path

allow_paths / extra_roots come from config.toml, where no shell ever runs — users writing "$HOME/code" or "~/code" got a literal, never-matching prefix and concluded the whole option was broken (GH #392). Unset variables are left verbatim (and warned about) so the entry fails loudly in lean-ctx doctor instead of silently matching something else.

is_harness_auto_memory_path

True for Claude Code / CodeBuddy auto-memory files under ~/.claude/projects/<slug>/memory/ (and the CodeBuddy twin).

is_read_only_path

True when candidate resolves to a location inside a configured read-only root. The candidate’s nearest existing ancestor is canonicalized (so a not-yet-existing file inherits the read-only status of the directory it would be created in — closing the “create a new file in a read-only repo” hole) and matched against the (symlink-resolved) read-only roots.

jail_path

jail_path_with_roots

Like jail_path, but also accepts paths under any of extra_roots.

read_only_roots_from_env_and_config

A read-only root is a sibling subtree the agent may read but never write — e.g. a reference repo mounted next to the project. Empty by default, so is_read_only_path/enforce_writable are zero-cost no-ops for everyone who hasn’t opted in (#475).

register_session_read_only_root

Register a session-scoped read-only root (an auto-detected language cache). Returns true when newly added. Idempotent on the canonicalized path.

session_read_only_roots

The session-scoped read-only roots auto-registered this process (#899).

warn_if_relaxed

Emit a loud tracing::warn! for every active path-jail relaxation. Called once at MCP/HTTP server startup so a trusted-but-loosening env/config leaves an in-band audit signal instead of silently defeating the jail (finding 3).