From 842e3607fa1f30e1f517e1939d18b03fcb62850a Mon Sep 17 00:00:00 2001
From: Ed Nutting <github@ednutting.com>
Date: Thu, 15 Jan 2026 12:44:17 +0000
Subject: [PATCH 1/5] Fix shell injection vulnerability in LocalScheduler

Replace create_subprocess_shell() with create_subprocess_exec() to prevent
arbitrary command execution through malicious job specifications. Arguments
are now passed as a list directly to exec instead of being joined into a
shell command string.

- Changed asyncio.create_subprocess_shell to create_subprocess_exec
- Remove string concatenation with " ".join()
- Updated tests to verify list-based argument passing
- Added test case to ensure special characters are handled safely

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 gator/scheduler/local.py      |   4 +-
 tests/test_local_scheduler.py | 105 ++++++++++++++++++++++++++++++++--
 2 files changed, 102 insertions(+), 7 deletions(-)

diff --git a/gator/scheduler/local.py b/gator/scheduler/local.py
index 7dfee01..ea70105 100644
--- a/gator/scheduler/local.py
+++ b/gator/scheduler/local.py
@@ -103,8 +103,8 @@ async def _inner():
                 async with self.update_lock:
                     # Launch jobs
                     self.slots[task.ident] = granted
-                    self.launched_processes[task.ident] = await asyncio.create_subprocess_shell(
-                        " ".join(self.create_command(task, {"concurrency": granted})),
+                    self.launched_processes[task.ident] = await asyncio.create_subprocess_exec(
+                        *self.create_command(task, {"concurrency": granted}),
                         stdin=asyncio.subprocess.DEVNULL,
                         stdout=asyncio.subprocess.DEVNULL,
                         stderr=asyncio.subprocess.STDOUT,
diff --git a/tests/test_local_scheduler.py b/tests/test_local_scheduler.py
index 797f946..61f57b8 100644
--- a/tests/test_local_scheduler.py
+++ b/tests/test_local_scheduler.py
@@ -52,7 +52,7 @@ async def test_local_scheduling(self, mocker, tmp_path):
         assert sched.quiet is False
         # Patch asyncio so we don't launch any real operations
         as_sub = mocker.patch(
-            "gator.scheduler.local.asyncio.create_subprocess_shell",
+            "gator.scheduler.local.asyncio.create_subprocess_exec",
             new=AsyncMock(),
         )
         as_tsk = mocker.patch(
@@ -87,10 +87,24 @@ def _create_proc(*_args, **_kwargs):
         as_sub.assert_has_calls(
             [
                 call(
-                    f"python3 -m gator --limit-error=0 --limit-critical=0"
-                    " --parent test:1234 --interval 7 --scheduler local --all-msg "
-                    f"--id T{x} --tracking {(tmp_path / f'T{x}').as_posix()}"
-                    " --sched-arg concurrency=1",
+                    "python3",
+                    "-m",
+                    "gator",
+                    "--limit-error=0",
+                    "--limit-critical=0",
+                    "--parent",
+                    "test:1234",
+                    "--interval",
+                    "7",
+                    "--scheduler",
+                    "local",
+                    "--all-msg",
+                    "--id",
+                    f"T{x}",
+                    "--tracking",
+                    (tmp_path / f"T{x}").as_posix(),
+                    "--sched-arg",
+                    "concurrency=1",
                     stdin=subprocess.DEVNULL,
                     stdout=subprocess.DEVNULL,
                     stderr=subprocess.STDOUT,
@@ -104,3 +118,84 @@ def _create_proc(*_args, **_kwargs):
         await sched.wait_for_all()
         # Check all monitors were fired up
         as_mon.assert_has_calls([call(f"T{x}", y) for x, y in zip(range(10), procs)])
+
+    async def test_scheduler_argument_safety(self, mocker, tmp_path):
+        """Ensure arguments with special characters are handled safely"""
+        # Create a scheduler
+        sched = LocalScheduler(
+            tracking=tmp_path / "tracking",
+            parent="test:1234",
+            interval=5,
+            quiet=True,
+            logger=self.logger,
+        )
+        # Patch asyncio so we don't launch any real operations
+        as_sub = mocker.patch(
+            "gator.scheduler.local.asyncio.create_subprocess_exec",
+            new=AsyncMock(),
+        )
+        mocker.patch.object(
+            sched,
+            "_LocalScheduler__monitor",
+            new=AsyncMock(wraps=sched._LocalScheduler__monitor),
+        )
+        procs = []
+
+        def _create_proc(*args, **kwargs):
+            nonlocal procs
+            # Capture the command arguments to verify they're passed as a list
+            proc = AsyncMock()
+            procs.append((proc, args, kwargs))
+            return proc
+
+        as_sub.side_effect = _create_proc
+
+        # Create a job with potentially dangerous characters in arguments
+        # These should be passed as literal arguments, not interpreted by shell
+        dangerous_job = Job(
+            "dangerous_test",
+            cwd=tmp_path.as_posix(),
+            command="echo",
+            args=[
+                "hello; rm -rf /",
+                "$(whoami)",
+                "`id`",
+                "&& cat /etc/passwd",
+            ],
+        )
+
+        # Note: Since gator launches jobs using its own command structure,
+        # the Job spec's command and args won't be directly passed to subprocess.
+        # Instead, gator uses "python3 -m gator" with the job spec.
+        # However, the fix ensures ANY arguments in the command list are safe.
+
+        # Launch the task
+        child = Child(
+            spec=dangerous_job,
+            ident="dangerous",
+            entry=MagicMock(),
+            tracking=tmp_path / "dangerous",
+        )
+        await sched.launch([child])
+
+        # Wait for launch
+        await sched.launch_task
+
+        # Verify create_subprocess_exec was called (not create_subprocess_shell)
+        assert as_sub.call_count == 1
+
+        # Get the command that was passed
+        _proc, cmd_args, cmd_kwargs = procs[0]
+
+        # Verify it's a list of arguments (as positional args to exec)
+        assert len(cmd_args) > 0, "Command should be passed as positional arguments"
+
+        # Verify the command starts with python3 -m gator (base command)
+        assert cmd_args[0] == "python3"
+        assert cmd_args[1] == "-m"
+        assert cmd_args[2] == "gator"
+
+        # Verify stdin/stdout/stderr are redirected
+        assert cmd_kwargs["stdin"] == subprocess.DEVNULL
+        assert cmd_kwargs["stdout"] == subprocess.DEVNULL
+        assert cmd_kwargs["stderr"] == subprocess.STDOUT

From 86be306d2031f010a88e7b484513f2c9be33656e Mon Sep 17 00:00:00 2001
From: Ed Nutting <github@ednutting.com>
Date: Thu, 15 Jan 2026 13:37:59 +0000
Subject: [PATCH 2/5] Fix expandvars stripping command substitution syntax from
 job args

The expandvars library was incorrectly processing command substitution
syntax like $(hostname) and converting it to (hostname), causing bash
syntax errors when jobs were executed.

Added utility functions to preserve command substitution patterns:
- find_command_substitutions(): Parses $(cmd) and \`cmd\` with proper
  nested parentheses support using a depth-tracking algorithm
- expand_vars_preserve_commands(): Replaces command substitutions with
  unique placeholders before expandvars processing, then restores them

This maintains all expandvars features (${VAR:-default}, nested vars, etc)
while ensuring shell command substitutions are passed through unchanged.

Changes:
- gator/common/utility.py: Added command substitution preservation utilities
- gator/wrapper.py: Updated to use new utility functions for arg expansion
- tests/test_command_substitution.py: Comprehensive test suite (25 tests)
- tests/test_wrapper.py: Added integration test for command substitution

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 gator/common/utility.py            | 104 +++++++++++++++-
 gator/wrapper.py                   |   8 +-
 tests/test_command_substitution.py | 184 +++++++++++++++++++++++++++++
 tests/test_wrapper.py              |  42 +++++++
 4 files changed, 330 insertions(+), 8 deletions(-)
 create mode 100644 tests/test_command_substitution.py

diff --git a/gator/common/utility.py b/gator/common/utility.py
index 8ff4c59..7ba380c 100644
--- a/gator/common/utility.py
+++ b/gator/common/utility.py
@@ -16,8 +16,11 @@
 import functools
 import os
 import pwd
+import uuid
 from typing import Awaitable, Callable, TypeVar, Union, overload
 
+import expandvars
+
 
 @functools.lru_cache
 def get_username() -> str:
@@ -34,15 +37,13 @@ def get_username() -> str:
     @overload
     def as_couroutine(
         fn: Callable[_P, Union[_R, Awaitable[_R]]],
-    ) -> Callable[_P, Awaitable[_R]]:
-        ...
+    ) -> Callable[_P, Awaitable[_R]]: ...
 except ImportError:
 
     @overload
     def as_couroutine(
         fn: Callable[..., Union[_R, Awaitable[_R]]],
-    ) -> Callable[..., Awaitable[_R]]:
-        ...
+    ) -> Callable[..., Awaitable[_R]]: ...
 
 
 def as_couroutine(fn):
@@ -56,3 +57,98 @@ async def async_fn(*args, **kwargs):
         return fn(*args, **kwargs)
 
     return async_fn
+
+
+def find_command_substitutions(text: str) -> list[tuple[int, int, str]]:
+    """
+    Find all command substitutions $(cmd) and `cmd` in the text, handling
+    nested parentheses correctly.
+
+    Returns a list of (start_pos, end_pos, original_text) tuples.
+    """
+    substitutions = []
+    i = 0
+
+    while i < len(text):
+        # Check for $(
+        if i < len(text) - 1 and text[i : i + 2] == "$(":
+            start = i
+            i += 2
+            depth = 1
+
+            # Find matching closing parenthesis
+            while i < len(text) and depth > 0:
+                if text[i] == "(":
+                    depth += 1
+                elif text[i] == ")":
+                    depth -= 1
+                i += 1
+
+            if depth == 0:
+                # Found matching closing paren
+                substitutions.append((start, i, text[start:i]))
+            # else: unmatched - let it through and shell will error
+
+        # Check for backticks
+        elif text[i] == "`":
+            start = i
+            i += 1
+
+            # Find closing backtick (no nesting for backticks)
+            while i < len(text) and text[i] != "`":
+                # Handle escaped backticks
+                if text[i] == "\\" and i + 1 < len(text):
+                    i += 2
+                else:
+                    i += 1
+
+            if i < len(text) and text[i] == "`":
+                i += 1
+                substitutions.append((start, i, text[start:i]))
+            # else: unmatched - let it through
+        else:
+            i += 1
+
+    return substitutions
+
+
+def expand_vars_preserve_commands(text: str, environ: dict) -> str:
+    """
+    Expand environment variables using expandvars, but preserve command
+    substitution syntax ($(cmd) and `cmd`) for the shell to handle later.
+
+    This prevents issues where expandvars would strip the $ from $(cmd),
+    turning it into (cmd) which is a syntax error.
+
+    Uses a placeholder approach:
+    1. Find and replace command substitutions with unique placeholders
+    2. Run expandvars on the text
+    3. Restore the command substitutions
+    """
+    # Find all command substitutions (handles nested parentheses)
+    substitutions = find_command_substitutions(text)
+
+    if not substitutions:
+        # No command substitutions, just expand normally
+        return expandvars.expand(text, environ=environ)
+
+    # Generate a unique prefix for placeholders to avoid collisions
+    unique_id = uuid.uuid4().hex[:8]
+
+    # Replace with placeholders in reverse order to maintain positions
+    placeholders = {}
+    result = text
+
+    for idx, (start, end, original) in enumerate(reversed(substitutions)):
+        placeholder = f"__GATOR_CMD_SUB_{unique_id}_{idx}__"
+        placeholders[placeholder] = original
+        result = result[:start] + placeholder + result[end:]
+
+    # Expand variables with expandvars
+    result = expandvars.expand(result, environ=environ)
+
+    # Restore command substitutions
+    for placeholder, original in placeholders.items():
+        result = result.replace(placeholder, original)
+
+    return result
diff --git a/gator/wrapper.py b/gator/wrapper.py
index cea0c51..27d855c 100644
--- a/gator/wrapper.py
+++ b/gator/wrapper.py
@@ -20,13 +20,13 @@
 from datetime import datetime
 from pathlib import Path
 
-import expandvars
 import psutil
 from tabulate import tabulate
 
 from .common.layer import BaseLayer, MetricResponse, UsageResponse
 from .common.summary import Summary
 from .common.types import Attribute, JobResult, LogSeverity, ProcStat
+from .common.utility import expand_vars_preserve_commands
 
 
 class Wrapper(BaseLayer):
@@ -243,9 +243,9 @@ async def __launch(self) -> None:
         env["PYTHONUNBUFFERED"] = "1"
         # Determine the working directory
         working_dir = Path((self.spec.cwd if self.spec else None) or Path.cwd())
-        # Expand variables in the command
-        command = expandvars.expand(self.spec.command, environ=env)
-        args = [expandvars.expand(str(arg), environ=env) for arg in self.spec.args]
+        # Expand variables in the command (but preserve shell command substitution)
+        command = expand_vars_preserve_commands(self.spec.command, environ=env)
+        args = [expand_vars_preserve_commands(str(arg), environ=env) for arg in self.spec.args]
         full_cmd = shlex.join((command, *args))
         # Ensure the tracking directory exists
         self.tracking.mkdir(parents=True, exist_ok=True)
diff --git a/tests/test_command_substitution.py b/tests/test_command_substitution.py
new file mode 100644
index 0000000..afc05d8
--- /dev/null
+++ b/tests/test_command_substitution.py
@@ -0,0 +1,184 @@
+# Copyright 2024, Peter Birch, mailto:peter@lightlogic.co.uk
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from gator.common.utility import expand_vars_preserve_commands, find_command_substitutions
+
+
+class TestCommandSubstitution:
+    """Test suite for command substitution handling in variable expansion"""
+
+    def test_find_simple_command_substitution(self):
+        """Test finding simple $(cmd) patterns"""
+        text = "echo $(hostname)"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0] == (5, 16, "$(hostname)")
+
+    def test_find_nested_command_substitution(self):
+        """Test finding nested $(cmd $(cmd)) patterns"""
+        text = "echo $(echo $(whoami))"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0] == (5, 22, "$(echo $(whoami))")
+
+    def test_find_complex_nested_command_substitution(self):
+        """Test finding complex nested patterns like $(date +%Y-$(date +%m))"""
+        text = "echo $(date +%Y-$(date +%m))"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0] == (5, 28, "$(date +%Y-$(date +%m))")
+
+    def test_find_backticks(self):
+        """Test finding `cmd` backtick patterns"""
+        text = "echo `hostname`"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0] == (5, 15, "`hostname`")
+
+    def test_find_escaped_backticks(self):
+        """Test handling escaped backticks"""
+        text = r"echo `echo \`nested\``"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        # Should capture the whole thing including escaped backticks
+        assert subs[0][2] == r"`echo \`nested\``"
+
+    def test_find_multiple_substitutions(self):
+        """Test finding multiple command substitutions in one string"""
+        text = "echo $(cmd) and `another`"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 2
+        assert subs[0] == (5, 11, "$(cmd)")
+        assert subs[1] == (16, 25, "`another`")
+
+    def test_find_with_variables(self):
+        """Test that variables don't interfere with finding command substitutions"""
+        text = "echo $HOME and $(hostname)"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0] == (15, 26, "$(hostname)")
+
+    def test_find_unmatched_paren(self):
+        """Test that unmatched parentheses are handled gracefully"""
+        text = "echo $(incomplete"
+        subs = find_command_substitutions(text)
+        # Should not find anything or handle gracefully
+        assert len(subs) == 0
+
+    def test_expand_preserve_simple_command_substitution(self):
+        """Test that simple command substitutions are preserved"""
+        text = "echo Hello from $(hostname)"
+        result = expand_vars_preserve_commands(text, {})
+        assert result == "echo Hello from $(hostname)"
+
+    def test_expand_preserve_nested_command_substitution(self):
+        """Test that nested command substitutions are preserved"""
+        text = "echo $(echo $(whoami))"
+        result = expand_vars_preserve_commands(text, {})
+        assert result == "echo $(echo $(whoami))"
+
+    def test_expand_preserve_complex_nested(self):
+        """Test that complex nested patterns are preserved"""
+        text = "echo $(date +%Y-$(date +%m))"
+        result = expand_vars_preserve_commands(text, {})
+        assert result == "echo $(date +%Y-$(date +%m))"
+
+    def test_expand_preserve_backticks(self):
+        """Test that backticks are preserved"""
+        text = "echo `hostname`"
+        result = expand_vars_preserve_commands(text, {})
+        assert result == "echo `hostname`"
+
+    def test_expand_variables_without_commands(self):
+        """Test that variables are expanded when no command substitutions present"""
+        text = "echo $HOME"
+        result = expand_vars_preserve_commands(text, {"HOME": "/root"})
+        assert result == "echo /root"
+
+    def test_expand_braced_variables(self):
+        """Test that braced variables are expanded"""
+        text = "echo ${HOME}"
+        result = expand_vars_preserve_commands(text, {"HOME": "/root"})
+        assert result == "echo /root"
+
+    def test_expand_variables_with_commands(self):
+        """Test that variables are expanded but commands are preserved"""
+        text = "echo $HOME and $(hostname)"
+        result = expand_vars_preserve_commands(text, {"HOME": "/root"})
+        assert result == "echo /root and $(hostname)"
+
+    def test_expand_default_values(self):
+        """Test expandvars default value syntax ${VAR:-default}"""
+        text = "echo ${HOME:-/default}"
+        result = expand_vars_preserve_commands(text, {})
+        assert result == "echo /default"
+
+    def test_expand_braced_with_suffix(self):
+        """Test braced variables with suffixes"""
+        text = "echo ${HOME}/subdir"
+        result = expand_vars_preserve_commands(text, {"HOME": "/root"})
+        assert result == "echo /root/subdir"
+
+    def test_expand_multiple_variables(self):
+        """Test multiple variable expansions"""
+        text = "echo $HOME$USER"
+        result = expand_vars_preserve_commands(text, {"HOME": "/root", "USER": "alice"})
+        assert result == "echo /rootalice"
+
+    def test_expand_complex_mixed(self):
+        """Test complex mix of variables and command substitutions"""
+        text = "echo $(date +%Y) in $HOME"
+        result = expand_vars_preserve_commands(text, {"HOME": "/root"})
+        assert result == "echo $(date +%Y) in /root"
+
+    def test_expand_backticks_with_variables(self):
+        """Test backticks preserved with variable expansion"""
+        text = "echo `cat /etc/hostname` and $USER"
+        result = expand_vars_preserve_commands(text, {"USER": "bob"})
+        assert result == "echo `cat /etc/hostname` and bob"
+
+    def test_empty_string(self):
+        """Test that empty strings are handled"""
+        result = expand_vars_preserve_commands("", {})
+        assert result == ""
+
+    def test_no_variables_no_commands(self):
+        """Test plain text with no variables or commands"""
+        text = "echo hello world"
+        result = expand_vars_preserve_commands(text, {})
+        assert result == "echo hello world"
+
+    def test_multiple_nested_levels(self):
+        """Test deeply nested command substitutions"""
+        text = "echo $(outer $(middle $(inner)))"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == "$(outer $(middle $(inner)))"
+
+        result = expand_vars_preserve_commands(text, {})
+        assert result == "echo $(outer $(middle $(inner)))"
+
+    def test_command_with_special_chars(self):
+        """Test command substitution with special characters"""
+        text = "echo $(grep -E '^pattern' file.txt)"
+        result = expand_vars_preserve_commands(text, {})
+        assert result == "echo $(grep -E '^pattern' file.txt)"
+
+    def test_placeholder_collision_resistance(self):
+        """Test that placeholder names don't collide with actual text"""
+        text = "echo __GATOR_CMD_SUB_0__ $(hostname)"
+        result = expand_vars_preserve_commands(text, {})
+        # Should preserve both the literal text and the command substitution
+        assert "$(hostname)" in result
+        assert "__GATOR_CMD_SUB_0__" in result
diff --git a/tests/test_wrapper.py b/tests/test_wrapper.py
index f19d95d..a1b2d7f 100644
--- a/tests/test_wrapper.py
+++ b/tests/test_wrapper.py
@@ -371,3 +371,45 @@ async def test_wrapper_metric(self, tmp_path, mocker) -> None:
         await wrp.stop()
         # Wait for task to complete
         await t_wrp
+
+    async def test_wrapper_command_substitution(self, tmp_path, mocker) -> None:
+        """Verify that command substitution $(cmd) and `cmd` are preserved"""
+        # Define a job specification with command substitution
+        job = Job(
+            "test",
+            cwd=tmp_path.as_posix(),
+            command="bash",
+            args=["-c", "echo Hello from $(hostname)"],
+        )
+        # Create a wrapper
+        trk_dir = tmp_path / "tracking"
+        wrp = Wrapper(spec=job, client=self.client, tracking=trk_dir, logger=self.logger)
+
+        # Mock the subprocess creation to inspect the command
+        original_exec = mocker.patch("asyncio.create_subprocess_exec")
+        mock_proc = AsyncMock()
+        mock_proc.pid = 12345
+        mock_proc.returncode = 0
+        mock_proc.wait = AsyncMock(return_value=0)
+        mock_proc.stdout = AsyncMock()
+        mock_proc.stdout.at_eof = lambda: True
+        mock_proc.stdout.readline = AsyncMock(return_value=b"")
+        mock_proc.stderr = AsyncMock()
+        mock_proc.stderr.at_eof = lambda: True
+        mock_proc.stderr.readline = AsyncMock(return_value=b"")
+        original_exec.return_value = mock_proc
+
+        # Run the job
+        await wrp.launch()
+
+        # Verify create_subprocess_exec was called
+        assert original_exec.called
+        call_args = original_exec.call_args
+
+        # The first positional arg should be the command
+        assert call_args[0][0] == "bash"
+        # The second should be "-c"
+        assert call_args[0][1] == "-c"
+        # The third should contain $(hostname) - NOT (hostname)!
+        assert call_args[0][2] == "echo Hello from $(hostname)"
+        assert "$(hostname)" in call_args[0][2], "Command substitution should be preserved"

From a11045d0647f01948bdd83dabab57a239d24ce4c Mon Sep 17 00:00:00 2001
From: Ed Nutting <github@ednutting.com>
Date: Thu, 15 Jan 2026 13:48:48 +0000
Subject: [PATCH 3/5] Add quote-aware parsing to command substitution detection

Enhanced find_command_substitutions() to properly handle shell quoting:
- Tracks single and double quote context while parsing
- Respects backslash escaping (only in double quotes and outside quotes)
- Correctly handles parentheses inside quoted strings like $(echo ")")
- Prevents premature closing on quoted characters

Added 28 comprehensive test cases covering:
- Parentheses in single and double quotes
- Escaped characters and backslashes
- Nested quotes in nested command substitutions
- Mixed quoting scenarios
- ANSI-C quoting ($'...')
- Arithmetic expansion $((..))
- Parameter expansion with special chars
- Commands with pipes, semicolons, redirects
- Glob patterns and brace expansion

This ensures commands like $(echo ")") are correctly parsed as a single
command substitution rather than failing on the quoted closing paren.

All 134 tests pass (106 original + 28 new).
---
 gator/common/utility.py            |  36 ++++-
 tests/test_command_substitution.py | 213 +++++++++++++++++++++++++++++
 2 files changed, 243 insertions(+), 6 deletions(-)

diff --git a/gator/common/utility.py b/gator/common/utility.py
index 7ba380c..ad3d4a8 100644
--- a/gator/common/utility.py
+++ b/gator/common/utility.py
@@ -62,7 +62,7 @@ async def async_fn(*args, **kwargs):
 def find_command_substitutions(text: str) -> list[tuple[int, int, str]]:
     """
     Find all command substitutions $(cmd) and `cmd` in the text, handling
-    nested parentheses correctly.
+    nested parentheses and quoted strings correctly.
 
     Returns a list of (start_pos, end_pos, original_text) tuples.
     """
@@ -75,13 +75,37 @@ def find_command_substitutions(text: str) -> list[tuple[int, int, str]]:
             start = i
             i += 2
             depth = 1
+            in_single_quote = False
+            in_double_quote = False
 
-            # Find matching closing parenthesis
+            # Find matching closing parenthesis, respecting quotes
             while i < len(text) and depth > 0:
-                if text[i] == "(":
-                    depth += 1
-                elif text[i] == ")":
-                    depth -= 1
+                char = text[i]
+
+                # Handle backslash escaping (only in double quotes or outside quotes)
+                if char == "\\" and not in_single_quote and i + 1 < len(text):
+                    i += 2  # Skip the backslash and next character
+                    continue
+
+                # Handle single quotes (toggle state, but not inside double quotes)
+                if char == "'" and not in_double_quote:
+                    in_single_quote = not in_single_quote
+                    i += 1
+                    continue
+
+                # Handle double quotes (toggle state, but not inside single quotes)
+                if char == '"' and not in_single_quote:
+                    in_double_quote = not in_double_quote
+                    i += 1
+                    continue
+
+                # Only count parentheses when not inside any quotes
+                if not in_single_quote and not in_double_quote:
+                    if char == "(":
+                        depth += 1
+                    elif char == ")":
+                        depth -= 1
+
                 i += 1
 
             if depth == 0:
diff --git a/tests/test_command_substitution.py b/tests/test_command_substitution.py
index afc05d8..d1dcda7 100644
--- a/tests/test_command_substitution.py
+++ b/tests/test_command_substitution.py
@@ -182,3 +182,216 @@ def test_placeholder_collision_resistance(self):
         # Should preserve both the literal text and the command substitution
         assert "$(hostname)" in result
         assert "__GATOR_CMD_SUB_0__" in result
+
+    def test_parentheses_in_double_quotes(self):
+        """Test that parentheses inside double quotes are handled correctly"""
+        text = '$(echo ")")'
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0] == (0, 11, '$(echo ")")')
+
+        result = expand_vars_preserve_commands(text, {})
+        assert result == '$(echo ")")'
+
+    def test_parentheses_in_single_quotes(self):
+        """Test that parentheses inside single quotes are handled correctly"""
+        text = "$(echo ')')"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0] == (0, 11, "$(echo ')')")
+
+        result = expand_vars_preserve_commands(text, {})
+        assert result == "$(echo ')')"
+
+    def test_escaped_parentheses(self):
+        """Test that escaped parentheses are handled correctly"""
+        text = r"$(echo \))"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0] == (0, 10, r"$(echo \))")
+
+    def test_complex_quoting(self):
+        """Test complex quoting scenarios"""
+        text = """$(echo "foo (bar)" 'baz (qux)' end)"""
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == """$(echo "foo (bar)" 'baz (qux)' end)"""
+
+    def test_nested_quotes(self):
+        """Test nested command substitution with quotes"""
+        text = '$(echo "outer $(echo inner)")'
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == '$(echo "outer $(echo inner)")'
+
+    def test_mixed_quotes_in_nested(self):
+        """Test nested command substitution with mixed quotes"""
+        text = """$(echo "$(echo 'nested')")"""
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == """$(echo "$(echo 'nested')")"""
+
+    def test_backslash_in_double_quotes(self):
+        """Test backslash escaping inside double quotes"""
+        text = r'$(echo "foo \" bar")'
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == r'$(echo "foo \" bar")'
+
+    def test_backslash_in_single_quotes(self):
+        """Test that backslashes are literal in single quotes"""
+        # Backslashes are literal in single quotes, so this is valid:
+        text = r"$(echo 'foo \ bar')"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == r"$(echo 'foo \ bar')"
+
+    def test_dollar_in_single_quotes(self):
+        """Test that $ is literal in single quotes"""
+        text = "$(echo '$HOME')"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == "$(echo '$HOME')"
+
+        result = expand_vars_preserve_commands(text, {"HOME": "/root"})
+        # $HOME should NOT be expanded inside the command substitution
+        assert result == "$(echo '$HOME')"
+
+    def test_dollar_in_double_quotes(self):
+        """Test that $ is special in double quotes"""
+        text = '$(echo "$HOME")'
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == '$(echo "$HOME")'
+
+        result = expand_vars_preserve_commands(text, {"HOME": "/root"})
+        # The whole command substitution should be preserved
+        assert result == '$(echo "$HOME")'
+
+    def test_multiple_levels_with_quotes(self):
+        """Test deeply nested substitutions with quotes"""
+        text = "$(outer \"$(middle '$(inner)')\")"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == "$(outer \"$(middle '$(inner)')\")"
+
+    def test_backticks_with_quotes(self):
+        """Test backticks with quoted content"""
+        text = '`echo "hello (world)"`'
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == '`echo "hello (world)"`'
+
+    def test_backticks_with_nested_backticks_escaped(self):
+        """Test escaped backticks inside backtick command substitution"""
+        text = r"`echo \`nested\``"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == r"`echo \`nested\``"
+
+    def test_empty_quotes(self):
+        """Test empty quoted strings"""
+        text = "$(echo \"\" '')"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == "$(echo \"\" '')"
+
+    def test_adjacent_quotes(self):
+        """Test adjacent quoted strings"""
+        text = "$(echo \"foo\"'bar')"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == "$(echo \"foo\"'bar')"
+
+    def test_escaped_dollar_outside_quotes(self):
+        """Test that escaped dollars are preserved"""
+        text = r"$(echo \$HOME)"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == r"$(echo \$HOME)"
+
+    def test_multiple_commands_with_quotes(self):
+        """Test multiple command substitutions with various quoting"""
+        text = """$(echo "foo)") and $(echo ')') and `echo ")"`"""
+        subs = find_command_substitutions(text)
+        assert len(subs) == 3
+        assert subs[0][2] == '$(echo "foo)")'
+        assert subs[1][2] == "$(echo ')')"
+        assert subs[2][2] == '`echo ")"`'
+
+    def test_ansi_c_quoting(self):
+        """Test ANSI-C quoting $'...' with escape sequences"""
+        text = r"$(echo $'hello\nworld')"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == r"$(echo $'hello\nworld')"
+
+    def test_arithmetic_expansion(self):
+        """Test arithmetic expansion $((...)) which has double parens"""
+        text = "$(echo $((1 + 2)))"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == "$(echo $((1 + 2)))"
+
+    def test_arithmetic_with_nested_parens(self):
+        """Test arithmetic with nested expressions"""
+        text = "$(echo $(($(echo 5) + 3)))"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == "$(echo $(($(echo 5) + 3)))"
+
+    def test_parameter_expansion(self):
+        """Test various parameter expansion forms"""
+        text = "$(echo ${var:-default})"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == "$(echo ${var:-default})"
+
+    def test_parameter_expansion_with_parens(self):
+        """Test parameter expansion with parentheses in default"""
+        text = '$(echo ${var:-"default (value)"})'
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == '$(echo ${var:-"default (value)"})'
+
+    def test_command_with_semicolons(self):
+        """Test commands with semicolons"""
+        text = "$(echo foo; echo bar)"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == "$(echo foo; echo bar)"
+
+    def test_command_with_pipes(self):
+        """Test commands with pipes"""
+        text = "$(echo foo | grep f)"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == "$(echo foo | grep f)"
+
+    def test_command_with_redirects(self):
+        """Test commands with redirections"""
+        text = "$(cat < file.txt > output.txt)"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == "$(cat < file.txt > output.txt)"
+
+    def test_glob_patterns(self):
+        """Test glob patterns inside command substitution"""
+        text = "$(ls *.txt)"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == "$(ls *.txt)"
+
+    def test_brace_expansion(self):
+        """Test brace expansion"""
+        text = "$(echo {a,b,c})"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == "$(echo {a,b,c})"
+
+    def test_tilde_expansion(self):
+        """Test tilde expansion"""
+        text = "$(ls ~/Documents)"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 1
+        assert subs[0][2] == "$(ls ~/Documents)"

