refactor: introduce ShellBasedSandbox, make all Sandbox methods abstract, fix 3 bugs

## Class hierarchy refactor

- Make all 5 methods abstract on Sandbox ABC: execute(), execute_code(),
  read_file(), write_file(), list_files()
- Create ShellBasedSandbox(Sandbox) — still abstract (execute() unimplemented)
  but provides shell-based defaults for the other 4 operations
- Move _execute_to_result and _execute_code_to_result to ShellBasedSandbox
- Update LocalSandbox and DockerSandbox to extend ShellBasedSandbox
- Export ShellBasedSandbox from sandbox/__init__.py and strands/__init__.py

New hierarchy:
  Sandbox (ABC, all 5 abstract + lifecycle)
    └── ShellBasedSandbox (ABC, only execute() abstract)
          ├── LocalSandbox (concrete)
          └── DockerSandbox (concrete)

## Bug fixes

Bug 1 — Language parameter injection in execute_code():
  The language parameter was interpolated unquoted into a shell command,
  allowing values like 'python; rm -rf /' to execute arbitrary commands.
  Fix: Validate language against an allowlist + strict regex, and
  shlex.quote() the language in the command string.

Bug 2 — Long output lines (>64KB) block readline() in LocalSandbox:
  readline() can block indefinitely on very long lines without newlines.
  Fix: Replace readline() with read(64KB) chunked reads.

Bug 3 — Non-existent working_dir raises unhandled FileNotFoundError:
  LocalSandbox.start() now creates the working directory if it doesn't
  exist, and raises NotADirectoryError if the path is a file.

## Tests

- Update test_base.py: test Sandbox ABC (all 5 abstract), ShellBasedSandbox,
  and add TestLanguageValidation with 11 injection tests
- Update test_local.py: add tests for long output, language injection,
  and working directory validation (4 new tests)
- Update test_docker.py: verify ShellBasedSandbox inheritance
- Update test_agent_sandbox.py: verify ShellBasedSandbox in hierarchy
- Total: 102 sandbox tests pass

Author: Strands Agent

src/strands/__init__.py

@@ -5,7 +5,7 @@
 from .agent.base import AgentBase
 from .event_loop._retry import ModelRetryStrategy
 from .plugins import Plugin
-from .sandbox.base import ExecutionResult, Sandbox
+from .sandbox.base import ExecutionResult, Sandbox, ShellBasedSandbox
 from .sandbox.docker import DockerSandbox
 from .sandbox.local import LocalSandbox
 from .tools.decorator import tool
@@ -25,6 +25,7 @@
     "Plugin",
     "sandbox",
     "Sandbox",
+    "ShellBasedSandbox",
     "Skill",
     "tool",
     "ToolContext",

src/strands/sandbox/__init__.py

@@ -4,13 +4,15 @@
 Tools that need to execute code or access a filesystem receive a Sandbox instead of managing
 their own execution, enabling portability across local, Docker, and cloud environments.
 
-Concrete implementations:
+Class hierarchy::
 
-- ``LocalSandbox`` — runs on the host via asyncio subprocesses (default)
-- ``DockerSandbox`` — runs inside a Docker container
+    Sandbox (ABC, all 5 abstract + lifecycle)
+      └── ShellBasedSandbox (ABC, only execute() abstract — shell-based file ops + execute_code)
+            ├── LocalSandbox — runs on the host via asyncio subprocesses (default)
+            └── DockerSandbox — runs inside a Docker container
 """
 
-from .base import ExecutionResult, Sandbox
+from .base import ExecutionResult, Sandbox, ShellBasedSandbox
 from .docker import DockerSandbox
 from .local import LocalSandbox
 
@@ -19,4 +21,5 @@
     "ExecutionResult",
     "LocalSandbox",
     "Sandbox",
+    "ShellBasedSandbox",
 ]

src/strands/sandbox/base.py

@@ -1,15 +1,22 @@
 """Base sandbox interface for agent code execution environments.
 
-This module defines the abstract Sandbox class and the ExecutionResult dataclass.
+This module defines the abstract Sandbox class, the ShellBasedSandbox class, and
+the ExecutionResult dataclass.
+
 Sandbox implementations provide the runtime context where tools execute code, run commands,
 and interact with a filesystem. Multiple tools share the same Sandbox instance, giving them
 a common working directory, environment variables, and filesystem.
 
