Claude Code 도구 모음 화면 읽는 법, 권한까지 정리

Claude Code 화면에 Read·Edit·Bash 같은 표시가 뜬다면, 그 순간 에이전트가 파일을 읽거나 고치거나 명령을 실행하고 있다는 뜻입니다.

이 이름들이 바로 Claude Code의 "도구(tool)"입니다.

도구 이름만 읽을 줄 알아도 에이전트가 지금 뭘 하려는지 파악되고, 권한 설정으로 그 행동을 통제할 수 있습니다.

이 글에서는 Claude Code 공식 문서를 기준으로, 화면에 자주 보이는 대표 도구가 각각 무슨 뜻인지, 또 권한 시스템으로 어떻게 통제하는지를 정리합니다.

참고로 앞서 다룬 "자주 쓰는 Claude Code 명령어" 글과 이어지는 클로드 코드 연작입니다.

 

핵심 요약: 도구 이름은 에이전트의 "행동 라벨"입니다. 이름을 읽으면 무슨 일을 하는지 알 수 있고, 권한 규칙으로 어떤 도구를 자동 허용하고 어떤 도구를 막을지 정할 수 있습니다.

 

도구가 뭐길래 화면에 계속 뜰까

Claude Code에는 코드를 이해하고 수정하기 위한 "내장 도구(built-in tools)" 세트가 들어 있습니다.

에이전트는 답만 내놓는 게 아니라 파일을 읽고 명령을 실행하며 실제로 작업을 진행합니다.

그 행동 하나하나가 도구 호출이고, 화면에 뜨는 이름이 곧 그 도구입니다.

도구 이름은 그냥 표시로 끝나지 않습니다.

권한 규칙이나 서브에이전트 설정, 훅(hook) 조건에서 그대로 쓰는 정확한 문자열이기도 합니다.

그래서 이름을 제대로 익혀두면 나중에 자동화나 권한 설정을 할 때 바로 가져다 쓸 수 있습니다.

 

화면에 자주 보이는 대표 도구 읽는 법

아래 표는 초보자가 가장 자주 마주치는 내장 도구를 모은 것입니다.

"권한 필요" 열은 기본 모드에서 확인창(프롬프트)이 뜨는지 여부를 뜻합니다.

도구	하는 일	화면에서 보면 무슨 의미	권한 필요
Read	파일 내용을 줄번호와 함께 읽음. 파일이 크면 첫 페이지만 주고 더 읽으라고 안내	파일을 읽는 중	아니오
Edit	정확한 문자열 치환으로 파일 일부를 수정. 편집 전 그 파일을 먼저 Read해야 함	파일을 고치는 중	예
Write	파일을 새로 만들거나 통째로 덮어씀(추가·병합 아님)	파일을 새로 쓰는 중	예
Bash	셸 명령을 실행. 기본 2분 타임아웃, 백그라운드 실행도 가능	터미널 명령을 실행하는 중	예(읽기 전용 명령은 예외)
Grep	파일 "내용" 안에서 패턴 검색. ripgrep 기반, .gitignore 존중	코드 내용을 검색하는 중	아니오
Glob	파일 "이름" 패턴으로 파일 찾기. 수정시간순 정렬, 최대 100개	파일 이름으로 찾는 중	아니오
Agent (화면 라벨 Task)	자체 컨텍스트를 가진 서브에이전트를 띄워 작업을 맡김. 부모는 최종 결과만 받음	하위 작업을 별도 에이전트에 맡기는 중	아니오
WebSearch	웹 검색으로 제목·URL만 반환(페이지 본문은 안 가져옴)	웹을 검색하는 중	예
WebFetch	특정 URL을 가져와 마크다운으로 바꾼 뒤 요약 성격으로 답을 반환	특정 URL을 읽는 중	예
TaskCreate 계열 (구 TodoWrite)	세션 할 일 체크리스트를 만들고 갱신	할 일 목록을 만들거나 고치는 중	아니오

표에서 Read·Grep·Glob은 권한이 "아니오"로 돼 있는데, 여기엔 단서가 붙습니다.

이 "아니오"는 작업 디렉터리, 그러니까 지금 열어둔 프로젝트 폴더 안을 볼 때만 적용됩니다.

작업 폴더 바깥의 경로를 읽으려 하면 이 도구들도 여전히 확인을 요구합니다.

 

Task와 Agent, TodoWrite는 왜 이름이 헷갈릴까

도구 이름이 버전에 따라 달라지는 탓에 헷갈리는 경우가 있습니다.

대표적인 게 서브에이전트 도구입니다.

공식 문서상 정식 이름은 Agent인데, 화면 표기(라벨)에는 Task로 보일 수 있습니다.

공식 문서도 화면 라벨과 정식 이름이 다를 수 있다고 안내합니다.