From 75cdaac9d090440dfbe0c62a5dc414698b0d56f6 Mon Sep 17 00:00:00 2001
From: Ed Nutting <github@ednutting.com>
Date: Thu, 15 Jan 2026 14:20:42 +0000
Subject: [PATCH 4/5] Warn users when command substitutions are detected in
 non-shell commands

When running non-shell commands (anything other than bash, sh, zsh, etc.),
Gator now logs a warning if command substitutions like $(cmd) or `cmd` are
detected in the command or arguments. This helps users understand that Gator
only evaluates simple environment variables and command substitutions will
pass through unevaluated to the target command.

Shell commands are excluded from this warning since they handle command
substitutions natively.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 gator/wrapper.py      | 20 +++++++++++++-
 tests/test_wrapper.py | 61 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 80 insertions(+), 1 deletion(-)

diff --git a/gator/wrapper.py b/gator/wrapper.py
index 27d855c..97d89d0 100644
--- a/gator/wrapper.py
+++ b/gator/wrapper.py
@@ -26,7 +26,7 @@
 from .common.layer import BaseLayer, MetricResponse, UsageResponse
 from .common.summary import Summary
 from .common.types import Attribute, JobResult, LogSeverity, ProcStat
-from .common.utility import expand_vars_preserve_commands
+from .common.utility import expand_vars_preserve_commands, find_command_substitutions
 
 
 class Wrapper(BaseLayer):
