stirrup 0.1.4__tar.gz → 0.1.6__tar.gz

{stirrup-0.1.4 → stirrup-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: stirrup
-Version: 0.1.4
+Version: 0.1.6
 Summary: The lightweight foundation for building agents
 Keywords: ai,agent,llm,openai,anthropic,tools,framework
 Author: Artificial Analysis, Inc.
@@ -77,20 +77,20 @@ Description-Content-Type: text/markdown
 <br>
 </div>
 
-
 <p align="center">
   <a href="https://pypi.python.org/pypi/stirrup"><img src="https://img.shields.io/pypi/v/stirrup" alt="PyPI version" /></a>&nbsp;<!--
   --><a href="https://github.com/ArtificialAnalysis/Stirrup/blob/main/LICENSE"><img src="https://img.shields.io/github/license/ArtificialAnalysis/Stirrup" alt="License" /></a>&nbsp;<!--
   --><a href="https://stirrup.artificialanalysis.ai"><img src="https://img.shields.io/badge/MkDocs-4F46E5?logo=materialformkdocs&logoColor=fff" alt="MkDocs" /></a>
 </p>
 
-
 Stirrup is a lightweight framework, or starting point template, for building agents. It differs from other agent frameworks by:
 
 - **Working with the model, not against it:** Stirrup gets out of the way and lets the model choose its own approach to completing tasks (similar to Claude Code). Many frameworks impose rigid workflows that can degrade results.
 - **Best practices and tools built-in:** We analyzed the leading agents (Claude Code, Codex, and others) to understand and incorporate best practices relating to topics like context management and foundational tools (e.g., code execution).
 - **Fully customizable:** Use Stirrup as a package or as a starting template to build your own fully customized agents.
 
+> **Note:** This is the Python implementation, [StirrupJS](https://github.com/ArtificialAnalysis/StirrupJS) is the Typescript implementation.
+
 ## Features
 
 - 🧪 **Code execution:** Run code locally, in Docker, or in an E2B sandbox

{stirrup-0.1.4 → stirrup-0.1.6}/README.md

@@ -9,20 +9,20 @@
 <br>
 </div>
 
-
 <p align="center">
   <a href="https://pypi.python.org/pypi/stirrup"><img src="https://img.shields.io/pypi/v/stirrup" alt="PyPI version" /></a>&nbsp;<!--
   --><a href="https://github.com/ArtificialAnalysis/Stirrup/blob/main/LICENSE"><img src="https://img.shields.io/github/license/ArtificialAnalysis/Stirrup" alt="License" /></a>&nbsp;<!--
   --><a href="https://stirrup.artificialanalysis.ai"><img src="https://img.shields.io/badge/MkDocs-4F46E5?logo=materialformkdocs&logoColor=fff" alt="MkDocs" /></a>
 </p>
 
-
 Stirrup is a lightweight framework, or starting point template, for building agents. It differs from other agent frameworks by:
 
 - **Working with the model, not against it:** Stirrup gets out of the way and lets the model choose its own approach to completing tasks (similar to Claude Code). Many frameworks impose rigid workflows that can degrade results.
 - **Best practices and tools built-in:** We analyzed the leading agents (Claude Code, Codex, and others) to understand and incorporate best practices relating to topics like context management and foundational tools (e.g., code execution).
 - **Fully customizable:** Use Stirrup as a package or as a starting template to build your own fully customized agents.
 
+> **Note:** This is the Python implementation, [StirrupJS](https://github.com/ArtificialAnalysis/StirrupJS) is the Typescript implementation.
+
 ## Features
 
 - 🧪 **Code execution:** Run code locally, in Docker, or in an E2B sandbox

{stirrup-0.1.4 → stirrup-0.1.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stirrup"
-version = "0.1.4"
+version = "0.1.6"
 description = "The lightweight foundation for building agents"
 readme = "README.md"
 license = { file = "LICENSE" }

{stirrup-0.1.4 → stirrup-0.1.6}/src/stirrup/core/agent.py

@@ -65,6 +65,9 @@ class SessionState:
     - depth: Agent depth (0 = root, >0 = subagent)
     - output_dir: For root agent, this is a local filesystem path. For subagents,
       this is a path within the parent's exec env.
+    - exec_env_owned: Whether this session owns the exec_env and should clean it up.
+      When share_parent_exec_env=True, the subagent borrows the parent's exec_env
+      and exec_env_owned=False to prevent cleanup on subagent exit.
     """
 
     exit_stack: AsyncExitStack
@@ -72,6 +75,7 @@ class SessionState:
     output_dir: str | None = None  # String path (contextual: local for root, in parent env for subagent)
     parent_exec_env: CodeExecToolProvider | None = None
     depth: int = 0
+    exec_env_owned: bool = True  # Whether this session owns (and should cleanup) the exec_env
     uploaded_file_paths: list[str] = field(default_factory=list)  # Paths of files uploaded to exec_env
     skills_metadata: list[SkillMetadata] = field(default_factory=list)  # Loaded skills metadata
     logger: AgentLoggerBase | None = None  # Logger for pause/resume during user input
@@ -184,6 +188,8 @@ class Agent[FinishParams: BaseModel, FinishMeta]:
         turns_remaining_warning_threshold: int = TURNS_REMAINING_WARNING_THRESHOLD,
         run_sync_in_thread: bool = True,
         text_only_tool_responses: bool = True,
+        # Subagent options
+        share_parent_exec_env: bool = False,
         # Logging
         logger: AgentLoggerBase | None = None,
     ) -> None:
@@ -203,6 +209,11 @@ class Agent[FinishParams: BaseModel, FinishMeta]:
             context_summarization_cutoff: Fraction of context window (0-1) at which to trigger summarization
             run_sync_in_thread: Execute synchronous tool executors in a separate thread
             text_only_tool_responses: Extract images from tool responses as separate user messages
+            share_parent_exec_env: When True and used as a subagent, share the parent's code
+                                   execution environment instead of creating a new one. This
+                                   provides better performance (no file copying) and allows
+                                   the subagent to see all files in the parent's environment.
+                                   Only effective when the agent is used as a subagent via to_tool().
             logger: Optional logger instance. If None, creates AgentLogger() internally.
 
         """
@@ -224,6 +235,7 @@ class Agent[FinishParams: BaseModel, FinishMeta]:
         self._turns_remaining_warning_threshold = turns_remaining_warning_threshold
         self._run_sync_in_thread = run_sync_in_thread
         self._text_only_tool_responses = text_only_tool_responses
+        self._share_parent_exec_env = share_parent_exec_env
 
         # Logger (can be passed in or created here)
         self._logger: AgentLoggerBase = logger if logger is not None else AgentLogger()
@@ -572,22 +584,47 @@ class Agent[FinishParams: BaseModel, FinishMeta]:
             # (like ViewImageToolProvider) can access state.exec_env in second pass.
             active_tools: list[Tool] = []
 
-            # First pass: Initialize CodeExecToolProvider (at most one allowed)
-            code_exec_providers = [t for t in self._tools if isinstance(t, CodeExecToolProvider)]
-            if len(code_exec_providers) > 1:
-                raise ValueError(
-                    f"Agent can only have one CodeExecToolProvider, found {len(code_exec_providers)}: "
-                    f"{[type(p).__name__ for p in code_exec_providers]}"
+            # Check if we should share parent's exec_env (subagent with share_parent_exec_env=True)
+            should_share_exec_env = (
+                self._share_parent_exec_env
+                and current_depth > 0
+                and parent_state is not None
+                and parent_state.exec_env is not None
+            )
+
+            if should_share_exec_env:
+                # SHARED EXEC ENV: Use parent's exec_env directly, don't create new one
+                state.exec_env = parent_state.exec_env  # type: ignore[union-attr]
+                state.exec_env_owned = False
+                logger.debug(
+                    "[%s __aenter__] Sharing parent's exec_env: %s (temp_dir=%s)",
+                    self._name,
+                    type(state.exec_env).__name__,
+                    getattr(state.exec_env, "_temp_dir", "N/A"),
                 )
+                # Skip CodeExecToolProvider initialization but still need to add code exec tool
+                # Create the tool from the shared exec_env using get_code_exec_tool()
+                # (the exec_env is already entered by parent, so we just create the tool wrapper)
+                code_exec_tool = state.exec_env.get_code_exec_tool()
+                active_tools.append(code_exec_tool)
+            else:
+                # OWNED EXEC ENV: Initialize our own CodeExecToolProvider (at most one allowed)
+                code_exec_providers = [t for t in self._tools if isinstance(t, CodeExecToolProvider)]
+                if len(code_exec_providers) > 1:
+                    raise ValueError(
+                        f"Agent can only have one CodeExecToolProvider, found {len(code_exec_providers)}: "
+                        f"{[type(p).__name__ for p in code_exec_providers]}"
+                    )
 
-            if code_exec_providers:
-                provider = code_exec_providers[0]
-                result = await exit_stack.enter_async_context(provider)
-                if isinstance(result, list):
-                    active_tools.extend(result)
-                else:
-                    active_tools.append(result)
-                state.exec_env = provider
+                if code_exec_providers:
+                    provider = code_exec_providers[0]
+                    result = await exit_stack.enter_async_context(provider)
+                    if isinstance(result, list):
+                        active_tools.extend(result)
+                    else:
+                        active_tools.append(result)
+                    state.exec_env = provider
+                    state.exec_env_owned = True
 
             # Second pass: Initialize remaining ToolProviders and static Tools
             for tool in self._tools:
@@ -620,35 +657,57 @@ class Agent[FinishParams: BaseModel, FinishMeta]:
                     raise ValueError("input_files specified but no CodeExecToolProvider configured")
 
                 logger.debug(
-                    "[%s __aenter__] Uploading input files: %s, depth=%d, parent_exec_env=%s, parent_exec_env._temp_dir=%s",
+                    "[%s __aenter__] Uploading input files: %s, depth=%d, parent_exec_env=%s, parent_exec_env._temp_dir=%s, exec_env_owned=%s",
                     self._name,
                     self._pending_input_files,
                     state.depth,
                     type(state.parent_exec_env).__name__ if state.parent_exec_env else None,
                     getattr(state.parent_exec_env, "_temp_dir", "N/A") if state.parent_exec_env else None,
+                    state.exec_env_owned,
                 )
 
                 if state.depth > 0 and state.parent_exec_env:
-                    # SUBAGENT: Read files from parent's exec env, write to subagent's exec env
-                    # input_files are paths within the parent's environment
-                    result = await state.exec_env.upload_files(
-                        *self._pending_input_files,
-                        source_env=state.parent_exec_env,
-                    )
+                    if not state.exec_env_owned:
+                        # SHARED EXEC ENV: Files already accessible - no transfer needed
+                        # Just record the paths as "uploaded" for system prompt
+                        if isinstance(self._pending_input_files, (str, Path)):
+                            state.uploaded_file_paths = [str(self._pending_input_files)]
+                        else:
+                            state.uploaded_file_paths = [str(p) for p in self._pending_input_files]
+                        logger.debug(
+                            "[%s __aenter__] Shared exec_env - files already accessible: %s",
+                            self._name,
+                            state.uploaded_file_paths,
+                        )
+                    else:
+                        # SEPARATE EXEC ENV: Read files from parent's exec env, write to subagent's exec env
+                        # input_files are paths within the parent's environment
+                        result = await state.exec_env.upload_files(
+                            *self._pending_input_files,
+                            source_env=state.parent_exec_env,
+                        )
+                        logger.debug(
+                            "[%s __aenter__] Upload result: uploaded=%s, failed=%s",
+                            self._name,
+                            result.uploaded,
+                            result.failed,
+                        )
+                        state.uploaded_file_paths = [uf.dest_path for uf in result.uploaded]
+                        if result.failed:
+                            raise RuntimeError(f"Failed to upload files: {result.failed}")
                 else:
                     # ROOT AGENT: Read files from local filesystem
                     resolved = self._resolve_input_files(self._pending_input_files)
                     result = await state.exec_env.upload_files(*resolved)
-
-                logger.debug(
-                    "[%s __aenter__] Upload result: uploaded=%s, failed=%s", self._name, result.uploaded, result.failed
-                )
-
-                # Store uploaded paths for system prompt
-                state.uploaded_file_paths = [uf.dest_path for uf in result.uploaded]
-
-                if result.failed:
-                    raise RuntimeError(f"Failed to upload files: {result.failed}")
+                    logger.debug(
+                        "[%s __aenter__] Upload result: uploaded=%s, failed=%s",
+                        self._name,
+                        result.uploaded,
+                        result.failed,
+                    )
+                    state.uploaded_file_paths = [uf.dest_path for uf in result.uploaded]
+                    if result.failed:
+                        raise RuntimeError(f"Failed to upload files: {result.failed}")
             self._pending_input_files = None  # Clear pending state
 
             # Upload skills directory if it exists and load metadata
@@ -667,7 +726,8 @@ class Agent[FinishParams: BaseModel, FinishMeta]:
                 state.skills_metadata = parent_state.skills_metadata
                 logger.debug("[%s __aenter__] Inherited %d skills from parent", self._name, len(state.skills_metadata))
                 # Transfer skills directory from parent's exec_env to sub-agent's exec_env
-                if state.exec_env and parent_state.exec_env:
+                # (only if we have a separate exec_env)
+                if state.exec_env and parent_state.exec_env and state.exec_env_owned:
                     await state.exec_env.upload_files("skills", source_env=parent_state.exec_env)
 
             # Configure and enter logger context
@@ -767,8 +827,19 @@ class Agent[FinishParams: BaseModel, FinishMeta]:
                             len(result.failed),
                         )
                     else:
-                        # SUBAGENT: Transfer to parent's exec env
-                        if state.parent_exec_env:
+                        # SUBAGENT: Handle file transfer based on exec_env ownership
+                        if not state.exec_env_owned:
+                            # SHARED EXEC ENV: Files already in parent's env - no transfer needed
+                            # Just record the paths for reporting to parent
+                            self._transferred_paths = list(paths)
+                            logger.debug(
+                                "[%s] SUBAGENT (depth=%d, shared_exec_env): Files already in parent env: %s",
+                                self._name,
+                                state.depth,
+                                self._transferred_paths,
+                            )
+                        elif state.parent_exec_env:
+                            # SEPARATE EXEC ENV: Transfer to parent's exec env
                             logger.debug(
                                 "[%s] SUBAGENT (depth=%d): Transferring %d file(s) to parent exec env: %s -> %s",
                                 self._name,

{stirrup-0.1.4 → stirrup-0.1.6}/src/stirrup/tools/code_backends/base.py

@@ -245,6 +245,39 @@ class CodeExecToolProvider(ToolProvider, ABC):
         """
         ...
 
+    @abstractmethod
+    async def is_directory(self, path: str) -> bool:
+        """Check if a path is a directory in this execution environment.
+
+        Args:
+            path: Path within this execution environment.
+
+        Returns:
+            True if the path exists and is a directory, False otherwise.
+
+        Raises:
+            RuntimeError: If execution environment not started.
+
+        """
+        ...
+
+    @abstractmethod
+    async def list_files(self, path: str) -> list[str]:
+        """List all files recursively in a directory within this execution environment.
+
+        Args:
+            path: Directory path within this execution environment.
+
+        Returns:
+            List of file paths (relative to the given path) for all files in the directory.
+            Returns an empty list if the path is a file or doesn't exist.
+
+        Raises:
+            RuntimeError: If execution environment not started.
+
+        """
+        ...
+
     async def save_output_files(
         self,
         paths: list[str],
@@ -334,18 +367,44 @@ class CodeExecToolProvider(ToolProvider, ABC):
             try:
                 if source_env:
                     # Cross-environment transfer: read from source_env
-                    content = await source_env.read_file_bytes(path_str)
-                    filename = Path(path_str).name
-                    dest_path = f"{dest_dir_str}/{filename}" if dest_dir_str else filename
-                    logger.debug(
-                        "UPLOAD CROSS-ENV: %s (%d bytes) from %s -> %s",
-                        path_str,
-                        len(content),
-                        type(source_env).__name__,
-                        dest_path,
-                    )
-                    await self.write_file_bytes(dest_path, content)
-                    result.uploaded.append(UploadedFile(Path(path_str), dest_path, len(content)))
+                    # Check if it's a directory first
+                    if await source_env.is_directory(path_str):
+                        # Handle directory recursively
+                        # Preserve directory name when dest_dir not specified
+                        dir_name = Path(path_str).name
+                        files = await source_env.list_files(path_str)
+                        for rel_file_path in files:
+                            src_file_path = f"{path_str}/{rel_file_path}"
+                            # If dest_dir specified, put files directly there
+                            # Otherwise, preserve the source directory name
+                            if dest_dir_str:
+                                dest_path = f"{dest_dir_str}/{rel_file_path}"
+                            else:
+                                dest_path = f"{dir_name}/{rel_file_path}"
+                            content = await source_env.read_file_bytes(src_file_path)
+                            logger.debug(
+                                "UPLOAD CROSS-ENV (dir): %s (%d bytes) from %s -> %s",
+                                src_file_path,
+                                len(content),
+                                type(source_env).__name__,
+                                dest_path,
+                            )
+                            await self.write_file_bytes(dest_path, content)
+                            result.uploaded.append(UploadedFile(Path(src_file_path), dest_path, len(content)))
+                    else:
+                        # Single file transfer
+                        content = await source_env.read_file_bytes(path_str)
+                        filename = Path(path_str).name
+                        dest_path = f"{dest_dir_str}/{filename}" if dest_dir_str else filename
+                        logger.debug(
+                            "UPLOAD CROSS-ENV: %s (%d bytes) from %s -> %s",
+                            path_str,
+                            len(content),
+                            type(source_env).__name__,
+                            dest_path,
+                        )
+                        await self.write_file_bytes(dest_path, content)
+                        result.uploaded.append(UploadedFile(Path(path_str), dest_path, len(content)))
                 else:
                     # Local filesystem upload - must be handled by subclass
                     # This is a fallback that reads from local fs and writes to env

{stirrup-0.1.4 → stirrup-0.1.6}/src/stirrup/tools/code_backends/docker.py

@@ -3,6 +3,7 @@
 import contextlib
 import hashlib
 import os
+import shlex
 import shutil
 import tempfile
 from pathlib import Path
@@ -106,7 +107,7 @@ class DockerCodeExecToolProvider(CodeExecToolProvider):
         self._source = source
         self._is_dockerfile = is_dockerfile
         self._dockerfile_context = dockerfile_context
-        self._working_dir = working_dir
+        self._working_dir = working_dir.rstrip("/")
         self._temp_base_dir = temp_base_dir
         self._env_vars = env_vars
 
@@ -125,51 +126,6 @@ class DockerCodeExecToolProvider(CodeExecToolProvider):
         """Return the container short ID, or None if not started."""
         return self._container.short_id if self._container else None
 
-    def _resolve_file_path(self, path: str) -> Path:
-        """Resolve a container path string to a validated host file path.
-
-        Args:
-            path: Path to file (relative to working directory, or absolute container path).
-
-        Returns:
-            Resolved absolute host Path to the file.
-
-        Raises:
-            RuntimeError: If execution environment not started.
-            ValueError: If path is outside mounted directory or is not a file.
-            FileNotFoundError: If file does not exist.
-
-        """
-        if self._temp_dir is None:
-            raise RuntimeError("ExecutionEnvironment not started. Use 'async with exec_env.create()' first.")
-
-        file_path = Path(path)
-
-        # Handle both absolute container paths and relative paths
-        if file_path.is_absolute():
-            # Convert container absolute path to host path
-            # e.g., /workspace/image.png -> <temp_dir>/image.png
-            if str(file_path).startswith(self._working_dir):
-                relative = file_path.relative_to(self._working_dir)
-                file_path = self._temp_dir / relative
-            else:
-                raise ValueError(f"Path is outside mounted directory: {path}")
-        else:
-            file_path = self._temp_dir / file_path
-
-        # Security check: ensure path is within temp directory
-        try:
-            file_path.resolve().relative_to(self._temp_dir.resolve())
-        except ValueError:
-            raise ValueError(f"Path is outside execution environment directory: {path}") from None
-
-        if not file_path.exists():
-            raise FileNotFoundError(f"File not found: {path}")
-        if not file_path.is_file():
-            raise ValueError(f"Path is not a file: {path}")
-
-        return file_path
-
     @classmethod
     def from_image(
         cls,
@@ -379,6 +335,10 @@ class DockerCodeExecToolProvider(CodeExecToolProvider):
         exc_tb: object,
     ) -> None:
         """Stop container and cleanup temp directory."""
+        # Fix ownership of all files before cleanup (prevents permission errors on nested directories)
+        if self._container and self._temp_dir:
+            await self._fix_file_ownership()
+
         # Stop and remove container
         if self._container:
             container = self._container  # Capture for lambda type narrowing
@@ -408,10 +368,12 @@ class DockerCodeExecToolProvider(CodeExecToolProvider):
         self._temp_dir = None
 
     def _container_path_to_host(self, path: str) -> Path:
-        """Convert a container path to the corresponding host path.
+        """Convert a container or host path to the corresponding host path.
 
         Args:
-            path: Path in the container (relative or absolute).
+            path: Path to resolve. Can be relative to the container working directory,
+                an absolute container path (starting with working_dir), or an absolute
+                host path already within the temp directory.
 
         Returns:
             Resolved Path on the host filesystem.
@@ -426,11 +388,16 @@ class DockerCodeExecToolProvider(CodeExecToolProvider):
 
         source_path = Path(path)
 
-        # Handle both absolute container paths and relative paths
+        # Handle absolute host paths, absolute container paths, and relative paths
         if source_path.is_absolute():
-            # Convert container absolute path to host path
-            # e.g., /workspace/output.txt -> <temp_dir>/output.txt
-            if str(source_path).startswith(self._working_dir):
+            temp_dir_prefix = str(self._temp_dir) + os.sep
+            working_dir_prefix = self._working_dir + "/"
+            if str(source_path).startswith(temp_dir_prefix):
+                # Already a valid host path within the temp directory
+                host_path = source_path
+            elif str(source_path).startswith(working_dir_prefix):
+                # Convert container absolute path to host path
+                # e.g., /workspace/output.txt -> <temp_dir>/output.txt
                 relative = source_path.relative_to(self._working_dir)
                 host_path = self._temp_dir / relative
             else:
@@ -452,7 +419,7 @@ class DockerCodeExecToolProvider(CodeExecToolProvider):
         Since files are volume-mounted, reads directly from the host temp directory.
 
         Args:
-            path: File path (relative or absolute container path).
+            path: File path (relative, absolute container, or absolute host path).
 
         Returns:
             File contents as bytes.
@@ -474,7 +441,7 @@ class DockerCodeExecToolProvider(CodeExecToolProvider):
         Since files are volume-mounted, writes directly to the host temp directory.
 
         Args:
-            path: Destination path (relative or absolute container path).
+            path: Destination path (relative, absolute container, or absolute host path).
             content: File contents to write.
 
         Raises:
@@ -492,7 +459,7 @@ class DockerCodeExecToolProvider(CodeExecToolProvider):
         Since files are volume-mounted, checks directly on the host temp directory.
 
         Args:
-            path: File path (relative or absolute container path).
+            path: File path (relative, absolute container, or absolute host path).
 
         Returns:
             True if the file exists, False otherwise.
@@ -505,6 +472,53 @@ class DockerCodeExecToolProvider(CodeExecToolProvider):
         host_path = self._container_path_to_host(path)
         return host_path.exists() and host_path.is_file()
 
+    async def is_directory(self, path: str) -> bool:
+        """Check if a path is a directory in the container.
+
+        Since files are volume-mounted, checks directly on the host temp directory.
+
+        Args:
+            path: Path (relative, absolute container, or absolute host path).
+
+        Returns:
+            True if the path exists and is a directory, False otherwise.
+
+        Raises:
+            RuntimeError: If environment not started.
+            ValueError: If path is outside mounted directory.
+
+        """
+        host_path = self._container_path_to_host(path)
+        return host_path.exists() and host_path.is_dir()
+
+    async def list_files(self, path: str) -> list[str]:
+        """List all files recursively in a directory within the container.
+
+        Since files are volume-mounted, lists directly from the host temp directory.
+
+        Args:
+            path: Directory path (relative, absolute container, or absolute host path).
+
+        Returns:
+            List of file paths (relative to the given path) for all files in the directory.
+            Returns an empty list if the path is a file or doesn't exist.
+
+        Raises:
+            RuntimeError: If environment not started.
+            ValueError: If path is outside mounted directory.
+
+        """
+        host_path = self._container_path_to_host(path)
+        if not host_path.exists() or not host_path.is_dir():
+            return []
+
+        files = []
+        for file_path in host_path.rglob("*"):
+            if file_path.is_file():
+                rel_path = file_path.relative_to(host_path)
+                files.append(str(rel_path))
+        return files
+
     async def run_command(self, cmd: str, *, timeout: int = SHELL_TIMEOUT) -> CommandResult:
         """Execute a shell command in the Docker container.
 
@@ -576,6 +590,42 @@ class DockerCodeExecToolProvider(CodeExecToolProvider):
                 error_kind="execution_error",
             )
 
+    async def _fix_file_ownership(self, paths: list[str] | None = None) -> None:
+        """Fix ownership of files created by the container.
+
+        Files and directories created inside the Docker container run as root,
+        which causes permission issues when trying to move/delete them from the host.
+        This method runs chown inside the container to fix ownership.
+
+        Args:
+            paths: Specific paths to fix. If None, fixes all files in working_dir.
+                   Paths should be container paths (absolute or relative to working_dir).
+        """
+        if self._container is None:
+            return
+
+        try:
+            # Get the host user ID to chown to
+            host_uid = os.getuid()
+            host_gid = os.getgid()
+
+            if paths:
+                # Normalize paths - handle both relative and absolute
+                container_paths = [
+                    f"{self._working_dir}/{path}" if not path.startswith("/") else path for path in paths
+                ]
+                quoted_paths = " ".join(shlex.quote(p) for p in container_paths)
+                chown_cmd = f"chown -R {host_uid}:{host_gid} {quoted_paths} 2>/dev/null || true"
+                await self.run_command(chown_cmd, timeout=10)
+            else:
+                # Fix all files in working directory
+                chown_cmd = f"chown -R {host_uid}:{host_gid} {shlex.quote(self._working_dir)} 2>/dev/null || true"
+                await self.run_command(chown_cmd, timeout=10)
+
+        except Exception as exc:
+            # Don't fail the operation if chown fails, just log warning
+            logger.warning("Failed to fix file ownership: %s", exc)
+
     async def save_output_files(
         self,
         paths: list[str],
@@ -594,9 +644,11 @@ class DockerCodeExecToolProvider(CodeExecToolProvider):
         using the base class implementation via read/write primitives.
 
         Args:
-            paths: List of file paths in the execution environment (relative or absolute container paths).
-                   Relative paths are resolved against the container working directory.
-                   Absolute container paths starting with working_dir are mapped to the host.
+            paths: List of file paths in the execution environment (relative, absolute container,
+                   or absolute host paths). Relative paths are resolved against the container
+                   working directory. Absolute container paths starting with working_dir are
+                   mapped to the host. Absolute host paths within the temp directory are
+                   accepted as-is.
             output_dir: Directory path to save files to.
             dest_env: If provided, output_dir is interpreted as a path within dest_env
                       (cross-environment transfer). If None, output_dir is a local
@@ -615,6 +667,9 @@ class DockerCodeExecToolProvider(CodeExecToolProvider):
         if dest_env is not None:
             return await super().save_output_files(paths, output_dir, dest_env)
 
+        # Fix ownership of files before moving them (solves permission issues with nested directories)
+        await self._fix_file_ownership(paths)
+
         # Local filesystem - use optimized move operation
         output_dir_path = Path(output_dir)
         output_dir_path.mkdir(parents=True, exist_ok=True)
@@ -768,7 +823,7 @@ class DockerCodeExecToolProvider(CodeExecToolProvider):
         """Read and return an image file from the Docker execution environment.
 
         Args:
-            path: Path to image file (relative to working directory, or absolute container path).
+            path: Path to image file (relative, absolute container, or absolute host path).
 
         Returns:
             ImageContentBlock containing the image data.

{stirrup-0.1.4 → stirrup-0.1.6}/src/stirrup/tools/code_backends/e2b.py

@@ -150,6 +150,68 @@ class E2BCodeExecToolProvider(CodeExecToolProvider):
 
         return await self._sbx.files.exists(path)
 
+    async def is_directory(self, path: str) -> bool:
+        """Check if a path is a directory in the E2B sandbox.
+
+        Args:
+            path: Path within the sandbox.
+
+        Returns:
+            True if the path exists and is a directory, False otherwise.
+
+        Raises:
+            RuntimeError: If environment not started.
+
+        """
+        if self._sbx is None:
+            raise RuntimeError("ExecutionEnvironment not started.")
+
+        if not await self._sbx.files.exists(path):
+            return False
+
+        info = await self._sbx.files.get_info(path)
+        return info.type == FileType.DIR
+
+    async def list_files(self, path: str) -> list[str]:
+        """List all files recursively in a directory within the E2B sandbox.
+
+        Args:
+            path: Directory path within the sandbox.
+
+        Returns:
+            List of file paths (relative to the given path) for all files in the directory.
+            Returns an empty list if the path is a file or doesn't exist.
+
+        Raises:
+            RuntimeError: If environment not started.
+
+        """
+        if self._sbx is None:
+            raise RuntimeError("ExecutionEnvironment not started.")
+
+        if not await self._sbx.files.exists(path):
+            return []
+
+        info = await self._sbx.files.get_info(path)
+        if info.type != FileType.DIR:
+            return []
+
+        # Use find command to list all files recursively
+        result = await self.run_command(f"find {path} -type f")
+        if result.exit_code != 0:
+            return []
+
+        files = []
+        for line in result.stdout.strip().split("\n"):
+            if line:
+                # Convert absolute path to relative path
+                rel_path = line.removeprefix(f"{path}/").removeprefix(path)
+                if rel_path.startswith("/"):
+                    rel_path = rel_path[1:]
+                if rel_path:
+                    files.append(rel_path)
+        return files
+
     async def run_command(self, cmd: str, *, timeout: int = SHELL_TIMEOUT) -> CommandResult:
         """Execute command in E2B execution environment, returning raw CommandResult."""
         if self._sbx is None:

{stirrup-0.1.4 → stirrup-0.1.6}/src/stirrup/tools/code_backends/local.py

@@ -222,6 +222,49 @@ class LocalCodeExecToolProvider(CodeExecToolProvider):
         resolved = self._resolve_and_validate_path(path)
         return resolved.exists() and resolved.is_file()
 
+    async def is_directory(self, path: str) -> bool:
+        """Check if a path is a directory in the temp directory.
+
+        Args:
+            path: Path (relative or absolute within the temp dir).
+
+        Returns:
+            True if the path exists and is a directory, False otherwise.
+
+        Raises:
+            RuntimeError: If environment not started.
+            ValueError: If path is outside temp directory.
+
+        """
+        resolved = self._resolve_and_validate_path(path)
+        return resolved.exists() and resolved.is_dir()
+
+    async def list_files(self, path: str) -> list[str]:
+        """List all files recursively in a directory within the temp directory.
+
+        Args:
+            path: Directory path (relative or absolute within the temp dir).
+
+        Returns:
+            List of file paths (relative to the given path) for all files in the directory.
+            Returns an empty list if the path is a file or doesn't exist.
+
+        Raises:
+            RuntimeError: If environment not started.
+            ValueError: If path is outside temp directory.
+
+        """
+        resolved = self._resolve_and_validate_path(path)
+        if not resolved.exists() or not resolved.is_dir():
+            return []
+
+        files = []
+        for file_path in resolved.rglob("*"):
+            if file_path.is_file():
+                rel_path = file_path.relative_to(resolved)
+                files.append(str(rel_path))
+        return files
+
     async def run_command(self, cmd: str, *, timeout: int = SHELL_TIMEOUT) -> CommandResult:
         """Execute command in the temp directory.