Agent 가 닿을 수 있는 범위 좁히기

"""보안 특화 Tool 설계 예 — 읽기 도구와 쓰기 도구를 파일 수준에서 분리한다.

raw/07_CODE_ARCHITECTURE/01_AREA_BY_AREA/02_tools_영역.md의
"read-only tool을 write tool로 몰래 변경 금지" 규칙을 구조로 강제한 형태다.
"""
from pathlib import Path

# 이 Agent가 읽어도 되는 유일한 디렉터리. 상수로 고정한다.
ALLOWED_ROOT = Path("./workspace").resolve()
MAX_READ_BYTES = 200_000


class ToolPermissionError(Exception):
    """도구가 허용 범위를 벗어난 대상에 접근하려 할 때 발생한다."""


def _resolve_inside_allowed_root(relative_path: str) -> Path:
    """경로를 확정하고 허용 디렉터리 밖이면 거부한다.

    `..`를 이용해 상위 디렉터리로 빠져나가는 입력을 차단한다.
    """
    candidate = (ALLOWED_ROOT / relative_path).resolve()
    if candidate != ALLOWED_ROOT and ALLOWED_ROOT not in candidate.parents:
        raise ToolPermissionError(f"허용 디렉터리 밖의 경로입니다: {relative_path}")
    return candidate


def read_workspace_file(relative_path: str) -> str:
    """Read a UTF-8 text file inside the agent workspace. This tool never writes."""
    target = _resolve_inside_allowed_root(relative_path)
    if not target.is_file():
        return f"[없음] 파일을 찾을 수 없습니다: {relative_path}"
    if target.stat().st_size > MAX_READ_BYTES:
        return f"[초과] 파일이 {MAX_READ_BYTES} bytes를 넘습니다: {relative_path}"
    return target.read_text(encoding="utf-8", errors="replace")


def list_workspace_files(subdir: str = "") -> list[str]:
    """List file names inside the agent workspace. This tool never writes."""
    target = _resolve_inside_allowed_root(subdir)
    if not target.is_dir():
        return []
    return sorted(p.name for p in target.iterdir() if p.is_file())


# 읽기 도구만 Agent에게 노출한다. 쓰기 도구는 이 목록에 넣지 않는다.
READ_ONLY_TOOLS = [read_workspace_file, list_workspace_files]