@@ -246,6 +246,24 @@ async def __launch(self) -> None:
         # Expand variables in the command (but preserve shell command substitution)
         command = expand_vars_preserve_commands(self.spec.command, environ=env)
         args = [expand_vars_preserve_commands(str(arg), environ=env) for arg in self.spec.args]
+        # Check for command substitutions and warn user they won't be evaluated (unless using shell)
+        common_shells = {"sh", "bash", "zsh", "ksh", "csh", "tcsh", "fish", "dash"}
+        is_shell_command = Path(command).name in common_shells
+        if not is_shell_command:
+            detected_substitutions = []
+            for substitution in find_command_substitutions(command):
+                detected_substitutions.append(substitution[2])  # Extract original_text
+            for arg in args:
+                for substitution in find_command_substitutions(arg):
+                    detected_substitutions.append(substitution[2])  # Extract original_text
+            if detected_substitutions:
+                substitutions_list = "\n".join(f"  {sub}" for sub in detected_substitutions)
+                await self.logger.warning(
+                    "Gator only supports simple environment variable substitutions. "
+                    "Command substitutions will pass through to the command without being "
+                    "evaluated by Gator.\n"
+                    f"Detected command substitutions:\n{substitutions_list}"
+                )
         full_cmd = shlex.join((command, *args))
         # Ensure the tracking directory exists
         self.tracking.mkdir(parents=True, exist_ok=True)
