파일시스템 및 코드 도구

이 도구들은 에이전트가 가장 많이 사용하는 핵심 도구입니다. 명령 실행, 파일 읽기·수정, 코드베이스 검색, PDF 텍스트 추출, git 조작이 모두 여기에 해당합니다. 모든 도구는 워크스페이스 디렉터리를 기준으로 동작하며, Revka의 보안 정책의 통제를 받습니다. 파일이나 프로세스에 접근하기 전에 경로 허용 목록, 자율성 수준, 시간당 작업 예산이 모두 적용됩니다.

이 페이지에서 소개하는 아홉 가지 도구는 모두 기본 도구 레지스트리에 포함되어 있으므로, 최소한의 설정에서도 사용할 수 있습니다. 전체 도구 목록은 도구 개요를 참고하세요.

참고

경로는 워크스페이스 루트를 기준으로 해석됩니다. ..이나 심볼릭 링크를 통해 워크스페이스 밖을 참조하는 경로는, 명시적 허용 목록 항목이 없는 한 거부됩니다. 정책, 명령 및 샌드박싱을 참고하세요.

shell

워크스페이스 디렉터리에서 임의의 셸 명령을 실행합니다.

{ "command": "cargo test --workspace", "approved": false }

필드	타입	기본값	설명
command	string	— (필수)	실행할 셸 명령입니다.
approved	boolean	false	감시 모드에서 중간/고위험 명령을 명시적으로 승인하려면 true로 설정합니다.

동작 및 제한:

• 출력 제한: 명령 출력은 1 MB에서 잘립니다.
• 타임아웃: 명령은 기본적으로 60초 후 강제 종료됩니다. shell_tool.timeout_secs로 변경할 수 있습니다.
• 정제된 환경: 프로세스 환경은 초기화되며, 안전한 허용 목록만 다시 추가됩니다. Unix에서는 PATH, HOME, TERM, LANG, USER, SHELL, TMPDIR이며, Windows에서는 PATH, PATHEXT, USERPROFILE, SYSTEMROOT, COMSPEC, TEMP 등입니다. API 키 등 비밀 값은 절대 전달되지 않습니다. 스크립트가 커스텀 변수를 필요로 한다면 security.shell_env_passthrough에 해당 변수 이름을 추가하거나, 명령 자체에 인라인으로 지정하세요.
• 샌드박스: 명령은 샌드박스 레이어를 통해 실행됩니다. 기본 NoopSandbox는 명령을 직접 실행하며, 실제 샌드박스(설정된 경우)는 추가 격리로 실행을 감싸줍니다.
• 승인 게이팅: 감시 모드에서 보안 정책은 명령 위험도를 분류합니다. 중간/고위험 명령은 approved: true를 전달하지 않으면 차단됩니다. 읽기 전용 정책과 속도 제한기도 실행을 차단할 수 있습니다.

주의

shell은 이 페이지에서 가장 강력한 도구입니다. 정책, 명령 및 샌드박싱과 OTP 게이팅 및 긴급 정지에서 설명하는 명령 허용/거부 목록과 OTP 게이팅으로 반드시 제한하세요.

file_read

줄 번호와 함께 파일 내용을 읽습니다. offset/limit으로 부분 읽기를 지원하며, PDF에서 일반 텍스트를 인라인으로 추출하고, 그 외 바이너리 파일은 손실 있는 UTF-8 변환으로 읽습니다.

{ "path": "src/main.rs", "offset": 1, "limit": 50 }

필드	타입	기본값	설명
path	string	— (필수)	파일 경로. 상대 경로는 워크스페이스 기준으로 해석되며, 외부 경로는 정책 허용 목록 항목이 필요합니다.
offset	integer	1	시작 줄 번호 (1-based).
limit	integer	전체 줄	반환할 최대 줄 수.

• 크기 제한: 10 MB를 초과하는 파일은 거부됩니다.
• PDF 텍스트: file_read는 PDF에서 텍스트를 인라인으로 추출합니다. PDF 텍스트를 읽기 위해 별도로 pdf_read를 호출할 필요는 없습니다. 추출 한도를 명시적으로 제어하고 싶을 때만 pdf_read를 사용하세요.

file_write

워크스페이스 내 파일에 내용을 씁니다. 누락된 상위 디렉터리도 자동으로 생성합니다.

{ "path": "output/report.md", "content": "# Report\n\n..." }

