Lesson 17 — The Bash Tool

The snapshot script sources the user's config file with < /dev/null (so no TTY-dependent prompts fire), then appends:

1. Unalias everything — unalias -a 2>/dev/null || true — avoids alias "freeze" inside function definitions.
2. User functions — typeset -f (zsh) or declare -F | base64-encode each function (bash). Completion functions starting with a single underscore are filtered out; double-underscore helpers (mise, pyenv) are kept.
3. Shell options — setopt lines (zsh) or shopt -p + set -o on | awk lines (bash). Then forcibly enables expand_aliases.
4. Aliases — alias -- form, stripping winpty aliases on Windows.
5. rg shim — if system rg is absent, injects a shell function backed by Bun's embedded ripgrep using the ARGV0 dispatch trick.
6. find / grep shims — in ant-native builds, always shadows system find/grep with embedded bfs/ugrep.
7. PATH export — export PATH=... from process.env.PATH.

// utils/bash/ShellSnapshot.ts — snapshot creation (simplified)
export const createAndSaveSnapshot = async (binShell: string) => {
  const configFile = getConfigFile(binShell)       // .zshrc / .bashrc / .profile
  const configFileExists = await pathExists(configFile)

  const snapshotPath = join(
    getClaudeConfigHomeDir(), 'shell-snapshots',
    `snapshot-${shellType}-${Date.now()}-${randomId}.sh`
  )

  const script = await getSnapshotScript(binShell, snapshotPath, configFileExists)
  execFile(binShell, ['-i', '-c', script], { timeout: 10000 })
  return snapshotPath
}

The promise is wrapped in .catch() and resolves to undefined. In buildExecCommand, if snapshotFilePath is undefined, the command is spawned with -l (login shell flag) so it still initialises from the user's profile. The session degrades gracefully — no aliases or custom functions, but commands still execute.

There is also a TOCTOU-aware re-check: before each command, access(snapshotFilePath) verifies the file still exists. If the OS cleaned up /tmp mid-session, lastSnapshotFilePath is cleared and the login-shell fallback is re-engaged.

eval quoting: The snapshot is sourced in the same shell invocation as the user command. Bash parses the entire line before executing, so aliases from the snapshot aren't yet available at parse time — they only become available after source snapshot runs. Using eval 'command' creates a second parse pass where the snapshot aliases are now live. The function singleQuoteForEval() wraps the command in single quotes, escaping internal single quotes as '"'"' (not \', which would break jq/awk filters containing !=).

Pipe rearrangement: Without special handling, eval 'rg foo | wc -l' < /dev/null causes wc to read from /dev/null (outputting 0) while rg waits forever on the inherited stdin pipe. The fix: inject < /dev/null between the first command and the pipe, so only the first command gets the null stdin. The parser handles this in rearrangePipeCommand().

// Before: wc reads /dev/null, rg blocks
eval 'rg foo | wc -l' < /dev/null

// After: rg reads /dev/null, wc reads rg's output
eval 'rg foo' < /dev/null | wc -l

The pipe rearrangement bails (falls back to whole-command quoting) for:

• Commands with backticks or $() — shell-quote mis-parses them
• Commands with shell variables ($VAR) — shell-quote drops them
• Control structures (for/while/if/case) — can't find pipe boundary
• Shell-quote single-quote bug pattern ('\' payload '\')
• Commands with bare newlines — shell-quote treats as whitespace

After sourcing the snapshot (which may re-enable extglob from user settings), the provider injects a command to disable extended glob patterns:

// bash
shopt -u extglob 2>/dev/null || true

// zsh
setopt NO_EXTENDED_GLOB 2>/dev/null || true

// When CLAUDE_CODE_SHELL_PREFIX is set (shell may differ)
{ shopt -u extglob || setopt NO_EXTENDED_GLOB; } >/dev/null 2>&1 || true

Extended globs (!(pattern), @(a|b), etc.) can be triggered by filenames created after our security validation completes. A file named !(safe_file) in the working directory could match and expand into a glob that hits arbitrary paths. Disabling extglob post-snapshot prevents this class of post-validation expansion attack.

Before the main validator chain, there is a special early-allow path for the pattern cmd $(cat <<'DELIM'\n...\nDELIM\n). This is the canonical way to pass multi-line content as a commit message or script argument without triggering the command-substitution validator.

The isSafeHeredoc() function uses line-based matching, not regex, to find the closing delimiter — exactly replicating bash's own heredoc-closing behavior. Key safety conditions:

1. The delimiter must be single-quoted (<<'EOF') or backslash-escaped (<<\EOF) so the body is literal text with no expansion.
2. The closing delimiter must be on a line by itself.
3. The substitution must appear in argument position, not command-name position (there must be a non-whitespace prefix before the $().
4. The text remaining after stripping the heredoc must contain only safe characters (no shell metacharacters).
5. Nested heredoc matches are rejected — they indicate the outer heredoc's literal body contains what looks like another heredoc, which our regex can't safely distinguish.

// Safe — ALLOWED:
git commit -m "$(cat <<'EOF'
Fix the login bug

Resolves #1234
EOF
)"

// Unsafe — BLOCKED (substitution in command-name position):
$(cat <<'EOF'
chmod
EOF
) 777 /etc/shadow

Each validator receives a ValidationContext with five pre-computed views of the command:

type ValidationContext = {
  originalCommand:        string  // verbatim from Claude
  baseCommand:            string  // first token after env vars
  unquotedContent:        string  // double-quotes stripped
  fullyUnquotedContent:   string  // both quote types stripped
  fullyUnquotedPreStrip:  string  // before safe-redirection stripping
  unquotedKeepQuoteChars: string  // strips content but keeps quote delimiters
  treeSitter?:            TreeSitterAnalysis | null  // AST, if available
}

unquotedKeepQuoteChars is specifically used by validateMidWordHash: it strips the content of quoted strings but keeps the quote characters themselves. This reveals patterns like 'x'# where x is inside single quotes and # is quote-adjacent — a situation where naive stripping would hide the # entirely.

A rule like Bash(npm run:*) should match NODE_ENV=production npm run build. To enable this, stripSafeWrappers() performs two-phase stripping before comparing against rules:

Phase 1: Strip leading env vars where the variable name is in SAFE_ENV_VARS. The allowlist covers build/locale/display vars that cannot execute code. Variables like PATH, LD_PRELOAD, PYTHONPATH are deliberately NOT in the list.

Phase 2: Strip wrapper commands: timeout (with full GNU flag parsing), time, nice (all invocation forms), nohup. Each uses a regex with an allowlisted character class for flag values — the old [^ \t]+ pattern was bypassed by timeout -k$(id) 10 ls where $(id) matched as a duration value and got stripped.

Both phases run in a fixed-point loop (repeat until stable), handling interleaved patterns like timeout 300 NODE_ENV=prod npm run build.

// SECURITY NOTE: Phase 2 does NOT strip env vars.
// After a wrapper, VAR=val is treated as the command to execute.
// `timeout 10 MY_CMD=foo` — MY_CMD=foo is the command name, not an env assignment.
// Stripping it here would create a false permission match.

Permission rules stored in settings use the format Bash(content). The content has three match modes:

The getSimpleCommandPrefix() function also auto-generates 2-word prefix rules when the user approves a command. For git commit -m "fix typo", the suggestion is Bash(git commit:*), not the literal command (which would never match again). For heredoc commands, the prefix is extracted before the << operator.

Bare shell names (bash, sh, zsh, python, env, sudo, etc.) are excluded from prefix suggestions entirely — Bash(bash:*) would be equivalent to Bash(*) and approve arbitrary code execution.

containsExcludedCommand() splits compound commands and checks each subcommand. Additionally, for each subcommand it generates a fixed-point closure of stripped forms (env vars stripped, wrappers stripped) and checks all variants against the pattern. This handles FOO=bar bazel run //... matching a bazel:* excluded pattern.

The fixed-point approach matches the stripping logic used in permission rule checking — if a pattern would match at permission-check time, it also matches at sandbox-exclusion time. Consistency prevents the situation where a command escapes the sandbox via an excluded pattern that the permission check would never match.

When the Monitor tool feature is enabled, standalone sleep N (where N ≥ 2) as the first subcommand is blocked by validateInput() before any permission check. The error message explains why and what to use instead:

function detectBlockedSleepPattern(command: string): string | null {
  const m = /^sleep\s+(\d+)\s*$/.exec(first)
  if (!m) return null
  const secs = parseInt(m[1]!, 10)
  if (secs < 2) return null  // sub-2s sleeps are fine (rate limiting, pacing)

  const rest = parts.slice(1).join(' ').trim()
  return rest
    ? `sleep ${secs} followed by: ${rest}`    // suggest Monitor
    : `standalone sleep ${secs}`               // "what are you waiting for?"
}

Float-duration sleeps (sleep 0.5) are exempt — they represent legitimate rate-limiting or deliberate pacing, not polling loops. The pattern only fires on integer durations.