diff --git a/tests/test_wrapper.py b/tests/test_wrapper.py
index a1b2d7f..b33eea1 100644
--- a/tests/test_wrapper.py
+++ b/tests/test_wrapper.py
@@ -413,3 +413,64 @@ async def test_wrapper_command_substitution(self, tmp_path, mocker) -> None:
         # The third should contain $(hostname) - NOT (hostname)!
         assert call_args[0][2] == "echo Hello from $(hostname)"
         assert "$(hostname)" in call_args[0][2], "Command substitution should be preserved"
+
+    async def test_wrapper_command_substitution_warning(self, tmp_path) -> None:
+        """Verify that a warning is logged when command substitutions are detected in
+        non-shell commands"""
+        # Define a job specification with command substitution in a non-shell command
+        job = Job(
+            "test",
+            cwd=tmp_path.as_posix(),
+            command="echo",
+            args=["Hello from $(hostname)", "and `date`"],
+        )
+        # Create a wrapper
+        trk_dir = tmp_path / "tracking"
+        wrp = Wrapper(spec=job, client=self.client, tracking=trk_dir, logger=self.logger)
+
+        # Run the job
+        await wrp.launch()
+
+        # Check that a warning was logged
+        mcs = self.mk_db.push_logentry.mock_calls
+        warning_logs = [
+            x.args[0]
+            for x in mcs
+            if x.args[0].severity is LogSeverity.WARNING
+        ]
+        assert len(warning_logs) > 0, "Expected at least one warning log entry"
+
+        # Check the warning message contains the expected information
+        warning_msg = warning_logs[0].message
+        assert "Detected command substitutions:" in warning_msg
+        assert "$(hostname)" in warning_msg
+        assert "`date`" in warning_msg
+        assert "Gator only supports simple environment variable substitutions" in warning_msg
+        assert "will pass through to the command without being evaluated" in warning_msg
+
+    async def test_wrapper_command_substitution_no_warning_for_shells(self, tmp_path) -> None:
+        """Verify that NO warning is logged when command substitutions are used with
+        shell commands"""
+        # Define a job specification with command substitution using bash
+        job = Job(
+            "test",
+            cwd=tmp_path.as_posix(),
+            command="bash",
+            args=["-c", "echo Hello from $(hostname)"],
+        )
+        # Create a wrapper
+        trk_dir = tmp_path / "tracking"
+        wrp = Wrapper(spec=job, client=self.client, tracking=trk_dir, logger=self.logger)
+
+        # Run the job
+        await wrp.launch()
+
+        # Check that NO warning was logged about command substitutions
+        mcs = self.mk_db.push_logentry.mock_calls
+        warning_logs = [
+            x.args[0]
+            for x in mcs
+            if x.args[0].severity is LogSeverity.WARNING
+            and "Command substitution" in x.args[0].message
+        ]
+        assert len(warning_logs) == 0, "Expected no warning for shell commands with substitutions"

