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

Structs

ApprovalMiss

A program the command runs that the allowlist does not name.

ApprovalRequest

What a user is asked to approve for one command.

PartialRun

The statements that may run, and one note per skipped statement.

Enums

Separator

The operator that ends a command segment.

ShellSecurity

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

Constants

LEAN_CTX_RUN_CONTROL_ENV

The LEAN_CTX_* variables a command line may set: they only switch compression or the hook re-entry guard for that one command. lean-ctx -c applies these from the command text (#1321) and no others. Every other LEAN_CTX_* variable — the shell security mode, the allowlist, the config and data directories, the path jail — is lean-ctx’s own policy, which a command line must not set for the lean-ctx it starts.

MAX_VALIDATED_COMMAND_BYTES

Longest command the gate validates; a longer one is refused in enforce mode. Every check re-scans the line, and a hook that runs out of time fails open.

Functions

allow_execute_languages

Adds languages to the global execute_allowed_languages: the “always allow” answer to a ctx_execute approval prompt.

allow_programs

Adds programs to the global shell_allowlist_extra, as lean-ctx allow does, without printing. Returns the entries that were new. Used when the user answers an approval prompt with “always allow”.

approval_request

The approval command needs, or None when it needs none (it passes) or cannot get one (a hard block, or a shell security mode other than enforce, where nothing is refused for a missing program).

check_leanctx_invocation

The checks for a single, plain lean-ctx … invocation from a host shell, honouring the active ShellSecurity mode like check_shell_allowlist.

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:

check_shell_allowlist_granted

super::check_shell_allowlist with granted programs counted as listed. An empty grant is exactly the ordinary check.

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.

exceeds_validation_limits

True when command is beyond what the gate validates: longer than MAX_VALIDATED_COMMAND_BYTES or nested deeper than the lexer follows. The shell hooks deny such a command (in enforce mode) instead of handing it on.

extract_all_commands_pub

Public accessor for extracting all command segments.

extract_base_command

heredoc_delims

The delimiters of the heredoc operators in line, in source order (only quoted ones with quoted_only). A << inside quotes, ${…} or arithmetic is no operator; a <<< here-string has no body.

invalid_allowlist_entries_pub

Public accessor: entries the effective allowlist silently dropped for invalid * placement (§4 of the design doc). Used by lean-ctx doctor to surface a count, and by --fix to know which raw config lines to comment out.

is_valid_allowlist_entry

§4 of the design doc: an entry’s only valid * placement is a single trailing token. Bare *, an embedded *, or more than one * are invalid.

narrowed_allowlist_entries_pub

Public accessor: multi-word entries with no trailing * — their meaning changed under subcommand scoping (now exact-match only, previously “whole binary”). Used by the lean-ctx doctor upgrade advisory (§2 of the design doc). Always empty when shell_allowlist_subcommand_scoping = false, since those entries’ meaning didn’t change under the compat path.

partial_run

Plans a partial run for command, which the gate refused as a whole. None keeps the whole-call rejection.

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.

read_heredoc_delim

Parse a heredoc delimiter token starting at start, returning its bare name (quotes/escapes removed), whether any part was quoted, and the index just past the token. None when no delimiter is present.

refuse_redaction_marker

Refuses code that contains a redaction marker such as [REDACTED:Database credentials]. Redaction applies only to what an agent is shown, never to what runs; an agent that copies a marker out of a redacted view into a command would write the marker itself into files or remote configs (a crash-looping server on 24.10.). No command means one, so it never runs, whatever the shell security mode.

segments_with_separators

Every segment together with the separator that ends it; the last segment has none. Same scanner as split_on_operators, so the two never disagree about where a command ends.

shadowed_allowlist_entries_pub

All shadowed entries in entries, paired with the entry that covers each one — used by the lean-ctx doctor advisory (§2).

shadowing_entry

§2 “Shadowing warnings”: is a made useless by a different entry already in entries? Entry A is shadowed by B when B matches every command A matches: B is a single word equal to A’s first word, or B ends in * and B’s words before the * are a leading run of A’s words (ignoring A’s own trailing *). Returns the first covering entry, in list order. Shared by lean-ctx allow (write-time warning) and lean-ctx doctor (read-only advisory) so the rule can’t drift between the two.

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).

warn_only_reason

The reason of an enforce-mode block message, without the wording that only holds when the command was actually stopped (#1874).

with_run_cwd

Runs f with relative paths resolved against cwd, the directory the checked command runs in, instead of this process’s own.