gobby 0.2.5__py3-none-any.whl → 0.2.7__py3-none-any.whl

gobby/agents/sandbox.py

@@ -0,0 +1,261 @@
+"""
+Sandbox Configuration Models.
+
+This module defines configuration models for sandbox/isolation settings
+when spawning agents. The actual sandboxing is handled by each CLI's
+built-in sandbox implementation - Gobby just passes the right flags.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class SandboxConfig(BaseModel):
+    """
+    Configuration for sandbox/isolation when spawning agents.
+
+    This is opt-in - by default sandboxing is disabled to preserve
+    existing behavior. When enabled, the appropriate CLI flags are
+    passed to enable the CLI's built-in sandbox.
+
+    Attributes:
+        enabled: Whether to enable sandboxing. Default False.
+        mode: Sandbox strictness level.
+            - "permissive": Allow more operations (easier debugging)
+            - "restrictive": Stricter isolation (more secure)
+        allow_network: Whether to allow network access (except localhost:60887
+            which is always allowed for Gobby daemon communication).
+        extra_read_paths: Additional paths to allow read access.
+        extra_write_paths: Additional paths to allow write access
+            (worktree paths are always allowed).
+    """
+
+    enabled: bool = False
+    mode: Literal["permissive", "restrictive"] = "permissive"
+    allow_network: bool = True
+    extra_read_paths: list[str] = Field(default_factory=list)
+    extra_write_paths: list[str] = Field(default_factory=list)
+
+
+class ResolvedSandboxPaths(BaseModel):
+    """
+    Resolved paths and settings for sandbox execution.
+
+    This is the computed result after resolving a SandboxConfig against
+    the actual workspace and daemon configuration. It contains the concrete
+    paths and settings that will be passed to CLI sandbox flags.
+
+    Attributes:
+        workspace_path: The primary workspace/worktree path for the agent.
+        gobby_daemon_port: Port where Gobby daemon is running (for network allowlist).
+        read_paths: All paths the sandbox should allow read access to.
+        write_paths: All paths the sandbox should allow write access to.
+        allow_external_network: Whether to allow network access beyond localhost.
+    """
+
+    workspace_path: str
+    gobby_daemon_port: int = 60887
+    read_paths: list[str]
+    write_paths: list[str]
+    allow_external_network: bool
+
+
+class SandboxResolver(ABC):
+    """
+    Abstract base class for CLI-specific sandbox configuration resolution.
+
+    Each CLI (Claude Code, Codex, Gemini) has different mechanisms for
+    enabling sandboxing. Subclasses implement the resolve() method to
+    convert a SandboxConfig and ResolvedSandboxPaths into CLI-specific
+    arguments and environment variables.
+    """
+
+    @property
+    @abstractmethod
+    def cli_name(self) -> str:
+        """Return the name of the CLI this resolver handles."""
+        ...
+
+    @abstractmethod
+    def resolve(
+        self, config: SandboxConfig, paths: ResolvedSandboxPaths
+    ) -> tuple[list[str], dict[str, str]]:
+        """
+        Resolve sandbox configuration to CLI-specific args and env vars.
+
+        Args:
+            config: The sandbox configuration from the agent definition.
+            paths: The resolved paths for the sandbox environment.
+
+        Returns:
+            A tuple of (cli_args, env_vars) where:
+            - cli_args: List of command-line arguments to pass to the CLI
+            - env_vars: Dict of environment variables to set
+        """
+        ...
+
+
+class ClaudeSandboxResolver(SandboxResolver):
+    """
+    Sandbox resolver for Claude Code CLI.
+
+    Claude Code uses --settings with a JSON object containing sandbox config.
+    See: https://code.claude.com/docs/en/sandboxing
+    """
+
+    @property
+    def cli_name(self) -> str:
+        return "claude"
+
+    def resolve(
+        self, config: SandboxConfig, paths: ResolvedSandboxPaths
+    ) -> tuple[list[str], dict[str, str]]:
+        if not config.enabled:
+            return ([], {})
+
+        import json
+
+        # Build settings JSON for Claude Code
+        settings = {
+            "sandbox": {
+                "enabled": True,
+                "autoAllowBashIfSandboxed": True,
+                # Network config - allow localhost for Gobby daemon
+                "network": {
+                    "allowLocalBinding": True,
+                },
+            }
+        }
+
+        return (["--settings", json.dumps(settings)], {})
+
+
+class CodexSandboxResolver(SandboxResolver):
+    """
+    Sandbox resolver for OpenAI Codex CLI.
+
+    Codex uses --sandbox flag with mode (read-only, workspace-write, danger-full-access)
+    and --add-dir for additional writable paths.
+    See: https://developers.openai.com/codex/cli/reference/
+    """
+
+    @property
+    def cli_name(self) -> str:
+        return "codex"
+
+    def resolve(
+        self, config: SandboxConfig, paths: ResolvedSandboxPaths
+    ) -> tuple[list[str], dict[str, str]]:
+        if not config.enabled:
+            return ([], {})
+
+        args: list[str] = []
+
+        # Sandbox mode
+        if config.mode == "restrictive":
+            args.extend(["--sandbox", "read-only"])
+        else:
+            args.extend(["--sandbox", "workspace-write"])
+
+        # Add extra write paths (workspace is implicit in workspace-write mode)
+        for path in paths.write_paths:
+            if path != paths.workspace_path:
+                args.extend(["--add-dir", path])
+
+        return (args, {})
+
+
+class GeminiSandboxResolver(SandboxResolver):
+    """
+    Sandbox resolver for Google Gemini CLI.
+
+    Gemini uses -s/--sandbox flag and SEATBELT_PROFILE env var for macOS.
+    See: https://geminicli.com/docs/cli/sandbox/
+    """
+
+    @property
+    def cli_name(self) -> str:
+        return "gemini"
+
+    def resolve(
+        self, config: SandboxConfig, paths: ResolvedSandboxPaths
+    ) -> tuple[list[str], dict[str, str]]:
+        if not config.enabled:
+            return ([], {})
+
+        args = ["-s"]
+        env: dict[str, str] = {}
+
+        # Set SEATBELT_PROFILE based on mode (macOS)
+        if config.mode == "restrictive":
+            env["SEATBELT_PROFILE"] = "restrictive-closed"
+        else:
+            env["SEATBELT_PROFILE"] = "permissive-open"
+
+        return (args, env)
+
+
+def get_sandbox_resolver(cli: str) -> SandboxResolver:
+    """
+    Factory function to get the appropriate sandbox resolver for a CLI.
+
+    Args:
+        cli: The CLI name ("claude", "codex", or "gemini")
+
+    Returns:
+        The appropriate SandboxResolver subclass instance.
+
+    Raises:
+        ValueError: If the CLI is not recognized.
+    """
+    resolvers: dict[str, type[SandboxResolver]] = {
+        "claude": ClaudeSandboxResolver,
+        "codex": CodexSandboxResolver,
+        "gemini": GeminiSandboxResolver,
+    }
+
+    if cli not in resolvers:
+        raise ValueError(f"Unknown CLI: {cli}. Must be one of: {list(resolvers.keys())}")
+
+    return resolvers[cli]()
+
+
+def compute_sandbox_paths(
+    config: SandboxConfig,
+    workspace_path: str,
+    gobby_daemon_port: int = 60887,
+) -> ResolvedSandboxPaths:
+    """
+    Compute resolved sandbox paths from a SandboxConfig.
+
+    This helper function combines the workspace path with extra paths
+    from the config to produce the final ResolvedSandboxPaths.
+
+    Args:
+        config: The sandbox configuration.
+        workspace_path: The primary workspace/worktree path.
+        gobby_daemon_port: Port where Gobby daemon is running.
+
+    Returns:
+        ResolvedSandboxPaths with all paths computed.
+    """
+    # Start with workspace in write paths
+    write_paths = [workspace_path]
+
+    # Add extra write paths
+    for path in config.extra_write_paths:
+        if path not in write_paths:
+            write_paths.append(path)
+
+    # Collect read paths
+    read_paths = list(config.extra_read_paths)
+
+    return ResolvedSandboxPaths(
+        workspace_path=workspace_path,
+        gobby_daemon_port=gobby_daemon_port,
+        read_paths=read_paths,
+        write_paths=write_paths,
+        allow_external_network=config.allow_network,
+    )

gobby/agents/spawn.py

@@ -1,17 +1,25 @@
-"""Terminal spawning for agent execution."""
+"""Terminal spawning for agent execution.
+
+This module provides the TerminalSpawner orchestrator and PreparedSpawn helpers
+for spawning CLI agents in terminal windows.
+
+Implementation is split across submodules:
+- spawners/prompt_manager.py: Prompt file creation and cleanup
+- spawners/command_builder.py: CLI command construction
+- spawners/: Platform-specific terminal spawners
+"""
 
 from __future__ import annotations
 
-import atexit
 import logging
-import os
-import tempfile
 from dataclasses import dataclass
 from pathlib import Path
 
 from gobby.agents.constants import get_terminal_env_vars
+from gobby.agents.sandbox import SandboxConfig, compute_sandbox_paths, get_sandbox_resolver
 from gobby.agents.session import ChildSessionConfig, ChildSessionManager
 from gobby.agents.spawners import (
+    MAX_ENV_PROMPT_LENGTH,
     AlacrittySpawner,
     CmdSpawner,
     EmbeddedSpawner,
@@ -30,6 +38,11 @@ from gobby.agents.spawners import (
     TmuxSpawner,
     WindowsTerminalSpawner,
     WSLSpawner,
+    build_cli_command,
+    build_codex_command_with_resume,
+    build_gemini_command_with_resume,
+    create_prompt_file,
+    read_prompt_from_env,
 )
 from gobby.agents.spawners.base import EmbeddedPTYResult, HeadlessResult
 from gobby.agents.tty_config import get_tty_config
@@ -71,161 +84,12 @@ __all__ = [
     "build_cli_command",
     "build_gemini_command_with_resume",
     "build_codex_command_with_resume",
+    "create_prompt_file",
     "MAX_ENV_PROMPT_LENGTH",
 ]
 
-# Maximum prompt length to pass via environment variable
-# Longer prompts will be written to a temp file
-MAX_ENV_PROMPT_LENGTH = 4096
-
 logger = logging.getLogger(__name__)
 
-# Module-level set for tracking prompt files to clean up on exit
-# This avoids registering a new atexit handler for each prompt file
-_prompt_files_to_cleanup: set[Path] = set()
-_atexit_registered = False
-
-
-def _cleanup_all_prompt_files() -> None:
-    """Clean up all tracked prompt files on process exit."""
-    for prompt_path in list(_prompt_files_to_cleanup):
-        try:
-            if prompt_path.exists():
-                prompt_path.unlink()
-        except OSError:
-            pass
-    _prompt_files_to_cleanup.clear()
-
-
-def _create_prompt_file(prompt: str, session_id: str) -> str:
-    """
-    Create a prompt file with secure permissions.
-
-    The file is created in the system temp directory with restrictive
-    permissions (owner read/write only) and tracked for cleanup on exit.
-
-    Args:
-        prompt: The prompt content to write
-        session_id: Session ID for naming the file
-
-    Returns:
-        Path to the created temp file
-    """
-    global _atexit_registered
-
-    # Create temp directory with restrictive permissions
-    temp_dir = Path(tempfile.gettempdir()) / "gobby-prompts"
-    temp_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
-
-    # Create the prompt file path
-    prompt_path = temp_dir / f"prompt-{session_id}.txt"
-
-    # Write with secure permissions atomically - create with mode 0o600 from the start
-    # This avoids the TOCTOU window between write_text and chmod
-    fd = os.open(str(prompt_path), os.O_CREAT | os.O_WRONLY | os.O_TRUNC, 0o600)
-    try:
-        with os.fdopen(fd, "w", encoding="utf-8") as f:
-            f.write(prompt)
-            f.flush()
-            os.fsync(f.fileno())
-    except Exception:
-        # fd is closed by fdopen, but if fdopen fails we need to close it
-        try:
-            os.close(fd)
-        except OSError:
-            pass
-        raise
-
-    # Track for cleanup
-    _prompt_files_to_cleanup.add(prompt_path)
-
-    # Register cleanup handler once
-    if not _atexit_registered:
-        atexit.register(_cleanup_all_prompt_files)
-        _atexit_registered = True
-
-    logger.debug(f"Created secure prompt file: {prompt_path}")
-    return str(prompt_path)
-
-
-def build_cli_command(
-    cli: str,
-    prompt: str | None = None,
-    session_id: str | None = None,
-    auto_approve: bool = False,
-    working_directory: str | None = None,
-    mode: str = "terminal",
-) -> list[str]:
-    """
-    Build the CLI command with proper prompt passing and permission flags.
-
-    Each CLI has different syntax for passing prompts and handling permissions:
-
-    Claude Code:
-    - claude --session-id <uuid> --dangerously-skip-permissions [prompt]
-    - Use --dangerously-skip-permissions for autonomous subagent operation
-
-    Gemini CLI:
-    - gemini -i "prompt" (interactive mode with initial prompt)
-    - gemini --approval-mode yolo -i "prompt" (YOLO + interactive)
-    - gemini "prompt" (one-shot non-interactive for headless)
-
-    Codex CLI:
-    - codex --full-auto -C <dir> [PROMPT]
-    - Or: codex -c 'sandbox_permissions=["disk-full-read-access"]' -a never [PROMPT]
-
-    Args:
-        cli: CLI name (claude, gemini, codex)
-        prompt: Optional prompt to pass
-        session_id: Optional session ID (used by Claude CLI)
-        auto_approve: If True, add flags to auto-approve actions/permissions
-        working_directory: Optional working directory (used by Codex -C flag)
-        mode: Execution mode - "terminal" (interactive) or "headless" (non-interactive)
-
-    Returns:
-        Command list for subprocess execution
-    """
-    command = [cli]
-
-    if cli == "claude":
-        # Claude CLI flags
-        if session_id:
-            command.extend(["--session-id", session_id])
-        if auto_approve:
-            # Skip all permission prompts for autonomous subagent operation
-            command.append("--dangerously-skip-permissions")
-        if prompt:
-            # Use -p (print mode) for non-interactive execution.
-            # NOTE: Print mode bypasses hooks - headless spawner manually tracks status.
-            command.append("-p")
-
-    elif cli == "gemini":
-        # Gemini CLI flags
-        if auto_approve:
-            command.extend(["--approval-mode", "yolo"])
-        # For terminal mode, use -i (prompt-interactive) to execute prompt and stay interactive
-        # For headless mode, use positional prompt for one-shot execution
-        if prompt:
-            if mode == "terminal":
-                command.extend(["-i", prompt])
-                return command  # Don't add prompt again as positional
-            # else: fall through to add as positional for headless
-
-    elif cli == "codex":
-        # Codex CLI flags
-        if auto_approve:
-            # --full-auto: low-friction sandboxed automatic execution
-            command.append("--full-auto")
-        if working_directory:
-            command.extend(["-C", working_directory])
-
-    # All three CLIs accept prompt as positional argument (must come last)
-    # For Gemini terminal mode, this is skipped (handled above with -i flag)
-    if prompt:
-        command.append(prompt)
-
-    return command
-
 
 class TerminalSpawner:
     """