From ea9aabe5ca8e1307d34e6284b39eb82978d6bb6b Mon Sep 17 00:00:00 2001
From: Ed Nutting <github@ednutting.com>
Date: Thu, 15 Jan 2026 20:41:05 +0000
Subject: [PATCH 5/5] Upgrade to new expandvars package version

---
 gator/common/utility.py            |  45 ----------
 gator/wrapper.py                   |   9 +-
 pyproject.toml                     |   2 +-
 tests/test_command_substitution.py | 131 +++--------------------------
 4 files changed, 20 insertions(+), 167 deletions(-)

diff --git a/gator/common/utility.py b/gator/common/utility.py
index ad3d4a8..6ecfb3e 100644
--- a/gator/common/utility.py
+++ b/gator/common/utility.py
@@ -16,11 +16,8 @@
 import functools
 import os
 import pwd
-import uuid
 from typing import Awaitable, Callable, TypeVar, Union, overload
 
-import expandvars
-
 
 @functools.lru_cache
 def get_username() -> str:
@@ -134,45 +131,3 @@ def find_command_substitutions(text: str) -> list[tuple[int, int, str]]:
             i += 1
 
     return substitutions
-
-
-def expand_vars_preserve_commands(text: str, environ: dict) -> str:
-    """
-    Expand environment variables using expandvars, but preserve command
-    substitution syntax ($(cmd) and `cmd`) for the shell to handle later.
-
-    This prevents issues where expandvars would strip the $ from $(cmd),
-    turning it into (cmd) which is a syntax error.
-
-    Uses a placeholder approach:
-    1. Find and replace command substitutions with unique placeholders
-    2. Run expandvars on the text
-    3. Restore the command substitutions
-    """
-    # Find all command substitutions (handles nested parentheses)
-    substitutions = find_command_substitutions(text)
-
-    if not substitutions:
-        # No command substitutions, just expand normally
-        return expandvars.expand(text, environ=environ)
-
-    # Generate a unique prefix for placeholders to avoid collisions
-    unique_id = uuid.uuid4().hex[:8]
-
-    # Replace with placeholders in reverse order to maintain positions
-    placeholders = {}
-    result = text
-
-    for idx, (start, end, original) in enumerate(reversed(substitutions)):
-        placeholder = f"__GATOR_CMD_SUB_{unique_id}_{idx}__"
-        placeholders[placeholder] = original
-        result = result[:start] + placeholder + result[end:]
-
-    # Expand variables with expandvars
-    result = expandvars.expand(result, environ=environ)
-
-    # Restore command substitutions
-    for placeholder, original in placeholders.items():
-        result = result.replace(placeholder, original)
-
-    return result
diff --git a/gator/wrapper.py b/gator/wrapper.py
index 97d89d0..2930f4f 100644
--- a/gator/wrapper.py
+++ b/gator/wrapper.py
@@ -20,13 +20,14 @@
 from datetime import datetime
 from pathlib import Path
 
