Module shell_allowlist 

Shell allowlist with AST-based command parsing.

Security model (Information Bottleneck principle):

• When allowlist is set: ALL segments of a compound command must be allowed (deny-by-default)
• When empty: all commands pass (backwards-compatible blocklist-only mode)
• Dangerous patterns (subshells, eval, backticks) are blocked in restricted mode

Enums

ShellSecurity

Active shell-security posture. Order is least → most permissive only for readability; do not rely on ordinal values.

Functions

check_shell_allowlist

Checks whether a command may run, honouring the active ShellSecurity mode (GL #788). This is the single chokepoint shared by MCP ctx_shell and the CLI shell entrypoints, so the mode applies consistently:

effective_allowlist_pub

Public accessor: the fully-resolved allowlist actually enforced by the MCP tools (base shell_allowlist + additive shell_allowlist_extra + env), deduplicated. Empty means blocklist-only mode (all commands pass). Used by lean-ctx allow and lean-ctx doctor to show users exactly what the runtime sees.

extract_all_commands_pub

Public accessor for extracting all command segments.

extract_base_command

passes_enforced

True when command would pass the allowlist / dangerous-pattern checks in enforce semantics — independent of the active ShellSecurity mode and without any logging or blocking side effects.

shell_tokenize

Tokenize a shell command segment respecting single/double quotes and backslash escapes. Returns tokens with outer quotes stripped, matching how the shell would parse them. E.g. git -C "Program Files" status → ["git", "-C", "Program Files", "status"]

strip_all_heredoc_bodies

Like strip_quoted_heredoc_bodies but strips bodies for all heredocs (quoted and unquoted delimiters). Use for checks that must never interpret heredoc body content as commands or redirects (#931).