그러니 "Task"가 보이더라도 "아, 하위 작업을 맡기는 Agent구나"로 읽으면 됩니다.

할 일 관리 도구도 최근에 바뀌었습니다.

예전에는 TodoWrite가 세션 할 일 체크리스트를 관리했습니다.

그런데 공식 문서 기준 v2.1.142부터 TodoWrite는 기본 비활성화되고, TaskCreate·TaskGet·TaskList·TaskUpdate로 대체됐습니다.

그러니 요즘 화면에서 할 일 목록을 갱신하는 표시는 TodoWrite가 아니라 Task 계열일 가능성이 큽니다.

이름이 헷갈릴 땐 "이 도구가 파일을 만지는가, 명령을 실행하는가, 정보만 읽는가"부터 보면 됩니다. 그게 곧 권한이 필요한지 아닌지의 기준이기도 합니다.

---

 

권한 시스템: 도구를 통제하는 3단 구조

도구 이름을 읽을 수 있게 됐다면 다음은 통제할 차례입니다.

Claude Code 공식 문서는 권한을 크게 3단으로 설명합니다.

먼저 읽기 전용(파일 읽기·Grep 등)은 작업 디렉터리 안에서는 승인이 필요 없습니다.

Bash 명령은 승인이 필요합니다(내장 읽기 전용 명령은 예외입니다).

파일 수정, 즉 Edit·Write도 승인이 필요합니다.

정보만 조회하는 행동은 그냥 진행하고, 시스템을 바꾸거나 실행하는 행동은 확인을 받는 구조인 셈입니다.

여기서 놓치면 안 되는 사실이 하나 있습니다.

권한은 모델(AI)이 아니라 Claude Code라는 하네스(프로그램)가 강제한다는 점입니다.

프롬프트나 CLAUDE.md 파일은 "무엇을 시도할지"만 유도할 뿐, "무엇을 허용할지"는 바꾸지 못합니다.

그래서 위험한 명령을 막고 싶다면 규칙으로 막아야 합니다. 부탁하듯 지시문을 넣는 것만으로는 부족합니다.

 

Allow, Ask, Deny 규칙과 평가 순서

권한 규칙에는 세 종류가 있습니다.

Allow는 자동 허용, Ask는 항상 확인, Deny는 차단입니다.

이 세 규칙은 정해진 순서대로 평가됩니다.

순서는 Deny → Ask → Allow이고, 먼저 매치되는 규칙이 결과를 결정합니다.

규칙이 얼마나 구체적인지는 이 순서에 영향을 주지 않습니다.

그래서 넓은 Deny 하나가 좁은 Allow를 덮어씁니다.

예를 들어 아래처럼 설정하면 aws 명령은 s3 조회까지 포함해 전부 막힙니다.

Deny:  Bash(aws *)      # aws로 시작하는 모든 명령 차단
Allow: Bash(aws s3 ls)  # 이 허용은 위 Deny에 덮여 무효

