ShellTool

Tool for executing shell commands under a strict allowlist.

IMPORTANT: This tool requires an explicit allowlist of commands for safety. It will not execute any command whose first token is not in the allowlist.

== Execution model ==

Commands are tokenized with shell-style quoting (see CommandTokenizer) and executed directly via ProcessBuilder '''without invoking a shell'''. As a consequence:

• No glob expansion (*, ?, [abc] are passed literally to the program).
• No variable substitution ($VAR, ${VAR}, $(...), backticks).
• No command chaining or redirection (&&, ;, |, <, >, &).
• Quoted arguments are honoured: echo "hello world" runs echo with one argument hello world, not two.

Combined with the allowlist, this means LLM-supplied input that contains shell metacharacters cannot escape into a shell — characters such as && survive tokenization as literal argument bytes and are handed to the allowlisted program, which generally treats them as harmless input.

== Environment and files ==

A command receives a scrubbed environment (see ShellConfig): only the variables named in inheritedEnvironment, plus environment. The files a command names are not checked unless ShellConfig.pathPolicy is set; then every file-like argument must pass that FileConfig's isPathAllowed: the file tools' allowed and blocked entries and real-location rule, with the argument judged as the program will hand it to the OS, .. and all. A .. after a link is read both ways: physically, as POSIX applies it (the link target's parent), and lexically, as Windows applies it (the directory holding the link), and both locations must be allowed. The file tools, which open the path themselves, remove .. as text first. A value attached to a flag is checked as a path too: the value after = of a long option (--file=x), and every tail of a short-option cluster (-fx, -ifx), within a budget of file-system lookups for the whole command. A value that is one plain path component costs one lookup - whether anything is there - and is resolved in full only when something is; this gives the full check's verdict exactly, with no assumption about name lengths. file -C, -m, -M and -f, date -f and -r, wc --files0-from, and sort -o, --output, -T, --temporary-directory, --compress-program and --files0-from (which write a file, run a program or read one the command does not name) are refused whatever the policy: anywhere in a short-option cluster, attached value or not, under any abbreviation of the long form, with or without =value, wherever they appear, -- or not before them, and however the program is spelled (/usr/bin/file, FILE, file.exe).

On Windows, with or without a path policy, an argument, the working directory and an environment value are refused when they hold a character a program reading its command line in an ANSI code page may receive as a different ASCII character ("best fit": ..／..／secret as ../../secret, -ｏ as -o; see WindowsBestFit, #1766). On a double-byte ANSI host (code pages 932, 936, 950) an argument the JDK puts in quotes is also refused when it holds a character whose second byte is 0x5C, the byte of \ (a 表, #1807).

== Features ==

• Command allowlist for security
• Configurable working directory
• Optional path policy for file arguments
• Scrubbed environment
• Timeout support
• Output size limits