Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

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.py
index 486fcc3d2..5aca42bf5 100644
--- a/camel/toolkits/terminal_toolkit/terminal_toolkit.py
+++ b/camel/toolkits/terminal_toolkit/terminal_toolkit.py
@@ -21,7 +21,7 @@ import threading
import time
import uuid
from queue import Empty, Full, Queue
-from typing import Any, Dict, List, Optional
+from typing import Any, Callable, Dict, List, Optional
from camel.logger import get_logger
from 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 provided
self.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 and
Docker 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.py
index 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 io
import platform
import tempfile
from pathlib import Path
@@ -418,3 +419,178 @@ def test_sanitize_command_respects_customized_dangerous_commands(
)
assert not is_safe
assert "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
+ )