🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org
Python agentai-societiesartificial-intelligencecommunicative-aicooperative-aideep-learninglarge-language-modelsmulti-agent-systemsnatural-language-processing
feat(toolkits): add optional terminal command and input approval (#4130)
Ayush Shekhar7170ded20e0e
diff --git a/camel/toolkits/terminal_toolkit/terminal_toolkit.py b/camel/toolkits/terminal_toolkit/terminal_toolkit.pyindex 486fcc3d2..5aca42bf5 100644--- a/camel/toolkits/terminal_toolkit/terminal_toolkit.py+++ b/camel/toolkits/terminal_toolkit/terminal_toolkit.py@@ -21,7 +21,7 @@ import threadingimport timeimport uuidfrom queue import Empty, Full, Queue-from typing import Any, Dict, List, Optional+from typing import Any, Callable, Dict, List, Optionalfrom camel.logger import get_loggerfrom camel.toolkits import manual_timeout@@ -66,6 +66,27 @@ def _to_plain(text: str) -> str:return text+def _default_console_approval(command: str) -> bool:+ r"""Ask for approval in a terminal; deny non-interactive input.++ Args:+ command (str): The command or process input requesting approval.++ Returns:+ bool: Whether the user explicitly approved the input.+ """+ if sys.stdin is None or not sys.stdin.isatty():+ return False+ try:+ response = input(+ f"\n[TerminalToolkit] Approve command or process input:\n"+ f" {command}\nApprove? (y/N): "+ )+ return response.strip().lower() in ("y", "yes")+ except EOFError:+ return False++@MCPServer()class TerminalToolkit(BaseToolkit):r"""A toolkit for LLM agents to execute and interact with terminal commands@@ -100,6 +121,16 @@ class TerminalToolkit(BaseToolkit):``Runtime.GO`` and ``Runtime.JAVA``. If empty (the default),only the Python runtime is configured. Example:``enable_other_runtimes=[Runtime.GO, Runtime.JAVA]``.+ require_approval (Optional[Callable[[str], bool]], optional): Callback+ checked before starting a shell command or sending process input.+ Receives the sanitized command for :obj:`shell_exec`, or the raw+ input for :obj:`shell_write_to_process`. Return True to allow it;+ exceptions propagate without executing the command or input.+ None disables approval. Pass :obj:`_default_console_approval` for+ interactive approval; non-interactive applications should provide+ their own callback. This does not restrict actions performed+ internally by an approved program or replace sandbox isolation.+ (default: :obj:`None`)"""def __init__(@@ -114,6 +145,7 @@ class TerminalToolkit(BaseToolkit):clone_current_env: bool = False,install_dependencies: Optional[List[str]] = None,enable_other_runtimes: list[Runtime] | None = None,+ require_approval: Optional[Callable[[str], bool]] = None,):# auto-detect if running inside a CAMEL runtime container# when inside a runtime, use local execution (already sandboxed)@@ -166,6 +198,7 @@ class TerminalToolkit(BaseToolkit):if not os.path.exists(self.working_dir):os.makedirs(self.working_dir, exist_ok=True)self.safe_mode = safe_mode+ self._require_approval = require_approval# Initialize whitelist of allowed commands if providedself.allowed_commands = (@@ -530,6 +563,12 @@ class TerminalToolkit(BaseToolkit):except (APIError, NotFound) as e:raise RuntimeError(f"Docker API error: {e}") from e+ def _approve_command(self, command: str) -> bool:+ r"""Check approval for a command or process input."""+ return self._require_approval is None or self._require_approval(+ command+ )+def _sanitize_command(self, command: str) -> tuple[bool, str]:r"""A comprehensive command sanitizer for both local andDocker backends."""@@ -762,6 +801,9 @@ class TerminalToolkit(BaseToolkit):)command = message+ if not self._approve_command(command):+ return "Command rejected by approval policy."+if self.use_docker_backend:# For Docker, we always run commands in a shell# to support complex commands.@@ -1085,6 +1127,9 @@ class TerminalToolkit(BaseToolkit):)session = self.shell_sessions[id]+ if not self._approve_command(command):+ return "Input rejected by approval policy."+# Flush any lingering output from previous commands.self._collect_output_until_idle(id, idle_duration=0.3, max_wait=2.0)diff --git a/test/toolkits/test_terminal_toolkit.py b/test/toolkits/test_terminal_toolkit.pyindex 4dca353d5..f8986b36a 100644--- a/test/toolkits/test_terminal_toolkit.py+++ b/test/toolkits/test_terminal_toolkit.py@@ -11,6 +11,7 @@# See the License for the specific language governing permissions and# limitations under the License.# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========+import ioimport platformimport tempfilefrom pathlib import Path@@ -418,3 +419,178 @@ def test_sanitize_command_respects_customized_dangerous_commands()assert not is_safeassert "echo" in message.lower()+++def make_approval_toolkit(temp_dir, monkeypatch, request):+ monkeypatch.setattr(+ TerminalToolkit, "_setup_initial_environment", lambda self: None+ )++ def create(**kwargs):+ toolkit = TerminalToolkit(working_directory=str(temp_dir), **kwargs)+ request.addfinalizer(toolkit.cleanup)+ return toolkit++ return create++[email protected]("block", [True, False])[email protected]("decision", [None, True, False, "error"])+def test_shell_exec_approval(+ make_approval_toolkit, monkeypatch, block, decision+):+ approval = None if decision is None else Mock(return_value=decision)+ if decision == "error":+ approval.side_effect = ValueError("policy failed")+ toolkit = make_approval_toolkit(require_approval=approval)+ popen = Mock(wraps=terminal_toolkit_module.subprocess.Popen)+ monkeypatch.setattr(terminal_toolkit_module.subprocess, "Popen", popen)++ if decision == "error":+ with pytest.raises(ValueError, match="policy failed"):+ toolkit.shell_exec("approval", "echo approved", block=block)+ else:+ result = toolkit.shell_exec("approval", "echo approved", block=block)+ if decision is False:+ assert "rejected" in result+ elif block:+ assert "approved" in result+ else:+ toolkit.shell_sessions["approval"]["process"].wait(timeout=5)++ if approval is not None:+ approval.assert_called_once_with("echo approved")+ if decision is False or decision == "error":+ popen.assert_not_called()+ assert toolkit.shell_sessions == {}+ else:+ popen.assert_called_once()++[email protected]("is_safe", [True, False])+def test_approval_runs_after_sanitization(+ make_approval_toolkit, monkeypatch, is_safe+):+ approval = Mock(return_value=False)+ toolkit = make_approval_toolkit(require_approval=approval)+ monkeypatch.setattr(+ toolkit, "_sanitize_command", Mock(return_value=(is_safe, "sanitized"))+ )+ toolkit.shell_exec("approval", "original")+ if is_safe:+ approval.assert_called_once_with("sanitized")+ else:+ approval.assert_not_called()++[email protected]("backend", ["local", "docker"])[email protected]("decision", [None, True, False, "error"])+def test_process_input_approval(+ make_approval_toolkit, monkeypatch, backend, decision+):+ approval = None if decision is None else Mock(return_value=decision)+ if decision == "error":+ approval.side_effect = ValueError("policy failed")+ toolkit = make_approval_toolkit(require_approval=approval)+ process = Mock()+ session = {+ "running": True,+ "backend": backend,+ "process": process,+ "command_history": [],+ "log_file": "unused",+ }+ toolkit.shell_sessions["approval"] = session+ monkeypatch.setattr(+ toolkit, "_collect_output_until_idle", Mock(return_value="")+ )+ monkeypatch.setattr(toolkit, "_write_to_log", Mock())+ try:+ if decision == "error":+ with pytest.raises(ValueError, match="policy failed"):+ toolkit.shell_write_to_process("approval", "echo input")+ else:+ result = toolkit.shell_write_to_process("approval", "echo input")+ if decision is False:+ assert "rejected" in result++ if approval is not None:+ approval.assert_called_once_with("echo input")+ if decision is False or decision == "error":+ process.stdin.write.assert_not_called()+ process.stdin.flush.assert_not_called()+ process._sock.sendall.assert_not_called()+ assert session["command_history"] == []+ assert session["running"] is True+ elif backend == "local":+ process.stdin.write.assert_called_once_with("echo input\n")+ process.stdin.flush.assert_called_once()+ else:+ process._sock.sendall.assert_called_once_with(b"echo input\n")+ finally:+ toolkit.shell_sessions.clear()++[email protected](platform.system() == "Windows", reason="Requires bash")+def test_approved_shell_does_not_approve_later_input(+ make_approval_toolkit, temp_dir+):+ approval = Mock(side_effect=lambda command: command == "bash")+ toolkit = make_approval_toolkit(require_approval=approval)+ toolkit.shell_exec("approval", "bash", block=False)+ process = toolkit.shell_sessions["approval"]["process"]+ command = "echo bypass > approval_probe.txt"+ try:+ result = toolkit.shell_write_to_process("approval", command)+ assert "rejected" in result+ assert not (temp_dir / "approval_probe.txt").exists()+ assert [call.args[0] for call in approval.call_args_list] == [+ "bash",+ command,+ ]+ finally:+ process.stdin.write("exit\n")+ process.stdin.flush()+ try:+ process.wait(timeout=5)+ except terminal_toolkit_module.subprocess.TimeoutExpired:+ process.kill()+ process.wait(timeout=5)++[email protected]("stdin", [None, io.StringIO("yes\n")])+def test_console_approval_denies_non_tty(monkeypatch, stdin):+ monkeypatch.setattr(terminal_toolkit_module.sys, "stdin", stdin)+ prompt = Mock(side_effect=AssertionError("Must not read non-TTY input"))+ monkeypatch.setattr("builtins.input", prompt)+ assert (+ terminal_toolkit_module._default_console_approval("echo test") is False+ )+ prompt.assert_not_called()+++ "response,expected",+ [+ ("yes", True),+ (" Y ", True),+ ("", False),+ ("no", False),+ (EOFError(), False),+ ],+)+def test_console_approval_interactive(monkeypatch, response, expected):+ monkeypatch.setattr(+ terminal_toolkit_module.sys,+ "stdin",+ Mock(isatty=Mock(return_value=True)),+ )+ prompt = Mock(return_value=response)+ if isinstance(response, Exception):+ prompt.side_effect = response+ monkeypatch.setattr("builtins.input", prompt)+ assert (+ terminal_toolkit_module._default_console_approval("echo test")+ is expected+ )