필드	타입	기본값	설명
path	string	— (필수)	워크스페이스 내 대상 경로.
content	string	— (필수)	파일에 쓸 전체 내용.

이 도구는 전체 덮어쓰기로 동작하며 추가(append)가 아닙니다. path에 기존 파일이 있으면 완전히 교체됩니다. 기존 파일의 특정 부분만 수정하려면 file_edit을 사용하는 것이 좋습니다.

file_edit

파일에서 정확한 문자열을 찾아 새 내용으로 교체합니다. 특정 부분만 수정할 때는 전체 파일을 다시 쓰는 것보다 안전합니다.

{
  "path": "src/main.rs",
  "old_string": "fn hello() {\n    println!(\"hi\");\n}",
  "new_string": "fn hello_world() {\n    println!(\"hello, world\");\n}"
}

필드	타입	기본값	설명
path	string	— (필수)	편집할 파일.
old_string	string	— (필수)	찾아서 교체할 정확한 텍스트.
new_string	string	— (필수)	대체할 텍스트.

old_string은 정확히 한 번만 일치해야 합니다. 일치 횟수가 0이거나 두 번 이상이면 편집이 거부되고 오류가 반환됩니다(old_string matches N times; must match exactly once). 일치가 고유해지도록 주변 컨텍스트를 충분히 — 보통 몇 줄 — 포함하세요.

팁

문자열이 여러 번 일치하여 편집이 실패한 경우, old_string을 좁히지 말고 인접한 줄을 추가하여 넓히세요. 서로 다른 여러 위치를 교체하려면 위치마다 file_edit을 개별 호출하세요.

glob_search

워크스페이스 내에서 glob 패턴에 일치하는 파일을 찾습니다. 워크스페이스 루트 기준의 상대 경로를 정렬된 목록으로 반환합니다.

{ "pattern": "src/**/*.rs" }