-Implementations only need to provide execute(). All other methods are built on top of it.
-Implementations may override convenience methods with native versions for better performance.
+Class hierarchy:
+
+- ``Sandbox`` (ABC): All 5 operations are abstract. Implement this for non-shell-based
+  sandboxes (e.g., API-based cloud sandboxes).
+- ``ShellBasedSandbox`` (ABC): Provides shell-based defaults for file operations and code
+  execution. Subclasses only need to implement ``execute()``.
 """
 
 import logging
+import re
 import secrets
 import shlex
 from abc import ABC, abstractmethod
@@ -19,6 +26,24 @@
 
 logger = logging.getLogger(__name__)
 
+#: Allowlist of language interpreters permitted in :meth:`ShellBasedSandbox.execute_code`.
+#: Prevents command injection via the ``language`` parameter.
+ALLOWED_LANGUAGES = frozenset(
+    {
+        "bash",
+        "node",
+        "perl",
+        "php",
+        "python",
+        "python3",
+        "ruby",
+        "sh",
+    }
+)
+
+#: Regex that matches a bare interpreter name (alphanumeric, dots, hyphens).
+_LANGUAGE_RE = re.compile(r"^[a-zA-Z0-9._-]+$")
+
 
 @dataclass
 class ExecutionResult:
@@ -43,10 +68,10 @@ class Sandbox(ABC):
     share the same Sandbox instance, giving them a common working
     directory, environment variables, and filesystem.
 
-    Implementations only need to provide execute(). All other methods
-    are built on top of it. Implementations may override convenience
-    methods with native versions for better performance (for example,
-    LocalSandbox overrides read_file/write_file with native file I/O).
+    All five operations — ``execute``, ``execute_code``, ``read_file``,
+    ``write_file``, and ``list_files`` — are abstract. Implement this
+    directly for non-shell-based backends (e.g., API-driven cloud sandboxes).
+    For shell-based backends, extend :class:`ShellBasedSandbox` instead.
 
     The sandbox auto-starts on the first ``execute()`` call if not already
     started, so callers do not need to manually call ``start()`` or use
@@ -78,9 +103,6 @@ async def execute(
         Yields stdout/stderr lines as they arrive. The final yield
         is an ExecutionResult with the exit code and complete output.
 
-        This is the only method implementations must provide. All other
-        methods are built on top of this one by default.
-
         The sandbox is auto-started on the first call if not already started.
 
         Args:
@@ -95,6 +117,7 @@ async def execute(
         # Concrete subclasses must yield at least one ExecutionResult.
         yield  # type: ignore[misc]  # pragma: no cover
 
+    @abstractmethod
     async def execute_code(
         self,
         code: str,
@@ -103,19 +126,143 @@ async def execute_code(
     ) -> AsyncGenerator[str | ExecutionResult, None]:
         """Execute code in the sandbox, streaming output.
 
-        Override for native code execution support. The default implementation
-        passes code to the language interpreter via ``-c`` with proper shell
-        quoting.
+        Args:
+            code: The source code to execute.
+            language: The programming language interpreter to use.
+            timeout: Maximum execution time in seconds. None means no timeout.
+
+        Yields:
+            str lines of output as they arrive, then a final ExecutionResult.
+        """
+        ...
+        yield  # type: ignore[misc]  # pragma: no cover
+
+    @abstractmethod
+    async def read_file(self, path: str) -> str:
+        """Read a file from the sandbox filesystem.
+
+        Args:
+            path: Path to the file to read.
+
+        Returns:
+            The file contents as a string.
+
+        Raises:
+            FileNotFoundError: If the file does not exist or cannot be read.
+        """
+        ...
+
+    @abstractmethod
+    async def write_file(self, path: str, content: str) -> None:
+        """Write a file to the sandbox filesystem.
+
+        Args:
+            path: Path to the file to write.
+            content: The content to write to the file.
+
+        Raises:
+            IOError: If the file cannot be written.
+        """
+        ...
+
+    @abstractmethod
+    async def list_files(self, path: str = ".") -> list[str]:
+        """List files in a sandbox directory.
+
+        Args:
+            path: Path to the directory to list.
+
+        Returns:
+            A list of filenames in the directory.
+
+        Raises:
+            FileNotFoundError: If the directory does not exist.
+        """
+        ...
+
+    async def _ensure_started(self) -> None:
+        """Auto-start the sandbox if it has not been started yet."""
+        if not self._started:
+            await self.start()
+            self._started = True
+
+    async def start(self) -> None:
+        """Initialize the sandbox.
+
+        Called once before first use. Override to perform setup such as
+        starting containers or creating temporary directories.
+        """
+        self._started = True
+
+    async def stop(self) -> None:
+        """Clean up sandbox resources.
+
+        Override to perform cleanup such as stopping containers or
+        removing temporary directories.
+        """
+        self._started = False
+
+    async def __aenter__(self) -> "Sandbox":
+        """Enter the async context manager, starting the sandbox."""
+        await self.start()
+        self._started = True
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        """Exit the async context manager, stopping the sandbox."""
+        await self.stop()
+        self._started = False
+
+
+class ShellBasedSandbox(Sandbox, ABC):
+    """Abstract sandbox that provides shell-based defaults for file and code operations.
+
+    Subclasses only need to implement :meth:`execute`. The remaining four
+    operations — ``read_file``, ``write_file``, ``list_files``, and
+    ``execute_code`` — are implemented via shell commands piped through
+    ``execute()``.
+
+    Subclasses may override any method with a native implementation for
+    better performance (e.g., ``LocalSandbox`` overrides ``read_file``
+    and ``write_file`` with direct filesystem calls).
+
+    Class hierarchy::
+
+        Sandbox (ABC, all 5 abstract + lifecycle)
+          └── ShellBasedSandbox (ABC, only execute() abstract)
+                ├── LocalSandbox
+                └── DockerSandbox
+    """
+
+    async def execute_code(
+        self,
+        code: str,
+        language: str = "python",
+        timeout: int | None = None,
+    ) -> AsyncGenerator[str | ExecutionResult, None]:
+        """Execute code in the sandbox, streaming output.
+
+        The default implementation passes code to the language interpreter
+        via ``-c`` with proper shell quoting. The ``language`` parameter is
+        validated against an allowlist to prevent command injection.
 
         Args:
             code: The source code to execute.
             language: The programming language interpreter to use.
