Class ShellTool

src/agents/tool.py:1216–1260

Next-generation shell tool. LocalShellTool will be deprecated in favor of this.

@dataclass
class ShellTool:
    """Next-generation shell tool. LocalShellTool will be deprecated in favor of this."""

    executor: ShellExecutor | None = None
    name: str = "shell"
    needs_approval: bool | ShellApprovalFunction = False
    """Whether the shell tool needs approval before execution. If True, the run will be interrupted
    and the tool call will need to be approved using RunState.approve() or rejected using
    RunState.reject() before continuing. Can be a bool (always/never needs approval) or a
    function that takes (run_context, action, call_id) and returns whether this specific call
    needs approval.
    """
    on_approval: ShellOnApprovalFunction | None = None
    """Optional handler to auto-approve or reject when approval is required.
    If provided, it will be invoked immediately when an approval is needed.
    """
    environment: ShellToolEnvironment | None = None
    """Execution environment for shell commands.

    If omitted, local mode is used.
    """

    def __post_init__(self) -> None:
        """Validate shell tool configuration and normalize environment fields."""
        normalized_environment = _normalize_shell_tool_environment(self.environment)
        self.environment = normalized_environment

        environment_type = normalized_environment["type"]
        if environment_type == "local":
            if self.executor is None:
                raise UserError("ShellTool with local environment requires an executor.")
            return

        if self.executor is not None:
            raise UserError("ShellTool with hosted environment does not accept an executor.")
        if self.needs_approval is not False or self.on_approval is not None:
            raise UserError(
                "ShellTool with hosted environment does not support needs_approval or on_approval."
            )
        self.needs_approval = False
        self.on_approval = None

    @property
    def type(self) -> str:
        return "shell"


@dataclass