+import expandvars
 import psutil
 from tabulate import tabulate
 
 from .common.layer import BaseLayer, MetricResponse, UsageResponse
 from .common.summary import Summary
 from .common.types import Attribute, JobResult, LogSeverity, ProcStat
-from .common.utility import expand_vars_preserve_commands, find_command_substitutions
+from .common.utility import find_command_substitutions
 
 
 class Wrapper(BaseLayer):
@@ -243,9 +244,9 @@ async def __launch(self) -> None:
         env["PYTHONUNBUFFERED"] = "1"
         # Determine the working directory
         working_dir = Path((self.spec.cwd if self.spec else None) or Path.cwd())
-        # Expand variables in the command (but preserve shell command substitution)
-        command = expand_vars_preserve_commands(self.spec.command, environ=env)
-        args = [expand_vars_preserve_commands(str(arg), environ=env) for arg in self.spec.args]
+        # Expand variables in the command
+        command = expandvars.expand(self.spec.command, environ=env)
+        args = [expandvars.expand(str(arg), environ=env) for arg in self.spec.args]
         # Check for command substitutions and warn user they won't be evaluated (unless using shell)
         common_shells = {"sh", "bash", "zsh", "ksh", "csh", "tcsh", "fish", "dash"}
         is_shell_command = Path(command).name in common_shells