@@ -369,6 +233,7 @@ class TerminalSpawner:
         max_agent_depth: int = 3,
         terminal: TerminalType | str = TerminalType.AUTO,
         prompt: str | None = None,
+        sandbox_config: SandboxConfig | None = None,
     ) -> SpawnResult:
         """
         Spawn a CLI agent in a new terminal with Gobby environment variables.
@@ -385,10 +250,22 @@ class TerminalSpawner:
             max_agent_depth: Maximum allowed depth
             terminal: Terminal type or "auto"
             prompt: Optional initial prompt
+            sandbox_config: Optional sandbox configuration
 
         Returns:
             SpawnResult with success status
         """
+        # Resolve sandbox configuration if enabled
+        sandbox_args: list[str] | None = None
+        sandbox_env: dict[str, str] = {}
+
+        if sandbox_config and sandbox_config.enabled:
+            # Compute sandbox paths based on cwd (workspace)
+            resolved_paths = compute_sandbox_paths(sandbox_config, str(cwd))
+            # Get CLI-specific resolver and generate args/env
+            resolver = get_sandbox_resolver(cli)
+            sandbox_args, sandbox_env = resolver.resolve(sandbox_config, resolved_paths)
+
         # Build command with prompt as CLI argument and auto-approve for autonomous work
         command = build_cli_command(
             cli,
@@ -397,6 +274,7 @@ class TerminalSpawner:
             auto_approve=True,  # Subagents need to work autonomously
             working_directory=str(cwd) if cli == "codex" else None,
             mode="terminal",  # Interactive terminal mode
+            sandbox_args=sandbox_args,
         )
 
         # Handle prompt for environment variables (backup for hooks/context)