필드	타입	기본값	설명
pattern	string	— (필수)	Glob 패턴. 예: **/*.rs, src/**/mod.rs, docs/*.md.

파일 이름이나 경로 패턴으로 파일을 찾을 때는 glob_search를 사용하세요. 파일 내용을 검색하려면 content_search를 사용하세요.

content_search

워크스페이스 내에서 정규 표현식으로 파일 내용을 검색합니다. 가능하면 ripgrep(rg)을 사용하고, 없으면 grep -rn -E로 대체합니다. 정규 표현식 문법은 ripgrep 호환(Rust regex)입니다.

{ "pattern": "fn main", "include": "*.rs", "output_mode": "content", "context_after": 2 }

필드	타입	기본값	설명
pattern	string	— (필수)	검색할 정규 표현식.
path	string	.	검색할 디렉터리.
output_mode	string	content	content(일치 줄), files_with_matches(경로만), count(파일별 일치 횟수).
include	string	—	파일 glob 필터. 예: *.rs.
case_sensitive	boolean	true	false로 설정하면 대소문자를 구분하지 않습니다.
context_before	integer	0	각 일치 앞에 표시할 컨텍스트 줄 수.
context_after	integer	0	각 일치 뒤에 표시할 컨텍스트 줄 수.
multiline	boolean	false	여러 줄 매칭을 활성화합니다. ripgrep이 필요하며 grep 폴백에서는 오류가 발생합니다.
max_results	integer	1000	반환할 최대 결과 수.

출력 모드:

• content — 일치하는 줄 자체를 반환합니다. 주변 줄이 필요하면 context_before/context_after와 함께 사용하세요.
• files_with_matches — 일치가 포함된 파일 경로만 반환합니다. “X를 언급하는 파일은 어디?”와 같은 경우에 적합합니다.
• count — 파일별 일치 횟수를 반환합니다.

semantic_code_search

토큰 효율적인 검색 어댑터를 사용하여 관련 코드 스니펫을 찾습니다. Semble(설치된 경우)을 먼저 시도하고, 그다음 ripgrep, 마지막으로 내장 리터럴 스캐너로 자동 폴백됩니다.

{ "query": "context compression for tool outputs", "top_k": 5 }

필드	타입	기본값	설명
query	string	— (필수)	자연어 또는 심볼 쿼리.
path	string	.	검색할 디렉터리.
top_k	integer	8	반환할 최대 결과 수 (최대 25로 제한).
backend	string	auto	auto, semble, 또는 literal.

백엔드:

• auto — PATH에 semble 바이너리가 있으면 Semble을 우선 사용하고, 없으면 ripgrep, 그다음 내장 리터럴 스캐너로 폴백합니다.
• semble — Semble 사이드카를 강제로 사용합니다. Semble이 설치되어 있지 않으면 실행 가능한 오류(Install with pip install semble or uv tool install semble, or use backend='literal')를 반환합니다.
• literal — Semble을 건너뛰고 ripgrep 또는 내장 스캐너를 직접 사용합니다.

Semble은 선택적 Python MCP 사이드카입니다. 설정 방법은 Python MCP 사이드카 설치를 참고하세요.

pdf_read

워크스페이스 내 PDF 파일에서 일반 텍스트를 추출합니다.

{ "path": "docs/spec.pdf", "max_chars": 50000 }

필드	타입	기본값	설명
path	string	— (필수)	PDF 파일 경로.
max_chars	integer	50000	반환할 최대 문자 수 (상한 200000). 한도를 초과한 출력은 표식과 함께 잘립니다.

• 크기 제한: 50 MB를 초과하는 PDF는 거부됩니다.
• 이미지 전용 / 암호화된 PDF: 이러한 파일은 오류가 아닌 성공 결과를 반환하며, 출력에는 PDF contains no extractable text (may be image-only or encrypted) 경고가 포함됩니다. 추출할 텍스트 레이어가 없기 때문입니다.
• 빌드 피처: PDF 추출을 사용하려면 rag-pdf Cargo 피처가 필요합니다. 해당 피처 없이 빌드된 경우 pdf_read는 등록은 되지만 명확한 오류를 반환합니다: PDF extraction is not enabled. Rebuild with: cargo build --features rag-pdf. Cargo 피처 플래그 및 ADR을 참고하세요.

참고

file_read도 PDF 텍스트를 인라인으로 추출합니다. max_chars로 출력을 제한하거나, 더 큰 50 MB 한도로 PDF를 읽고 싶을 때 pdf_read를 사용하세요.

git_operations

워크스페이스의 git 작업 트리를 대상으로 구조화된 git 작업을 수행합니다. 파싱된 JSON 출력을 제공하며 자율성 수준이 적용됩니다.

{ "operation": "status" }

{ "operation": "commit", "message": "fix: resolve race condition" }

필드	타입	설명
operation	string (필수)	status, diff, log, branch, commit, add, checkout, stash 중 하나.
message	string	커밋 메시지 (commit 시 사용).
paths	string	스테이징할 파일 경로 (add 시 사용).
branch	string	브랜치 이름 (checkout 시 사용).
files	string	diff할 파일 또는 경로 (diff 시 사용, 기본값 .).
cached	boolean	스테이징된 변경 사항 표시 (diff 시 사용).
limit	integer	반환할 로그 항목 수 (log 시 사용, 기본값 10).
stash_action	string	push, pop, list, 또는 drop (stash 시 사용).
path	string	작업을 실행할 워크스페이스 내 선택적 하위 디렉터리. 기본값은 워크스페이스 루트입니다.

자율성 적용: 쓰기 작업(commit, add, checkout, stash)은 더 높은 자율성 수준이 필요합니다. 읽기 전용 정책 모드에서는 차단됩니다(git write operations require higher autonomy level). status, diff, log, branch는 항상 사용 가능합니다. 자율성 수준 및 승인을 참고하세요.

인수 안전성: 임의 코드 실행이나 훅 우회를 방지하기 위해 git 인수를 정제합니다. --exec=, --upload-pack=, --receive-pack=, --pager=, --editor=, --no-verify, -c, 명령 치환(`, $(...)), 셸 메타문자(|, ;, >) 등의 옵션은 거부됩니다.

팁

구조화된 도구가 지원하지 않는 작업(예: push, merge, rebase)은 shell 도구를 통해 git 명령을 실행하세요. 동일한 명령 정책과 승인 게이팅이 적용됩니다.

관련 페이지

• 도구 개요 — 전체 도구 목록 및 등록 방식.
• 보안 모델 및 정책, 명령 및 샌드박싱 — 경로 허용 목록, 명령 게이팅, 샌드박싱.
• 자율성 수준 및 승인 — 읽기 전용/감시/전체 모드가 쓰기 도구에 미치는 영향.
• 설정: 채널, 도구 및 통합 — shell_tool.timeout_secs, security.shell_env_passthrough 등의 설정 키.
• 코드 에이전트, 위임 및 파이프라인 — Claude Code, Codex 등에 대규모 코딩 작업을 위임하는 방법.