Tool Protocol — GEODE Docs

프로토콜

core/tools/base.py:35가 Tool을 Protocol 클래스로 정의합니다. 네이티브, MCP, 플러그인을 막론하고 모든 도구가 아래를 구현합니다.

class Tool(Protocol):
    name: str
    description: str
    input_schema: dict[str, Any]
    async def execute(self, **kwargs) -> Any: ...

단일 진실의 출처

core/tools/definitions.json이 도구 메타데이터 (이름, 설명, 스키마, 상시 로드 플래그) 를 중앙 집중화합니다. 핸들러는 카테고리 모듈 (core/tools/file_tools.py, core/tools/memory_tools.py 등) 에 있고, 이름으로 레지스트리에 연결됩니다.

지연 로딩

모든 LLM 호출마다 도구 정의 전체를 보내면 턴당 input 토큰을 크게 태우게 됩니다. GEODE는 카탈로그를 분할합니다.

티어	동작
상시 로드	모든 LLM 호출에서 전송. `memory_search`, `memory_get`, `memory_save`, `web_search`, `wanted_jobs_search`.
지연 로드	`tool_search`로 발견 가능, 요청 시 로드. 전체 도구 수가 `defer_threshold` (기본 10) 를 넘으면 활성화됩니다.

상시 로드 도구의 frozenset은 core/tools/registry.py:215-223에 ALWAYS_LOADED_TOOLS로 정의됩니다.

이 패턴은 Claude Code의 도구 지연 로딩 설계에서 빌려온 것입니다.

도구 실행 라이프사이클 (Hook 이벤트)

TOOL_EXEC_START. execute() 이전
TOOL_EXEC_END. 성공 이후
TOOL_EXEC_FAILED. 예외 경로
TOOL_RECOVERY_START / TOOL_RECOVERY_END. 재시도 경로
TOOL_APPROVAL_REQUEST / GRANTED / DENIED. HITL 게이트

4-티어 안전성

도구는 definitions.json에서 안전 티어로 태깅됩니다.

읽기 전용. Read, Grep, Glob, Search → 승인 없음
로컬 변경. Edit, Write → CWD 내 allow-list
부수 효과. Bash, 메시지 전송 → HITL 승인
파괴적. rm -rf, force push → 확인 필요

도구 프로토콜

프로토콜

단일 진실의 출처

지연 로딩

도구 실행 라이프사이클 (Hook 이벤트)

4-티어 안전성

카테고리