@@ -422,6 +300,10 @@ class TerminalSpawner:
             prompt_file=prompt_file,
         )
 
+        # Merge sandbox environment variables if present
+        if sandbox_env:
+            env.update(sandbox_env)
+
         # Set title (avoid colons/parentheses which Ghostty interprets as config syntax)
         title = f"gobby-{cli}-d{agent_depth}"
 
@@ -437,8 +319,8 @@ class TerminalSpawner:
         """
         Write prompt to a temp file for passing to spawned agent.
 
-        Delegates to the module-level _create_prompt_file helper which
-        handles secure permissions and cleanup tracking.
+        Delegates to the create_prompt_file helper which handles
+        secure permissions and cleanup tracking.
 
         Args:
             prompt: The prompt content
@@ -447,7 +329,7 @@ class TerminalSpawner:
         Returns:
             Path to the created temp file
         """
-        return _create_prompt_file(prompt, session_id)
+        return create_prompt_file(prompt, session_id)
 
 
 @dataclass
@@ -545,7 +427,7 @@ def prepare_terminal_spawn(
             prompt_env = prompt
         else:
             # Write to temp file with secure permissions
-            prompt_file = _create_prompt_file(prompt, child_session.id)
+            prompt_file = create_prompt_file(prompt, child_session.id)
 
     # Build environment variables
     env_vars = get_terminal_env_vars(
@@ -571,34 +453,6 @@ def prepare_terminal_spawn(
     )
 
 
-def read_prompt_from_env() -> str | None:
-    """
-    Read initial prompt from environment variables.
-
-    Checks GOBBY_PROMPT_FILE first (for long prompts),
-    then falls back to GOBBY_PROMPT (for short prompts).
-
-    Returns:
-        Prompt string or None if not set
-    """
-    from gobby.agents.constants import GOBBY_PROMPT, GOBBY_PROMPT_FILE
-
-    # Check for prompt file first
-    prompt_file = os.environ.get(GOBBY_PROMPT_FILE)
-    if prompt_file:
-        try:
-            prompt_path = Path(prompt_file)
-            if prompt_path.exists():
-                return prompt_path.read_text(encoding="utf-8")
-            else:
-                logger.warning(f"Prompt file not found: {prompt_file}")
-        except Exception as e:
-            logger.error(f"Error reading prompt file: {e}")
-
-    # Fall back to inline prompt
-    return os.environ.get(GOBBY_PROMPT)
-
-
 async def prepare_gemini_spawn_with_preflight(
     session_manager: ChildSessionManager,
     parent_session_id: str,
@@ -677,7 +531,7 @@ async def prepare_gemini_spawn_with_preflight(
         if len(prompt) <= MAX_ENV_PROMPT_LENGTH:
             prompt_env = prompt
         else:
-            prompt_file = _create_prompt_file(prompt, child_session.id)
+            prompt_file = create_prompt_file(prompt, child_session.id)
 
     # Build environment variables
     env_vars = get_terminal_env_vars(
@@ -708,57 +562,6 @@ async def prepare_gemini_spawn_with_preflight(
     )
 
 
-def build_gemini_command_with_resume(
-    gemini_external_id: str,
-    prompt: str | None = None,
-    auto_approve: bool = False,
-    gobby_session_id: str | None = None,
-) -> list[str]:
-    """
-    Build Gemini CLI command with session resume.
-
-    Uses -r flag to resume a preflight-captured session, with session context
-    injected into the initial prompt.
-
-    Args:
-        gemini_external_id: Gemini's session_id from preflight capture
-        prompt: Optional user prompt
-        auto_approve: If True, add --approval-mode yolo
-        gobby_session_id: Gobby session ID to inject into context
-
-    Returns:
-        Command list for subprocess execution
-    """
-    command = ["gemini"]
-
-    # Resume the preflight session
-    command.extend(["-r", gemini_external_id])
-
-    if auto_approve:
-        command.extend(["--approval-mode", "yolo"])
-
-    # Build prompt with session context
-    if gobby_session_id:
-        context_prefix = (
-            f"Your Gobby session_id is: {gobby_session_id}\n"
-            f"Use this when calling Gobby MCP tools.\n\n"
-        )
-        full_prompt = context_prefix + (prompt or "")
-    else:
-        full_prompt = prompt or ""
-
-    # Use -i for interactive mode with initial prompt
-    if full_prompt:
-        command.extend(["-i", full_prompt])
-
-    return command
-
-
-# =============================================================================
-# Codex Preflight Capture
-# =============================================================================
-
-
 async def prepare_codex_spawn_with_preflight(
     session_manager: ChildSessionManager,
     parent_session_id: str,
@@ -837,7 +640,7 @@ async def prepare_codex_spawn_with_preflight(
         if len(prompt) <= MAX_ENV_PROMPT_LENGTH:
             prompt_env = prompt
         else:
-            prompt_file = _create_prompt_file(prompt, child_session.id)
+            prompt_file = create_prompt_file(prompt, child_session.id)
 
     # Build environment variables
     env_vars = get_terminal_env_vars(
@@ -866,51 +669,3 @@ async def prepare_codex_spawn_with_preflight(
         agent_depth=child_session.agent_depth,
         env_vars=env_vars,
     )
-
-
-def build_codex_command_with_resume(
-    codex_external_id: str,
-    prompt: str | None = None,
-    auto_approve: bool = False,
-    gobby_session_id: str | None = None,
-    working_directory: str | None = None,
-) -> list[str]:
-    """
-    Build Codex CLI command with session resume.
-
-    Uses `codex resume {session_id}` to resume a preflight-captured session,
-    with session context injected into the prompt.
-
-    Args:
-        codex_external_id: Codex's session_id from preflight capture
-        prompt: Optional user prompt
-        auto_approve: If True, add --full-auto flag
-        gobby_session_id: Gobby session ID to inject into context
-        working_directory: Optional working directory override
-
-    Returns:
-        Command list for subprocess execution
-    """
-    command = ["codex", "resume", codex_external_id]
-
-    if auto_approve:
-        command.append("--full-auto")
-
-    if working_directory:
-        command.extend(["-C", working_directory])
-
-    # Build prompt with session context
-    if gobby_session_id:
-        context_prefix = (
-            f"Your Gobby session_id is: {gobby_session_id}\n"
-            f"Use this when calling Gobby MCP tools.\n\n"
-        )
-        full_prompt = context_prefix + (prompt or "")
-    else:
-        full_prompt = prompt or ""
-
-    # Prompt is a positional argument after session_id
-    if full_prompt:
-        command.append(full_prompt)
-
-    return command