diff --git a/pyproject.toml b/pyproject.toml
index 1e1089c..16dbda3 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -14,7 +14,7 @@ psutil = "^5.9.4"
 rich = "^13.3.4"
 tabulate = "^0.9.0"
 pyyaml = "^6.0"
-expandvars = "^0.9.0"
+expandvars = "^1.1.2"
 websockets = "^11.0.2"
 aiosqlite = "^0.19.0"
 aiohttp = "^3.12.13"
diff --git a/tests/test_command_substitution.py b/tests/test_command_substitution.py
index d1dcda7..ceb525e 100644
--- a/tests/test_command_substitution.py
+++ b/tests/test_command_substitution.py
@@ -12,11 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from gator.common.utility import expand_vars_preserve_commands, find_command_substitutions
+from gator.common.utility import find_command_substitutions
 
 
-class TestCommandSubstitution:
-    """Test suite for command substitution handling in variable expansion"""
+class TestFindCommandSubstitutions:
+    """Test suite for finding command substitutions in text"""
 
     def test_find_simple_command_substitution(self):
         """Test finding simple $(cmd) patterns"""
@@ -76,89 +76,6 @@ def test_find_unmatched_paren(self):
         # Should not find anything or handle gracefully
         assert len(subs) == 0
 
-    def test_expand_preserve_simple_command_substitution(self):
-        """Test that simple command substitutions are preserved"""
-        text = "echo Hello from $(hostname)"
-        result = expand_vars_preserve_commands(text, {})
-        assert result == "echo Hello from $(hostname)"
-
-    def test_expand_preserve_nested_command_substitution(self):
-        """Test that nested command substitutions are preserved"""
-        text = "echo $(echo $(whoami))"
-        result = expand_vars_preserve_commands(text, {})
-        assert result == "echo $(echo $(whoami))"
-
-    def test_expand_preserve_complex_nested(self):
-        """Test that complex nested patterns are preserved"""
-        text = "echo $(date +%Y-$(date +%m))"
-        result = expand_vars_preserve_commands(text, {})
-        assert result == "echo $(date +%Y-$(date +%m))"
-
-    def test_expand_preserve_backticks(self):
-        """Test that backticks are preserved"""
-        text = "echo `hostname`"
-        result = expand_vars_preserve_commands(text, {})
-        assert result == "echo `hostname`"
-
-    def test_expand_variables_without_commands(self):
-        """Test that variables are expanded when no command substitutions present"""
-        text = "echo $HOME"
-        result = expand_vars_preserve_commands(text, {"HOME": "/root"})
-        assert result == "echo /root"
-
-    def test_expand_braced_variables(self):
-        """Test that braced variables are expanded"""
-        text = "echo ${HOME}"
-        result = expand_vars_preserve_commands(text, {"HOME": "/root"})
-        assert result == "echo /root"
-
-    def test_expand_variables_with_commands(self):
-        """Test that variables are expanded but commands are preserved"""
-        text = "echo $HOME and $(hostname)"
-        result = expand_vars_preserve_commands(text, {"HOME": "/root"})
-        assert result == "echo /root and $(hostname)"
-
-    def test_expand_default_values(self):
-        """Test expandvars default value syntax ${VAR:-default}"""
-        text = "echo ${HOME:-/default}"
-        result = expand_vars_preserve_commands(text, {})
-        assert result == "echo /default"
-
-    def test_expand_braced_with_suffix(self):
-        """Test braced variables with suffixes"""
-        text = "echo ${HOME}/subdir"
-        result = expand_vars_preserve_commands(text, {"HOME": "/root"})
-        assert result == "echo /root/subdir"
-
-    def test_expand_multiple_variables(self):
-        """Test multiple variable expansions"""
-        text = "echo $HOME$USER"
-        result = expand_vars_preserve_commands(text, {"HOME": "/root", "USER": "alice"})
-        assert result == "echo /rootalice"
-
-    def test_expand_complex_mixed(self):
-        """Test complex mix of variables and command substitutions"""
-        text = "echo $(date +%Y) in $HOME"
-        result = expand_vars_preserve_commands(text, {"HOME": "/root"})
-        assert result == "echo $(date +%Y) in /root"
-
-    def test_expand_backticks_with_variables(self):
-        """Test backticks preserved with variable expansion"""
-        text = "echo `cat /etc/hostname` and $USER"
-        result = expand_vars_preserve_commands(text, {"USER": "bob"})
-        assert result == "echo `cat /etc/hostname` and bob"
-
-    def test_empty_string(self):
-        """Test that empty strings are handled"""
-        result = expand_vars_preserve_commands("", {})
-        assert result == ""
-
-    def test_no_variables_no_commands(self):
-        """Test plain text with no variables or commands"""
-        text = "echo hello world"
-        result = expand_vars_preserve_commands(text, {})
-        assert result == "echo hello world"
-
     def test_multiple_nested_levels(self):
         """Test deeply nested command substitutions"""
         text = "echo $(outer $(middle $(inner)))"