# 규칙 형식은 Tool 또는 Tool(지정자)
Bash(npm run *)          # npm run 계열 명령
Read(./.env)             # 특정 파일 읽기
Edit(/src/**)            # src 폴더 아래 편집
WebFetch(domain:example.com)  # 특정 도메인만

 

Deny를 쓰는 방식도 두 갈래로 나뉩니다.

도구 이름만 쓴 Deny(예: Bash)는 그 도구를 아예 컨텍스트에서 빼버립니다.

반면 범위를 지정한 Deny(예: Bash(rm *))는 도구는 남기고 그 호출만 차단합니다.

규칙은 /permissions 화면에서 확인하고 관리할 수 있습니다.

 

권한 모드: 확인 강도를 통째로 바꾸기

규칙을 하나하나 정하기 전에, 전체 확인 강도를 한 번에 정하는 "권한 모드"가 있습니다.

세션을 시작할 때 지정하거나 도중에 바꿀 수 있습니다.

모드	동작	언제 쓰나
default	각 도구 첫 사용 시 확인	평소 기본값
acceptEdits	작업 폴더 내 파일 편집과 mkdir·touch·mv·cp 같은 명령을 자동 승인	편집이 많고 확인이 번거로울 때
plan	읽기·읽기전용 탐색만, 소스 파일은 편집하지 않음	계획부터 세우고 싶을 때
bypassPermissions	확인 프롬프트 건너뜀(명시적 Ask 규칙과 rm -rf 회로차단은 예외). 컨테이너·VM 등 격리 환경 전용	격리된 환경에서 자동화할 때만

이 밖에 도구 호출을 자동 승인하는 auto 모드, 그리고 사전 허용된 것 외에는 자동 거부하는 dontAsk 모드도 있습니다.

모드는 설정 파일의 defaultMode 값이나 시작 시 --permission-mode 옵션으로 지정합니다.

세션 도중이라면 Shift+Tab로 모드를 바꿀 수 있습니다(정확한 순서와 키는 버전·플랫폼에 따라 다를 수 있습니다).

bypassPermissions는 확인을 통째로 건너뛰는 만큼 위험합니다. 공식 문서도 컨테이너나 VM 같은 격리 환경 전용으로 안내하고, root·sudo 권한에서는 실행 자체를 거부합니다.

 

확인 없이 실행되는 읽기 전용 명령

Bash가 "권한 필요"인데도 어떤 명령은 확인 없이 바로 실행됩니다.

정보만 조회하는 내장 읽기 전용 명령들이 그렇습니다.

대표적으로 ls, cat, echo, pwd, head, tail, grep, find, wc, which, diff, stat, du, cd, 그리고 읽기 전용 형태의 git이 여기에 해당합니다.

이 목록 자체는 사용자가 바꿀 수 없습니다.

굳이 이런 명령까지 확인받고 싶다면 Ask나 Deny 규칙을 따로 추가하면 됩니다.

 

mcp__로 시작하는 도구는 뭔가

화면에서 mcp__로 시작하는 긴 이름의 도구를 볼 때가 있습니다.

이건 기본 내장 도구가 아니라, MCP 서버 연결로 추가된 외부 도구입니다.

MCP는 쉽게 말해 AI가 외부 도구와 안전하게 연결되도록 해주는 공통 연결 규격입니다.

MCP 서버를 붙이면 그 서버가 제공하는 도구가 mcp__서버명__도구명 형식으로 나타납니다.

가령 mcp__puppeteer__puppeteer_navigate는 puppeteer 서버가 제공하는 브라우저 이동 도구입니다.

결국 이름 앞의 mcp__만 봐도 "이건 외부에서 붙인 도구구나"를 한눈에 구분할 수 있습니다.

브라우저 조작, GitHub API, 데이터베이스, Gmail 같은 기능이 이런 식으로 들어옵니다.

권한도 같은 방식으로 지정합니다.

mcp__puppeteer는 그 서버의 아무 도구를, mcp__puppeteer__*는 그 서버 전체를 가리킵니다.

모든 MCP 도구를 막고 싶다면 mcp__*를 Deny로 걸면 됩니다.

참고로 스킬(Skill)은 새 도구를 추가하지 않고, 기존 Skill 도구를 거쳐 실행됩니다.

 

 

자주 묻는 질문

화면에 뜨는 도구 이름만 봐도 뭘 하는지 알 수 있나요?

네, 대부분 알 수 있습니다.

Read는 파일을 읽는 중, Edit·Write는 파일을 고치거나 새로 쓰는 중, Bash는 명령을 실행하는 중입니다.

Grep은 코드 내용 검색, Glob은 파일 이름 검색, WebSearch·WebFetch는 웹을 뒤지는 중이라는 뜻입니다.

TodoWrite가 안 보이는데 어디 갔나요?

공식 문서 기준 v2.1.142부터 TodoWrite는 기본 비활성화됐습니다.

대신 TaskCreate·TaskGet·TaskList·TaskUpdate 같은 Task 계열이 할 일 목록을 담당합니다.

환경변수 CLAUDE_CODE_ENABLE_TASKS=0으로 예전 방식을 다시 켤 수도 있습니다.

위험한 명령을 확실히 막으려면 어떻게 하나요?

규칙으로 막아야 합니다.

지시문으로 부탁하는 건 소용이 없습니다. 권한은 모델이 아니라 하네스가 강제하기 때문입니다.

평가 순서가 Deny → Ask → Allow이므로, Bash(rm *)처럼 넓은 Deny를 걸면 좁은 Allow가 있어도 막힙니다.

---

정리하면

Claude Code의 도구 이름은 에이전트의 행동을 그대로 보여주는 라벨입니다.

Read·Edit·Write·Bash·Grep·Glob 정도만 알아둬도 화면의 흐름이 읽힙니다.

그다음은 권한입니다.

읽기는 자동, 실행과 편집은 확인이라는 3단 구조를 이해하고 Deny → Ask → Allow 순서만 기억하면 됩니다.

안전한 도구는 Allow로 자동화하고 위험한 명령은 Deny로 막으면, 승인 피로와 사고를 한꺼번에 줄일 수 있습니다.

개인적으로는 처음 며칠은 default 모드로 화면을 천천히 읽으며 도구 이름과 친해지길 권합니다. 손에 익은 뒤에 자동화 규칙을 늘려도 늦지 않습니다.

도구 이름과 권한, 이 두 가지만 잡으면 Claude Code 화면은 더 이상 낯선 로그가 아니라 읽을 수 있는 작업 기록이 됩니다.