+                Must match :data:`ALLOWED_LANGUAGES` or be a simple
+                interpreter name (alphanumeric, dots, hyphens only).
             timeout: Maximum execution time in seconds. None means no timeout.
 
         Yields:
             str lines of output as they arrive, then a final ExecutionResult.
+
+        Raises:
+            ValueError: If the language name is not allowed.
         """
-        async for chunk in self.execute(f"{language} -c {shlex.quote(code)}", timeout=timeout):
+        _validate_language(language)
+        async for chunk in self.execute(
+            f"{shlex.quote(language)} -c {shlex.quote(code)}", timeout=timeout
+        ):
             yield chunk
 
     async def _execute_to_result(self, command: str, timeout: int | None = None) -> ExecutionResult:
@@ -229,35 +376,23 @@ async def list_files(self, path: str = ".") -> list[str]:
             raise FileNotFoundError(result.stderr)
         return [f for f in result.stdout.strip().split("\n") if f]
 
-    async def _ensure_started(self) -> None:
-        """Auto-start the sandbox if it has not been started yet."""
-        if not self._started:
-            await self.start()
-            self._started = True
-
-    async def start(self) -> None:
-        """Initialize the sandbox.
-
-        Called once before first use. Override to perform setup such as
-        starting containers or creating temporary directories.
-        """
-        self._started = True
 
-    async def stop(self) -> None:
-        """Clean up sandbox resources.
+def _validate_language(language: str) -> None:
+    """Validate a language interpreter name to prevent command injection.
 
-        Override to perform cleanup such as stopping containers or
-        removing temporary directories.
-        """
-        self._started = False
+    The language must either be in the :data:`ALLOWED_LANGUAGES` allowlist or
+    match a strict regex pattern (alphanumeric characters, dots, and hyphens only).
 
-    async def __aenter__(self) -> "Sandbox":
-        """Enter the async context manager, starting the sandbox."""
-        await self.start()
-        self._started = True
-        return self
+    Args:
+        language: The language interpreter name to validate.
 
-    async def __aexit__(self, *args: Any) -> None:
-        """Exit the async context manager, stopping the sandbox."""
-        await self.stop()
-        self._started = False
+    Raises:
+        ValueError: If the language name is not allowed.
+    """
+    if language in ALLOWED_LANGUAGES:
+        return
+    if not _LANGUAGE_RE.match(language):
+        raise ValueError(
+            "language must be an alphanumeric interpreter name "
+            "(e.g. 'python', 'node'), got: %r" % language
+        )

src/strands/sandbox/docker.py

@@ -14,12 +14,12 @@
 from collections.abc import AsyncGenerator
 from typing import Any
 
-from .base import ExecutionResult, Sandbox
+from .base import ExecutionResult, ShellBasedSandbox
 
 logger = logging.getLogger(__name__)
 
 
-class DockerSandbox(Sandbox):
+class DockerSandbox(ShellBasedSandbox):
     """Execute code and commands in a Docker container.
 
     The container is created during start() and removed during stop().