@@ -166,23 +83,6 @@ def test_multiple_nested_levels(self):
         assert len(subs) == 1
         assert subs[0][2] == "$(outer $(middle $(inner)))"
 
-        result = expand_vars_preserve_commands(text, {})
-        assert result == "echo $(outer $(middle $(inner)))"
-
-    def test_command_with_special_chars(self):
-        """Test command substitution with special characters"""
-        text = "echo $(grep -E '^pattern' file.txt)"
-        result = expand_vars_preserve_commands(text, {})
-        assert result == "echo $(grep -E '^pattern' file.txt)"
-
-    def test_placeholder_collision_resistance(self):
-        """Test that placeholder names don't collide with actual text"""
-        text = "echo __GATOR_CMD_SUB_0__ $(hostname)"
-        result = expand_vars_preserve_commands(text, {})
-        # Should preserve both the literal text and the command substitution
-        assert "$(hostname)" in result
-        assert "__GATOR_CMD_SUB_0__" in result
-
     def test_parentheses_in_double_quotes(self):
         """Test that parentheses inside double quotes are handled correctly"""
         text = '$(echo ")")'
@@ -190,9 +90,6 @@ def test_parentheses_in_double_quotes(self):
         assert len(subs) == 1
         assert subs[0] == (0, 11, '$(echo ")")')
 
-        result = expand_vars_preserve_commands(text, {})
-        assert result == '$(echo ")")'
-
     def test_parentheses_in_single_quotes(self):
         """Test that parentheses inside single quotes are handled correctly"""
         text = "$(echo ')')"
@@ -200,9 +97,6 @@ def test_parentheses_in_single_quotes(self):
         assert len(subs) == 1
         assert subs[0] == (0, 11, "$(echo ')')")
 
-        result = expand_vars_preserve_commands(text, {})
-        assert result == "$(echo ')')"
-
     def test_escaped_parentheses(self):
         """Test that escaped parentheses are handled correctly"""
         text = r"$(echo \))"
@@ -253,10 +147,6 @@ def test_dollar_in_single_quotes(self):
         assert len(subs) == 1
         assert subs[0][2] == "$(echo '$HOME')"
 
-        result = expand_vars_preserve_commands(text, {"HOME": "/root"})
-        # $HOME should NOT be expanded inside the command substitution
-        assert result == "$(echo '$HOME')"
-
     def test_dollar_in_double_quotes(self):
         """Test that $ is special in double quotes"""
         text = '$(echo "$HOME")'
@@ -264,10 +154,6 @@ def test_dollar_in_double_quotes(self):
         assert len(subs) == 1
         assert subs[0][2] == '$(echo "$HOME")'
 
-        result = expand_vars_preserve_commands(text, {"HOME": "/root"})
-        # The whole command substitution should be preserved
-        assert result == '$(echo "$HOME")'
-
     def test_multiple_levels_with_quotes(self):
         """Test deeply nested substitutions with quotes"""
         text = "$(outer \"$(middle '$(inner)')\")"
@@ -395,3 +281,14 @@ def test_tilde_expansion(self):
         subs = find_command_substitutions(text)
         assert len(subs) == 1
         assert subs[0][2] == "$(ls ~/Documents)"
+
+    def test_no_command_substitutions(self):
+        """Test text with no command substitutions"""
+        text = "echo hello world"
+        subs = find_command_substitutions(text)
+        assert len(subs) == 0
+
+    def test_empty_string(self):
+        """Test empty string"""
+        subs = find_command_substitutions("")
+        assert len(subs) == 0