도구 참조

Claude Code가 사용할 수 있는 도구의 완전한 참조로, 권한 요구사항 및 도구별 동작을 포함합니다.

Claude Code는 코드베이스를 이해하고 수정하는 데 도움이 되는 기본 제공 도구 세트에 액세스할 수 있습니다. 도구 이름은 권한 규칙, 서브에이전트 도구 목록, 및 훅 매처에서 사용하는 정확한 문자열입니다.

Claude가 사용할 수 있는 도구와 먼저 요청할 시기를 제어하려면 설정, 훅 또는 서브에이전트의 도구 목록에서 권한 규칙을 구성합니다. 도구 이름을 허용하는 각 위치는 권한 규칙 및 훅으로 도구 구성을 참조하세요.

사용자 정의 도구를 추가하려면 MCP 서버를 연결합니다. 재사용 가능한 프롬프트 기반 워크플로우로 Claude를 확장하려면 스킬을 작성합니다. 이는 새 도구 항목을 추가하는 대신 기존 Skill 도구를 통해 실행됩니다.

권한 규칙 및 훅으로 도구 구성하기

대부분의 경우 Claude가 이러한 도구를 사용할 시기를 결정하므로 Claude와 상호작용할 때 도구 이름을 직접 지정할 필요가 없습니다. 권한 및 기타 구성을 정의할 때 도구 이름을 직접 참조합니다:

• 설정의 permissions.allow 및 permissions.deny와 /permissions 인터페이스에서
• CLI flags의 --allowedTools 및 --disallowedTools에서
• Agent SDK의 allowedTools 및 disallowedTools 옵션에서
• subagent의 tools 또는 disallowedTools frontmatter에서
• skill의 allowed-tools frontmatter에서
• hook의 if condition에서

이 모든 항목은 동일한 규칙 형식인 ToolName(specifier)을 허용합니다. specifier는 도구에 따라 다르며, 여러 도구가 형식을 공유합니다:

여기에 나열되지 않은 도구(예: ExitPlanMode 또는 ShareOnboardingGuide)는 specifier 없이 도구 이름만 허용합니다.

Edit(...) allow 규칙은 동일한 경로에 대한 읽기 액세스도 부여하므로 일치하는 Read(...) 규칙이 필요하지 않습니다. Read(...) deny 규칙은 동일한 경로의 Edit 및 Write 도구도 차단하며, 새 파일을 만드는 것도 포함됩니다. 두 도구 모두 Claude가 읽을 수 있어야 하는 콘텐츠를 변경하기 때문입니다. Read deny 체크는 편집 시 Claude Code v2.1.208 이상이 필요하며, 쓰기 시 v2.1.228 이상이 필요합니다.

Hook matcher 필드는 괄호로 묶인 규칙 형식이 아닌 도구 이름만 사용합니다. 매칭 규칙은 matcher patterns을 참조하세요. 각 도구가 hook의 tool_input에 전달하는 필드 이름은 PreToolUse input reference를 참조하세요.

에이전트 도구 동작

에이전트 도구는 별도의 컨텍스트 윈도우에서 서브에이전트를 생성합니다. 서브에이전트는 자율적으로 작업을 진행한 후 부모 대화에 단일 텍스트 결과를 반환합니다. 부모는 서브에이전트의 중간 도구 호출이나 출력을 보지 못하고 최종 결과만 봅니다. 에이전트 팀이 활성화된 경우, name을 포함하는 호출은 팀원을 시작할 수 있으며, 이는 결과를 반환하는 대신 팀 메시지를 통해 보고합니다.

서브에이전트가 실행하는 턴의 수를 제한하려면 서브에이전트 정의에서 maxTurns를 설정합니다. 서브에이전트가 제한에 도달하면 Claude Code는 반환된 결과를 부분 출력으로 표시하며, Claude는 서브에이전트를 재개하여 계속할 수 있습니다.

동일한 에이전트 도구는 포크 모드가 켜져 있는 곳에서 포크된 서브에이전트도 시작합니다. 포크는 새로 시작하는 대신 전체 부모 대화를 상속하고, 포그라운드에 유지되는 경우를 제외하고 백그라운드에서 실행되며, 여전히 터미널에서 권한 프롬프트를 표시합니다. 이 섹션의 나머지 부분은 포크되지 않은 서브에이전트를 설명합니다.

포크되지 않은 서브에이전트가 사용할 수 있는 도구는 서브에이전트 정의의 tools 및 disallowedTools 필드에 따라 달라집니다:

• 두 필드 모두 설정되지 않음: 서브에이전트는 서브에이전트에서 사용 가능한 모든 도구를 상속합니다.
• tools만 설정됨: 서브에이전트는 나열된 도구만 가져옵니다.
• disallowedTools만 설정됨: 서브에이전트는 나열된 도구를 제외한 모든 부모 도구를 가져옵니다.
• 둘 다 설정됨: disallowedTools가 우선합니다. 둘 다에 나열된 도구는 제거됩니다.

모든 경우에 해결된 집합은 서브에이전트에서 사용 가능한 도구로 제한됩니다. 서브에이전트에서 사용할 수 없는 도구는 tools에 나열되어 있어도 절대 부여되지 않습니다.

서브에이전트의 tools 목록의 모든 항목이 사용 가능한 도구와 일치하지 못하면 에이전트 도구는 일반적으로 서브에이전트를 시작하는 대신 항목의 이름을 지정하는 오류를 반환합니다. 에이전트가 0개의 도구로 생성됨에서 메시지와 각 항목을 수정하는 방법을 참조하세요.

서브에이전트를 시작하는 것 자체는 권한을 요청하지 않습니다. Claude Code는 서브에이전트의 자체 도구 호출을 실행할 때 권한 규칙에 대해 확인합니다.

서브에이전트의 권한 프롬프트를 보는 위치는 포그라운드 또는 백그라운드에서 실행되는지 여부에 따라 달라집니다. Claude Code는 기본적으로 서브에이전트를 백그라운드에서 실행하며, 포그라운드에서 실행되는 경우는 제외합니다.

• 포그라운드 서브에이전트는 각 도구 호출이 발생하는 순간 주 대화에서 볼 수 있는 동일한 권한 프롬프트를 표시합니다.
• 백그라운드 서브에이전트 v2.1.186부터 주 세션에서 권한 프롬프트를 표시합니다. 프롬프트는 어느 서브에이전트가 요청하는지 이름을 지정하며, Esc를 누르면 서브에이전트를 중지하지 않고 해당 도구 호출 하나만 거부합니다. v2.1.186 이전에는 백그라운드 서브에이전트가 프롬프트를 표시할 수 있는 모든 도구 호출을 자동으로 거부하고 해당 도구 없이 계속했습니다.

서브에이전트가 도달할 수 있는 범위를 제한하려면 먼저 tools 필드를 좁혀서(예: Bash를 목록에서 제외) 또는 설정에서 거부 규칙을 설정합니다.

AskUserQuestion 도구 동작

Claude는 결정이나 명확화가 필요할 때 AskUserQuestion을 사용하여 객관식 질문을 제시합니다. 옵션을 선택하거나 Other 행 또는 메모 필드를 통해 직접 텍스트를 입력하여 답변합니다.

직접 텍스트를 입력하여 답변하면, Claude Code는 Claude가 작성한 내용을 따르도록 중립적인 표현으로 답변을 전달하며, 먼저 대기하거나 설명해 달라는 요청을 포함합니다.

질문 자동 계속 타임아웃

질문은 답변할 때까지 열려 있습니다. 답변하지 않은 질문이 결국 닫혀서 Claude가 사용자 없이 계속 진행되도록 하려면, askUserQuestionTimeout 설정을 60s, 5m, 또는 10m으로 설정합니다. 사용자 settings.json에서 또는 /config의 Question auto-continue timeout 행에서 설정할 수 있습니다.

질문이 입력 없이 그 시간 동안 유지되면, 대화 상자가 자동으로 닫힙니다. 이미 선택한 옵션을 제출하고 Claude에게 사용자가 키보드에서 떨어져 있을 수 있다고 알려주므로, Claude는 자신의 판단으로 진행하고 나중에 다시 질문할 수 있습니다. 마지막 20초 동안 카운트다운이 표시됩니다. 아무 키나 눌러 타이머를 다시 시작합니다. 포커스를 보고하는 터미널에서는 창으로 전환하면 타이머도 다시 시작됩니다.

타임아웃은 AskUserQuestion의 객관식 질문에만 적용됩니다. 계획 승인을 포함한 권한 프롬프트는 유휴 상태에서 자동으로 해결되지 않습니다.

Bash 도구 동작

Bash 도구는 각 명령을 별도의 프로세스에서 실행합니다.

명령 간에 유지되는 항목

• Claude가 주 세션에서 cd를 실행할 때, 새로운 작업 디렉토리는 프로젝트 디렉토리 내에 있거나 --add-dir, /add-dir 또는 설정의 additionalDirectories로 추가한 추가 작업 디렉토리 내에 있는 한 이후의 Bash 명령으로 이월됩니다. 서브에이전트 세션은 작업 디렉토리 변경을 절대 이월하지 않습니다.
  • cd가 해당 디렉토리 외부로 이동하면, Claude Code는 프로젝트 디렉토리로 재설정하고 도구 결과에 Shell cwd was reset to <dir>을 추가합니다.
  • 모든 Bash 명령이 프로젝트 디렉토리에서 시작하도록 이월을 비활성화하려면 CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1을 설정합니다.
• 환경 변수는 유지되지 않습니다. 한 명령의 export는 다음 명령에서 사용할 수 없습니다.
• 셸 시작 파일에 정의된 별칭과 셸 함수를 사용할 수 있습니다. 세션 시작 시, Claude Code는 셸에 따라 ~/.zshrc, ~/.bashrc 또는 ~/.profile을 소싱하고, 결과 별칭, 함수 및 셸 옵션을 캡처한 후 모든 Bash 명령에 적용합니다.

Claude Code를 시작하기 전에 virtualenv 또는 conda 환경을 활성화합니다. 환경 변수가 Bash 명령 간에 유지되도록 하려면, Claude Code를 시작하기 전에 CLAUDE_ENV_FILE을 셸 스크립트로 설정하거나 SessionStart 훅을 사용하여 동적으로 채웁니다.

타임아웃 및 출력 제한

각 명령은 타임아웃 하에서 실행되며, Claude가 관리합니다. 명령에 기본값보다 더 오래 필요할 때, 해당 호출로 timeout 매개변수를 전달합니다. 명령별 타임아웃을 설정하지 않습니다. 두 개의 환경 변수가 Claude가 받는 것을 제한합니다:

• BASH_DEFAULT_TIMEOUT_MS — Claude가 타임아웃을 전달하지 않을 때의 기본값입니다. 기본값은 2분입니다.
• BASH_MAX_TIMEOUT_MS — 기본값으로, Claude가 요청하는 것을 제한하는 상한을 설정합니다. 유효한 상한은 둘 중 더 큰 값이며, 기본값은 10분입니다.

출력 제한

Claude Code는 명령이 실행되는 동안 명령의 출력을 작업 파일로 스트리밍합니다. 출력이 5GB를 초과하는 명령은 중단됩니다. 명령이 완료되면, Claude Code는 아래에 설명된 읽기 창에서 해당 파일의 출력을 다시 읽습니다. 출력이 Claude에 인라인으로 도달하는 양은 Claude Code가 결과를 실패로 처리하는지 여부에 따라 달라집니다:

종료 코드 1로 끝나는 명령은 Claude Code가 해당 명령에 대해 종료 코드 1을 양성 결과로 인식할 때만 Bash 도구에 대한 유효한 결과로 계산됩니다: grep, rg, egrep, fgrep, find, diff, test 및 [, 그리고 git diff와 git grep. 종료 코드 1이 양성 정보 결과인 경우에도 다른 모든 명령은 실패로 계산됩니다: pgrep과 jq -e의 일치 항목 없음, cmp의 파일 차이.

BASH_MAX_OUTPUT_LENGTH는 Claude Code가 작업 파일에서 명령의 결과로 다시 읽는 출력의 문자 수를 설정합니다. 기본값은 30,000자이며, 최대 150,000자까지입니다. 명령이 정기적으로 해당 창을 초과할 때 이를 높입니다. 예를 들어 자세한 빌드 또는 전체 테스트 스위트 로그입니다. 이를 높이면 읽기 창이 확대되며, 이는 실패한 명령의 발췌가 잘리는 창이기도 합니다. 인라인 상한을 높이지 않습니다. 인라인 상한을 초과하는 유효한 결과는 이 변수와 관계없이 파일 경로와 미리보기로 도착합니다.

유효한 결과의 얼마나 많은 부분을 Claude가 인라인으로 받는지 변경하려면, 대신 bashOutputMaxChars 설정을 최대 128,000자까지 설정합니다. 인라인 상한과 읽기 창을 함께 크기 조정하며, Claude Code는 BASH_MAX_OUTPUT_LENGTH를 무시합니다. Claude Code v2.1.261 이상이 필요합니다.

백그라운드 명령

개발 서버 또는 감시 빌드와 같은 장기 실행 프로세스의 경우, Claude는 run_in_background: true를 설정하여 명령을 백그라운드 작업으로 시작하고 실행 중인 동안 계속 작업할 수 있습니다. /tasks로 백그라운드 작업을 나열하고 중지합니다. 거기서 또는 데스크톱 앱과 같은 연결된 클라이언트에서 중지한 후, Claude는 대기하지 않고 계속 진행합니다. 서브에이전트가 명령을 시작한 경우, 해당 서브에이전트가 계속 진행합니다.

포그라운드 서브에이전트가 시작한 명령은 해당 서브에이전트가 최종 응답을 제공할 때 중지됩니다. 주 대화 또는 백그라운드 서브에이전트가 시작한 명령은 최종 응답 후에도 계속 실행됩니다. -p 플래그가 있는 비대화형 모드에서, 백그라운드 명령은 실행의 최종 결과 직후에 종료됩니다.

명령이 완료되지 않고 타임아웃에 도달하면, Claude Code는 중지하지 않고 백그라운드로 이동합니다. Claude는 명령이 계속되는 동안 계속 작업합니다. Claude Code는 이동된 명령에 다른 백그라운드 명령과 동일한 수명 규칙을 적용하므로, 포그라운드 서브에이전트의 명령을 해당 서브에이전트의 최종 응답에서 여전히 종료합니다. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1을 설정하면 자동 백그라운드 처리 및 나머지 백그라운드 작업 기능을 비활성화합니다.

Claude Code는 세 가지 종류의 명령을 절대 자동 백그라운드 처리하지 않습니다. 대신 타임아웃에서 중지합니다:

• sleep으로 시작하는 명령입니다.
• 어디든지 git을 실행하는 명령입니다.
• Claude Code가 완전히 단순 명령으로 파싱할 수 없는 복합 명령입니다. Claude Code는 ${VAR}과 같은 매개변수 확장을 파싱 불가능으로 처리하므로, ; exit "${PIPESTATUS[0]}"로 끝나는 명령을 타임아웃에서 중지합니다. 해당 명령의 나머지가 파싱되더라도 말입니다.

백그라운드로 이동된 명령의 결과는 발생한 일을 나타냅니다:

• 타임아웃이 이동을 트리거할 때, 결과는 명시적으로 보고합니다: Command did not complete within its 120s timeout and was moved to the background, 초는 적용된 타임아웃과 일치하며, 작업 ID와 출력이 기록되는 파일의 경로가 뒤따릅니다.
• 백그라운드로 이동되는 명령 내의 cd, pushd, popd 또는 chdir은 절대 이월되지 않습니다. 결과는 Session cwd remains <dir>; directory changes made by the backgrounded command do not apply to subsequent commands.를 나타내므로, Claude는 발생하지 않은 디렉토리 변경에 대해 작동하지 않습니다.

Linux 및 WSL의 메모리 제한

Linux 및 WSL에서, CLAUDE_CODE_TOOL_MEMORY_LIMIT을 4G와 같은 크기로 설정하여 Bash, PowerShell 및 Monitor 도구 명령이 사용할 수 있는 메모리를 제한하므로, 하나의 폭주 빌드가 세션의 나머지 부분이 필요한 메모리를 차지할 수 없습니다. Claude Code v2.1.233 이상이 필요합니다. v2.1.246 이전에는 Monitor 도구 명령이 상한 외부에서 실행되었습니다.

• 크기를 바이트 수 또는 K, M, G 또는 T 접미사가 있는 것으로 작성합니다. 상한을 끄려면 0, off, false, no 또는 none을 설정합니다. Claude Code는 4e9와 같이 크기로 읽을 수 없는 다른 값을 무시합니다.
• Claude Code는 각 명령에 대해 별도로가 아니라 하나의 상한에 대해 세션의 모든 Bash, PowerShell 및 Monitor 명령을 계산합니다.
• Claude Code는 메모리 cgroup으로 상한을 적용합니다. cgroup을 설정할 수 없으면, 명령은 상한 없이 실행되며, claude --debug의 디버그 로그는 이유를 나타냅니다.
• Claude Code가 시작한 첫 번째 프로세스가 상한을 켜거나, 오프 값 또는 실패한 cgroup 설정으로 인해 꺼진 후, Claude Code는 다시 시작할 때까지 해당 결과를 유지합니다. 변경되거나 제거된 값 또는 고정된 설정을 적용하려면 claude를 다시 시작합니다.
• 명령이 상한 아래에 머물 수 없으면, 커널이 명령을 중단하며, 결과의 아무것도 상한을 명명하지 않습니다.

Claude Code는 또한 시작하는 다른 종류의 프로세스를 동일한 제한에 대해 계산할 수 있습니다. CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE를 상한에서 제외할 종류의 쉼표로 구분된 목록으로 설정합니다. Claude Code는 목록에 없는 모든 종류에 상한을 적용합니다. 모든 종류를 제한하려면 none으로 설정하거나, Bash, PowerShell 및 Monitor 도구 명령만 제한하려면 all-new로 설정합니다. Claude Code v2.1.246 이상이 필요합니다. 명명할 수 있는 종류:

• mcp: 로컬 MCP 서버
• lsp: 언어 서버
• hooks: 훅 명령
• plugin: 플러그인이 실행하는 명령
• helper: Claude Code의 자체 도우미 명령, 예를 들어 git
• agent: 자식 Claude Code 프로세스, 예를 들어 에이전트 팀원

나열하는 것이 무엇이든, 이러한 규칙이 적용됩니다:

• 알 수 없는 이름: Claude Code는 인식하지 못하는 이름을 무시합니다.
• Bash, PowerShell 및 Monitor: Claude Code는 나열하는 것이 무엇이든 Bash, PowerShell 및 Monitor 도구 명령을 상한 아래에 유지합니다.
• 변수 설정 해제: Claude Code는 Anthropic이 서버에서 제공하는 구성에서 다른 제한된 종류의 집합을 가져오며, 해당 집합은 시간이 지남에 따라 변할 수 있으므로, 변경되지 않는 집합이 필요할 때 변수를 설정합니다.
• 권한 게이팅 훅: 모든 종류가 제한되더라도, Claude Code는 작업을 차단하거나 결과를 변경할 수 있는 훅과 해당 훅이 호출하는 모든 MCP 서버를 상한에서 제외하므로, 커널이 권한 게이팅 훅을 중단하는 것이 차단하는 작업을 허용할 수 없습니다.

Edit 도구 동작

Edit 도구는 정확한 문자열 교체를 수행합니다. old_string과 new_string을 받아 첫 번째를 두 번째로 교체합니다. 정규식이나 유사 일치를 사용하지 않습니다.

편집을 적용하기 위해 세 가지 검사를 통과해야 합니다. 그 전에, Read 거부 규칙과 일치하는 경로는 거부되며, 여기에 새 파일을 만드는 것도 포함됩니다. 거부는 Claude Code v2.1.208 이상이 필요합니다.

• 편집 전 읽기: Claude는 편집하기 전에 현재 대화에서 파일을 읽으며, PARTIAL view 공지로 단축된 읽기는 계산되지 않습니다. Claude Opus 4.6, Claude Haiku 4.5 및 이전 모델은 항상 읽기를 요구합니다. 최신 모델은 읽기가 권한 프롬프트를 필요로 하지 않고 Read 도구를 사용할 수 있을 때 읽지 않은 파일을 편집할 수 있습니다.
• 일치: old_string은 파일에 정확히 작성된 대로 나타나야 합니다. 공백이나 들여쓰기의 단 한 글자 차이도 일치하지 않기에 충분합니다.
• 고유성: old_string은 정확히 한 번 나타나야 합니다. 두 번 이상 나타날 때, Claude는 한 번의 발생을 고정하기에 충분한 주변 컨텍스트가 있는 더 긴 문자열을 제공하거나, replace_all: true를 설정하여 모두 교체합니다.

Claude가 마지막으로 읽은 후 디스크에서 변경된 파일은 old_string이 현재 콘텐츠와 정확히 일치하고 명확하며 Claude Code가 프롬프트 없이 파일을 읽을 수 있을 때 여전히 편집할 수 있습니다. 파일의 현재 콘텐츠와 일치하면 이것이 안전하게 유지되며, 결과는 파일이 다른 변경 사항을 포함하고 있음을 기록하므로 Claude는 주변 콘텐츠에 따라 달라지는 편집 전에 다시 읽습니다. 다른 경우, 예를 들어 오래된 old_string 또는 replace_all 없이 두 번 이상 일치하는 경우, Claude는 편집하기 전에 파일을 다시 읽습니다. 읽지 않은 파일 및 변경된 파일의 완화된 처리는 Claude Code v2.1.208 이상이 필요합니다. 그 전에는 Claude Code가 대화에서 읽지 않았거나 읽은 후 디스크에서 변경된 파일에 대한 모든 편집을 거부했습니다.

Bash로 파일을 보는 것은 명령이 cat, nl, bat, batcat, head, tail, sed -n 'X,Yp', grep, egrep, fgrep 또는 rg일 때 단일 파일에 대해 파이프나 리디렉션이 없을 때 편집 전 읽기 요구 사항을 충족합니다. 파이프된 출력 및 기타 Bash 명령은 편집 전 읽기 검사에 계산되지 않습니다.

Bash로 파일을 보는 것은 권한이 아닌 편집 적격성에만 영향을 미칩니다. Read 및 Edit 권한 규칙에서 Read 및 Edit 거부 규칙이 적용되는 Bash 명령을 확인하십시오.

EndConversation 도구 동작

EndConversation 도구는 현재 세션을 종료합니다. Claude는 두 가지 상황에서만 이를 사용합니다:

• 지속적인 학대적 입력에 대한 최후의 수단으로, 대화를 다시 방향 지으려는 시도가 실패하고 이전 메시지에서 명확한 경고를 한 후
• 도구 시연을 명시적으로 요청하고 세션을 종료하고 싶다는 것을 확인할 때

일반적인 좌절감, 욕설, 또는 작업이 잘못되는 것은 해당하지 않으며, 유해한 콘텐츠 요청도 마찬가지입니다. Claude는 세션을 종료하는 대신 이를 거절합니다. Claude Code는 claude.ai와 동일한 접근 방식을 따르며, 드물게 채팅의 일부를 종료할 수 있습니다.

Claude가 대화형 세션을 종료한 후 세션이 잠깁니다. 새로운 프롬프트와 대부분의 명령은 Claude ended this conversation. Start a new session (or /clear) to continue.를 반환하며, /clear, /resume, /help, /exit, /feedback만 계속 실행됩니다. Claude Code는 세션의 트랜스크립트에 종료를 기록하므로, 종료된 세션을 재개하면 잠금이 복원됩니다. 세션의 기록은 삭제되지 않습니다.

비대화형 모드에서 -p 플래그를 사용하여 종료된 세션을 재개하면 오류가 발생하고 코드 1로 종료되므로, 스크립트는 종료된 실행을 성공으로 읽지 않습니다.

도구는 권한을 묻지 않으며, PreToolUse 훅은 이에 대해 실행되지 않습니다. 다른 도구가 남아 있는 동안 이를 차단할 수도 없습니다: EndConversation을 명명하는 거부 및 요청 규칙은 효과가 없으며, --disallowedTools도 --tools 목록도 이를 제거할 수 없습니다. 이 예외는 의도적입니다: 도구는 대화를 종료하는 것 외에는 아무것도 하지 않으며, 파일이나 데이터를 읽거나 수정하지 않으며, 이러한 종류의 보안 장치는 적용되는 세션이 이를 끌 수 없을 때만 유지됩니다. 거부 규칙이 다른 모든 도구를 제거하고 EndConversation도 일치할 때, "*"처럼, Claude Code는 허용 규칙이 EndConversation을 명시적으로 명명하지 않는 한 유일한 도구로 남기는 대신 이를 제거합니다. 다른 모든 도구를 제거하지만 EndConversation과 일치하지 않는 거부 목록은 이를 제자리에 둡니다.

서브에이전트는 절대 도구를 받지 않습니다. 메인 대화의 도구 목록을 공유하는 백그라운드 작업은 이를 보지만, 거기서 호출하면 아무것도 종료되지 않습니다.

도구는 다음의 모든 조건이 충족될 때만 나타납니다:

• 버전: Claude Code v2.1.213 이상.
• 모델: 세션의 모델이 Claude Opus 4.8, Claude Sonnet 5, Claude Fable 5, 또는 이들 중 하나의 최신 버전입니다.
• 표면: 대화형 터미널 세션, IDE의 통합 터미널에서의 claude 세션 포함, 이것이 JetBrains 플러그인이 실행되는 방식입니다. 다른 표면은 도구를 포함하지 않습니다:
  • 비대화형 -p 실행
  • Agent SDK TypeScript 및 Python 패키지를 통한 세션
  • VS Code 확장 패널, 자체 CLI를 번들로 제공합니다
  • GitHub Actions
  • 웹의 Claude Code
• 시작 모드: --bare 세션이 아닙니다. Bare 모드는 셸 및 파일 도구만 로드하므로 도구는 거기서 등록되지 않습니다.
• 제공자: Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform, Microsoft Foundry에서 사용할 수 없으며, 클라우드 게이트웨이를 통해 로그인한 세션에서도 사용할 수 없습니다.

Glob 도구 동작

Glob 도구는 이름 패턴으로 파일을 찾습니다. 재귀적 디렉토리 매칭을 위한 **를 포함한 표준 glob 구문을 지원합니다:

• **/*.js는 모든 깊이의 모든 .js 파일과 일치합니다
• src/**/*.ts는 src/ 아래의 모든 .ts 파일과 일치합니다
• *.{json,yaml}은 현재 디렉토리의 .json 및 .yaml 파일과 일치합니다

결과는 수정 시간순으로 정렬되며 100개 파일로 제한됩니다. 제한에 도달하면 Claude는 결과에서 잘림 플래그를 보고 패턴을 좁힐 수 있습니다.

Glob은 기본적으로 .gitignore를 존중하지 않으므로 gitignore된 파일을 추적된 파일과 함께 찾습니다. 이는 gitignore된 파일을 건너뛰는 Grep과 다릅니다. Glob이 .gitignore를 존중하도록 하려면 Claude Code를 시작하기 전에 CLAUDE_CODE_GLOB_NO_IGNORE=false를 설정하십시오.

Claude Code는 검색 디렉토리의 존재 여부를 확인하기 전에 Glob 호출에 대한 권한을 결정합니다. 여전히 작업 디렉토리 외부의 누락된 path에 대해 읽기 권한 확인을 실행하므로 경로에 대한 권한 프롬프트가 경로가 존재한다는 의미는 아닙니다.

null 바이트를 포함하는 pattern 또는 path 값은 Claude에 이를 제거하도록 요청하는 오류를 반환합니다.

Grep 도구 동작

Grep 도구는 파일 내용에서 패턴을 검색합니다. Glob이 파일 이름으로 파일을 찾는 곳에서 Grep은 파일 내부의 줄을 찾습니다.

Grep은 ripgrep을 기반으로 하며 POSIX grep이 아닌 ripgrep의 정규식 구문을 사용합니다. 정규식 메타문자를 포함하는 패턴은 이스케이프 처리가 필요합니다. 예를 들어 Go 코드에서 interface{}를 찾으려면 interface\{\} 패턴이 필요합니다.

ripgrep이 거부하는 패턴, glob 또는 파일 유형은 ripgrep의 진단을 포함하는 오류를 반환하므로 Claude가 입력을 수정하고 다시 검색할 수 있습니다. v2.1.208 이전에는 Claude Code가 거부된 입력을 검색된 텍스트가 대상 파일에 존재하더라도 오류 대신 No files found로 보고했습니다.

세 가지 출력 모드는 반환되는 내용을 제어합니다:

• files_with_matches: 파일 경로만, 줄 내용 없음. 이것이 기본값입니다.
• content: 파일 및 줄 번호가 있는 일치하는 줄. 도구의 offset 매개변수가 일치하는 패턴의 마지막 일치를 지나가리킬 때, Grep은 No entries at this offset을 반환하므로 Claude는 패턴이 일치하지 않는다고 결론짓는 대신 offset을 확대하거나 재설정합니다.
• count: 파일당 일치 개수, 그 다음 모든 일치하는 파일 전체의 합계. 합계는 도구의 head_limit 또는 offset 매개변수가 나열된 파일별 항목을 자르더라도 모든 일치를 포함합니다. v2.1.208 이전에는 합계가 나열된 항목만 합산했습니다.

Claude는 glob 매개변수(예: **/*.tsx)를 사용하여 파일별로 결과를 범위 지정하거나 type 매개변수(예: py 또는 rust)를 사용하여 언어별로 범위 지정할 수 있습니다. 기본적으로 패턴은 단일 줄 내에서 일치합니다. Claude는 multiline: true를 설정하여 줄 경계를 넘어 일치시킬 수 있습니다.

Grep은 .gitignore를 준수하므로 gitignore된 파일은 건너뜁니다. gitignore된 파일을 검색하려면 Claude가 해당 경로를 직접 전달합니다.

Claude Code는 검색 path가 존재하는지 확인하기 전에 Grep 호출에 대한 권한을 결정합니다. 여전히 작업 디렉터리 외부의 누락된 path에 대해 읽기 권한 확인을 실행하므로 경로에 대한 권한 프롬프트는 경로가 존재한다는 의미가 아닙니다.

LSP 도구 동작

LSP 도구는 실행 중인 언어 서버로부터 Claude에 코드 인텔리전스를 제공합니다. 각 파일 편집 후, 자동으로 타입 오류 및 경고를 보고하므로 Claude는 별도의 빌드 단계 없이 문제를 해결할 수 있습니다. Claude는 또한 코드를 탐색하기 위해 직접 호출할 수 있습니다:

• 기호의 정의로 이동
• 기호에 대한 모든 참조 찾기
• 위치에서 타입 정보 가져오기
• 파일의 기호 나열
• 작업 영역 전체에서 이름으로 기호 검색
• 인터페이스의 구현 찾기
• 호출 계층 추적

Claude Code는 언어에 대한 코드 인텔리전스 플러그인을 설치할 때까지 도구를 비활성 상태로 유지합니다. 클라우드 세션에서 Claude Code는 플러그인 언어 서버를 시작하지 않으므로 LSP 도구는 그곳에서 비활성 상태로 유지됩니다. Claude Code는 플러그인에서 언어 서버의 구성을 가져오며, 사용자가 서버 바이너리를 직접 설치합니다.

Claude Code는 언어 서버를 시작할 수 없는 파일에 대한 각 LSP 호출에 대해 오류 결과를 반환합니다.

Monitor 도구

Monitor 도구를 사용하면 Claude가 대화를 일시 중지하지 않고 백그라운드에서 무언가를 감시하고 변경 시 반응할 수 있습니다. Claude에게 다음을 요청할 수 있습니다:

• 로그 파일을 추적하고 오류가 나타나면 플래그 지정
• PR 또는 CI 작업을 폴링하고 상태 변경 시 보고
• 디렉터리의 파일 변경 감시
• 지정한 장시간 실행 스크립트의 출력 추적
• WebSocket 피드에 연결하고 각 메시지가 도착할 때마다 보고

대부분의 감시의 경우 Claude는 작은 스크립트를 작성하고 백그라운드에서 실행한 후 각 출력 라인을 도착할 때마다 수신합니다. 이미 이벤트를 푸시하는 서버의 경우 Claude는 스크립트를 실행하는 대신 WebSocket을 열 수 있습니다.

사용자는 동일한 세션에서 계속 작업하고 Claude는 이벤트가 도착할 때 개입합니다.

Claude에게 취소를 요청하거나 세션을 종료하여 모니터를 중지합니다. 모니터를 시작한 subagent를 중지하면(예: /tasks에서) 해당 모니터도 함께 중지됩니다.

Monitor가 명령을 실행할 때 Bash와 동일한 권한 규칙을 사용하므로 Bash에 대해 설정한 allow 및 deny 패턴이 여기에도 적용됩니다. 자동 모드가 활성화되어 있는 동안 Claude Code는 Monitor 자체의 이름을 지정하는 allow 규칙과 함께 삭제되는 다른 광범위한 allow 규칙을 적용하지 않으므로 분류기는 Monitor 명령을 Bash 명령과 동일한 방식으로 검토합니다.

WebSocket 소스에는 자체 승인 프롬프트가 있으며, 분류기도 자동 모드에서 이를 결정합니다.

이 도구는 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서 사용할 수 없습니다. DISABLE_TELEMETRY 또는 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC이 설정된 경우에도 사용할 수 없습니다.

플러그인은 Claude에게 시작을 요청하는 대신 플러그인이 활성화될 때 자동으로 시작되는 모니터를 선언할 수 있습니다. 플러그인 모니터를 참조하세요.

WebSocket 소스

서버가 이미 WebSocket을 통해 이벤트를 푸시하는 경우 Claude는 폴링 스크립트를 작성하는 대신 직접 연결할 수 있습니다. 각 종류의 소켓 활동은 이벤트가 되거나 감시를 종료합니다:

• 텍스트 메시지: 각각이 하나의 이벤트가 되며, 메시지가 여러 줄에 걸쳐 있어도 마찬가지입니다.
• 바이너리 메시지: 통과하지 않습니다. Claude는 [binary frame, 512 bytes]와 같은 자리 표시자 라인을 수신합니다.
• 1 MiB보다 큰 메시지: 감시가 종료되므로 필터링된 피드가 있는 경우 구독하세요.
• 소켓 종료: 감시가 종료되고 Claude는 종료 코드를 수신합니다.

WebSocket 감시는 command 대신 ws 입력을 사용하며, 단일 Monitor 호출은 둘을 결합할 수 없습니다. ws 입력에는 두 가지 필드가 있습니다:

timeout_ms 및 persistent 입력은 명령에서와 동일하게 작동합니다: persistent가 설정되지 않으면 감시가 기한에 종료되고 TaskStop이 조기에 취소합니다.

WebSocket을 열면 승인을 요청합니다. 자동 모드에서는 분류기가 대신 결정합니다. 프롬프트는 동일한 호스트에 대해 향후 프롬프트를 건너뛸 수 있는 옵션을 제공하지 않습니다.

Claude Code는 프라이빗, 링크-로컬 또는 클라우드 메타데이터 주소를 가리키는 URL을 거부하며, 이는 해당 주소로 확인되는 호스트 이름도 포함합니다. 또한 sandbox.network.deniedDomains의 호스트를 거부하고, 관리 설정에서 allowManagedDomainsOnly가 설정된 경우 관리 허용 목록 외부의 모든 호스트를 거부합니다.

NotebookEdit 도구 동작

NotebookEdit은 cell_id로 대상 셀을 지정하여 Jupyter 노트북을 한 번에 한 셀씩 수정합니다. 일반 파일에서 Edit처럼 노트북 전체에서 문자열 교체를 수행하지 않습니다.

세 가지 편집 모드는 대상 셀에 발생하는 일을 제어합니다:

• replace: 셀의 소스를 덮어씁니다. 이것이 기본값입니다.
• insert: 대상 후에 새 셀을 추가합니다. cell_id가 없으면, 새 셀은 노트북의 시작 부분으로 이동합니다. cell_type을 code 또는 markdown으로 설정해야 합니다.
• delete: 대상 셀을 제거합니다.

권한 규칙은 Edit(...) 경로 형식을 사용합니다. Edit(notebooks/**)와 같은 규칙은 해당 디렉토리의 파일에 대한 NotebookEdit 호출을 포함합니다.

PowerShell 도구

PowerShell 도구를 사용하면 Claude가 PowerShell 명령을 기본적으로 실행할 수 있습니다. Windows에서는 이것이 명령이 Git Bash를 통해 라우팅되는 대신 PowerShell에서 실행됨을 의미합니다. 도구가 사용 가능해지는 방식은 플랫폼에 따라 다릅니다.

• Git Bash가 없는 Windows: 도구가 자동으로 활성화됩니다.
• Git Bash가 설치된 Windows: 도구는 claude.ai 및 Console 계정에서 기본적으로 켜져 있습니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry 세션에서 활성화하려면 CLAUDE_CODE_USE_POWERSHELL_TOOL=1을 설정하거나, 끄려면 0을 설정합니다.
• Linux, macOS 및 WSL: 도구는 선택 사항입니다.

PreToolUse hooks는 도구의 명령 문자열을 tool_input.command에서 수신하며, Bash 도구와 동일한 필드를 가집니다.

셸 명령을 검사하는 hooks에서 Bash|PowerShell과 일치시킵니다. PowerShell hook 입력 섹션은 Bash만 일치시키는 것이 충분하지 않은 이유를 설명합니다.

PowerShell 도구 활성화

환경 또는 settings.json에서 CLAUDE_CODE_USE_POWERSHELL_TOOL=1을 설정합니다.

{
  "env": {
    "CLAUDE_CODE_USE_POWERSHELL_TOOL": "1"
  }
}

Windows에서는 도구를 끄려면 변수를 0으로 설정합니다. Linux, macOS 및 WSL에서는 도구에 PowerShell 7 이상이 필요합니다. pwsh를 설치하고 PATH에 있는지 확인합니다.

Windows에서 Claude Code는 PowerShell 7+에 대해 pwsh.exe를 자동으로 감지하며, PowerShell 5.1에 대해 powershell.exe로 폴백됩니다. 도구가 활성화되면 Claude는 PowerShell을 기본 셸로 취급합니다. Bash 도구는 Git Bash가 설치되어 있을 때 POSIX 스크립트에 사용 가능하게 유지됩니다.

Claude Code는 프로세스 범위에서만 -ExecutionPolicy Bypass를 사용하여 PowerShell을 생성하므로, .ps1 스크립트 및 모듈 가져오기는 머신의 정책을 변경하지 않고도 기본 Windows 설치에서 작동합니다. 프로세스 범위 바이패스는 Group Policy MachinePolicy 또는 UserPolicy를 재정의하지 않으므로, 엔터프라이즈 정책이 여전히 적용됩니다. 머신의 유효한 실행 정책을 대신 존중하려면 CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1을 설정합니다.

설정, hooks 및 skills의 셸 선택

세 가지 추가 설정이 PowerShell이 사용되는 위치를 제어합니다.

• settings.json의 "defaultShell": "powershell": 대화형 ! 명령을 PowerShell을 통해 라우팅합니다. PowerShell 도구가 활성화되어야 합니다.
• 개별 command hooks의 "shell": "powershell": 해당 hook을 PowerShell에서 실행합니다. Hooks는 PowerShell을 직접 생성하므로, CLAUDE_CODE_USE_POWERSHELL_TOOL과 관계없이 작동합니다.
• skill frontmatter의 shell: powershell: !`command` 블록을 PowerShell에서 실행합니다. PowerShell 도구가 활성화되어야 합니다.

Bash 도구 섹션에서 설명한 동일한 주 세션 작업 디렉토리 재설정 동작이 PowerShell 명령에 적용되며, CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR 환경 변수를 포함합니다.

v2.1.196부터 grep, rg, egrep, fgrep, findstr 및 git grep의 종료 코드 1은 일치하는 항목이 없음을 의미합니다. git diff의 종료 코드 1은 차이가 존재함을 의미합니다. 두 결과 모두 Claude에 명령 실패로 보고되지 않습니다. robocopy의 경우, 종료 코드 0부터 7까지는 복사된 파일 또는 감지된 추가 파일과 같은 정보 결과입니다. 종료 코드 8 이상은 실패로 계산됩니다.

Windows 인코딩 및 종료 코드

Windows에서 다음 PowerShell 인코딩 및 종료 코드 동작에는 Claude Code v2.1.214 이상이 필요합니다.

• >와 >>를 사용한 리디렉션은 PowerShell 5.1에서 UTF-8 파일을 작성합니다.
• Claude Code는 기본 명령의 표준 입력으로 파이프된 텍스트를 UTF-8로 인코딩합니다.
• Claude Code는 ANSI 이스케이프 시퀀스 없이 오류 출력을 캡처합니다.
• 자식 프로세스가 표준 입력을 대기하는 명령은 행(hang)되는 대신 파일 끝을 수신합니다.
• where.exe의 종료 코드 1은 일치하는 항목이 없음을 의미하고, fc.exe 및 diff.exe에서는 파일이 다름을 의미하므로, 명령이 출력을 생성할 때 Claude Code는 해당 종료 코드를 명령 오류가 아닌 유효한 부정적 답변으로 취급합니다. Claude Code는 여전히 where.exe /Q 또는 $null로의 리디렉션과 같은 침묵된 형식을 종료 코드 1에서 실패로 보고합니다.

v2.1.214 이전에는 PowerShell 5.1의 >가 UTF-16LE 파일을 작성했고, 비ASCII 파이프된 입력은 ?로 도착했으며, Python 스크립트는 비ASCII 문자를 인쇄할 때 UnicodeEncodeError로 충돌할 수 있었습니다.

미리보기 제한 사항

PowerShell 도구는 미리보기 중에 다음과 같은 알려진 제한 사항이 있습니다.

• PowerShell 프로필이 로드되지 않습니다.
• Windows에서는 샌드박싱이 지원되지 않습니다.

Read 도구 동작

Read 도구는 파일 경로를 받아 줄 번호와 함께 내용을 반환합니다. Claude는 항상 절대 경로를 전달하도록 지시됩니다.

기본적으로 Read는 파일의 시작 부분에서 반환합니다. 전체 파일 읽기가 토큰 제한을 초과하면 Read는 첫 번째 페이지를 PARTIAL view 공지와 함께 반환하며, 이는 Claude가 받은 파일의 양과 offset 및 limit을 사용하여 더 읽는 방법을 알려줍니다. 명시적 offset 또는 limit을 전달하고 여전히 토큰 제한을 초과하는 읽기는 오류를 반환합니다.

명시적 limit이 있는 읽기는 선택된 줄이 토큰 제한에 맞을 수 있는 것을 초과하는 즉시 중지되고 나머지 범위를 로드하지 않고 오류를 반환합니다. 오류는 Claude에게 더 작은 limit을 사용하거나, 단일 줄이 그렇게 큰 경우에는 대신 Grep으로 특정 내용을 검색하도록 지시합니다. v2.1.208 이전에는 Claude Code가 전체 범위를 메모리에 로드한 후 거부했으므로, 매우 긴 단일 줄이 있는 파일을 읽으면 메모리 부족이 발생할 수 있었습니다.

빈 파일을 읽으면 파일이 존재하지만 내용이 비어 있다는 공지가 반환되고, 마지막 줄을 지난 offset은 파일의 줄 수를 나타내는 공지를 반환합니다. v2.1.208 이전에는 빈 파일을 읽으면 끝을 지난 공지가 반환되었습니다.

Read는 일반 텍스트 이상의 여러 파일 유형을 처리합니다:

• 이미지: PNG, JPG 및 기타 이미지 형식은 원본 바이트가 아닌 Claude가 볼 수 있는 시각적 콘텐츠로 반환됩니다. Claude Code는 모델의 이미지 크기 제한에 맞추기 위해 큰 이미지를 크기 조정하고 재압축하므로, Claude는 큰 스크린샷의 축소된 버전을 볼 수 있습니다. v2.1.196부터 크기 조정 후에도 500KB보다 큰 이미지는 픽셀 치수는 변경하지 않고 품질을 낮춘 JPEG로 다시 인코딩됩니다. Claude가 큰 이미지에서 세밀한 픽셀 수준의 세부 정보를 놓친 경우, 예를 들어 ImageMagick을 통해 Bash로 관심 영역을 먼저 자르도록 요청하십시오.
• PDF: Claude는 짧은 .pdf 파일을 전체적으로 읽습니다. 10페이지보다 긴 PDF의 경우, pages 매개변수(예: "1-5")를 사용하여 범위로 읽으며, 한 번에 최대 20페이지까지 읽습니다.
• Jupyter 노트북: .ipynb 파일은 코드, 마크다운 및 시각화를 포함한 모든 셀과 해당 출력을 반환합니다. Claude Code는 100MB를 초과하는 노트북 파일을 읽기를 거부합니다. 오류는 Claude에게 셀 슬라이스와 같은 노트북의 일부를 읽는 방법을 알려주며, 셸 명령을 사용합니다.

Read는 디렉토리가 아닌 파일만 읽습니다. Claude는 ls와 같은 셸 명령을 사용하여 디렉토리 내용을 나열합니다.

SendFeedback 도구 동작

Claude가 작성한 피드백은 Claude Code에 대해 Claude가 사용자를 위해 작성하는 피드백 보고서입니다. Claude Code v2.1.238 이상이 필요합니다. Claude Code는 각 초안을 사용자의 머신에 ~/.claude/feedback/drafts/ 아래에 저장하며, SendFeedback 도구를 사용하여 초안을 전송할 때까지 Anthropic에 아무것도 전달되지 않습니다. Claude는 다음의 경우에 SendFeedback 도구로 초안을 작성합니다:

• 도구 또는 명령이 계속 실패하는 경우
• 사용자가 요청한 작업을 도와줄 수 없는 경우
• 사용자가 Claude가 한 실수를 지적하거나 Claude가 실수를 발견한 경우
• 사용자가 피드백을 제출하도록 요청하는 경우

Claude가 초안을 작성할 때 표시되는 내용

Claude가 초안을 대기열에 추가한 후, 프롬프트 위에 초안의 제목이 있는 카드가 표시됩니다. 1을 눌러 초안을 검토하고, 2를 두 번 눌러 작성된 대로 전송하거나, 0을 눌러 해제할 수 있습니다. 해제된 초안은 대기열에 남아 있습니다. 카드를 해제한 후 Claude Code는 Claude가 작성한 피드백을 끌 것인지 묻습니다. 두 번 거절하면 더 이상 묻지 않습니다.

기본적으로 한 세션에서 최대 3개의 카드가 표시됩니다. Anthropic은 릴리스 없이 서버에서 이 제한을 조정할 수 있습니다. 제한 이후 및 feedbackDrafts를 quiet으로 설정할 때마다, 프롬프트 바닥글에 대기 중인 초안의 개수만 표시됩니다.

초안 검토 및 편집

인수 없이 /feedback을 실행하여 대기열을 엽니다. 카드를 해제했거나 본 적이 없는 초안을 포함하여 모든 세션의 모든 대기 중인 초안을 나열합니다. 초안을 선택하여 검토를 위해 열면 다음을 수행할 수 있습니다:

• 제목, 영역 및 세부 정보 편집
• 전사본 전송을 yes 또는 no로 설정합니다. Claude가 초안을 대기열에 추가한 세션의 전사본을 여전히 사용할 수 있을 때, yes로 시작되어 해당 대화를 Anthropic에 전송합니다. no는 보고서만 전송합니다.
• 초안을 전송하거나, 삭제하거나, 나중을 위해 대기열에 남겨둡니다.

대신 직접 보고서를 작성하려면 w를 눌러 표준 피드백 대화를 엽니다. /feedback 뒤에 텍스트가 있거나 /bug를 사용하면 해당 대화를 직접 엽니다.

초안 전송

초안을 전송하면 Claude Code는 /feedback 보고서와 동일한 방식으로 제출하며, 동일한 보존을 사용하고 머신에서 초안을 삭제합니다. 카드에서 전송하면 ✓ Sent가 표시됩니다. 대기열에서 전송하면 영수증 ID와 함께 닫힙니다.

보고서에는 다음이 포함됩니다:

• 사용자의 제목, 영역 및 세부 정보
• Claude Code 버전, 운영 체제 및 모델과 같은 환경 정보
• 최근 API 요청의 ID
• 검토 화면에서 전사본 전송을 yes로 설정한 경우의 대화 전사본입니다. 카드에서 전송하면 전사본이 포함되지 않습니다.

Claude Code는 전사본을 찾을 수 있도록 로컬 초안에 작업 디렉토리를 유지하며, 디렉토리를 전송하지 않습니다.

영구 데이터 보존 정책이 없는 조직에서 Claude Code는 /feedback과 마찬가지로 도구를 제외합니다. 그러한 조직의 세션에서 여전히 도구를 제공하는 경우, 초안은 머신에 남아 있으며 전송은 Feedback collection is not available for organizations with custom data retention policies. 오류로 실패합니다.

초안 삭제 또는 유지

초안을 삭제하면 Claude Code는 머신에서 초안을 삭제합니다. 대기열에 남겨둔 초안은 30일 후 또는 더 짧을 때 cleanupPeriodDays가 지난 후 만료됩니다. 대기열은 모든 세션에서 10개의 초안을 보유하며, Claude가 11번째 초안을 대기열에 추가하면 Claude Code는 가장 오래된 초안을 삭제합니다. 세션의 초안이 여전히 대기열에 있을 때 /exit을 실행하면 Claude Code는 종료하기 전에 초안을 검토할 것인지 삭제할 것인지 묻습니다.

Claude가 작성한 피드백 끄기

/config에서 Claude가 작성한 피드백을 off로 설정하면 feedbackDrafts 설정이 작성되거나, 한 세션 동안 CLAUDE_CODE_SEND_FEEDBACK=0을 설정합니다. 둘 중 하나를 사용하면 Claude는 초안을 대기열에 추가할 수 없습니다. 카드 없이 초안 작성을 계속하려면 feedbackDrafts를 quiet으로 설정합니다. 관리자는 관리 설정에서 feedbackDrafts를 설정할 수 있으며, 이는 사용자의 설정보다 우선합니다.

Claude가 작성한 피드백이 없는 세션

Claude Code는 Claude API를 사용하는 머신의 대화형 터미널 세션에 도구를 포함합니다. 다음에서는 도구를 제외합니다:

• 대기열을 검토할 화면이 없는 비대화형 -p 실행 및 Agent SDK 세션
• 머신의 대기열에 쓸 수 없는 Claude Code on the web과 같은 클라우드 세션
• Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform 또는 Microsoft Foundry의 세션
• CLAUDE_CODE_SEND_FEEDBACK=0 또는 DISABLE_FEEDBACK_COMMAND=1을 설정하거나, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC을 비어 있지 않은 값으로 설정하거나, 기능 플래그 가져오기를 끈 세션
• 제품 피드백을 끈 조직 및 영구 데이터 보존 정책이 없는 조직

Task 도구 가용성

Claude Code v2.1.233 이상에서는 다음 도구들이 Opus 4.8, Sonnet 5, Fable 5, Mythos 5 또는 이후 버전의 해당 제품군에서 사용할 수 없습니다(옵트인하지 않는 한): TodoWrite, TaskCreate, TaskGet, TaskUpdate, 및 TaskList. 이러한 모델들은 작성된 체크리스트 없이 다단계 작업을 추적하며, 도구의 정의와 알림이 컨텍스트를 차지하므로 Claude Code는 이들을 제외합니다. 이들이 없으면 Claude는 작업 중에 작업 목록에 아무것도 추가하지 않습니다. Opus 4.7과 같은 다른 모델에서는 Claude Code가 기본적으로 4개의 Task 도구를 제공하며, CLAUDE_CODE_ENABLE_TASKS=0을 설정할 때만 TodoWrite를 제공합니다.

나열된 모델 중 하나에서 이러한 도구를 사용하려면 다음 중 하나를 수행하십시오:

• Claude Code를 시작하기 전에 CLAUDE_CODE_ENABLE_TODO_TOOLS=1을 내보내십시오. 예를 들어 CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude. Claude Code는 모든 모델과 모든 공급자에서 동일한 도구를 제공합니다
• --allowedTools에서 도구 중 하나의 이름을 지정하십시오. 예를 들어 claude --allowedTools TaskCreate
• --tools에 도구를 나열하십시오. 이는 세션의 기본 제공 도구를 명시된 도구로 제한합니다. 사용하는 다른 기본 제공 도구와 함께 원하는 도구를 포함하십시오
• Agent SDK에서 allowedTools 및 tools 옵션은 두 플래그와 동일한 방식으로 작동합니다

백그라운드 세션과 웹의 Claude Code에서는 Claude Code가 나열된 모든 모델에서 동일한 도구를 제공합니다.

Claude Code는 세션에 도구가 있을 때만 서브에이전트에 도구를 제공하며, 서브에이전트가 다른 모델을 실행하더라도 마찬가지입니다. 프로세스 내 에이전트 팀 팀원은 세션을 동일한 방식으로 따르지만, 분할 창의 자체 팀원은 별도의 Claude Code 프로세스로 실행되므로 자체 모델이 결정합니다. Task 도구가 없으면 에이전트는 공유 작업 목록 대신 메시지를 통해 팀과 조정합니다.

WebFetch 도구 동작

WebFetch는 URL과 추출할 내용을 설명하는 프롬프트를 받습니다. 페이지를 가져오고, 서버가 HTML을 반환할 때 응답을 Markdown으로 변환한 후, 작은 빠른 모델을 사용하여 프롬프트를 콘텐츠에 대해 실행합니다. 대부분의 가져오기에서 Claude는 원본 페이지가 아닌 해당 모델의 답변을 받습니다. 변환 단계는 구성할 수 없습니다.

이는 WebFetch가 설계상 손실이 있다는 의미입니다. 추출 프롬프트가 Claude에 도달하는 내용을 결정하므로, 페이지가 무언가를 언급하지 않는다고 말하는 결과는 프롬프트가 그것을 묻지 않았다는 의미일 수 있습니다. Claude에 더 구체적인 프롬프트로 다시 가져오도록 요청하거나, 처리되지 않은 페이지를 위해 Bash를 통해 curl을 사용하십시오.

몇 가지 동작이 Claude가 받는 응답을 형성합니다:

• HTTP URL은 자동으로 HTTPS로 업그레이드됩니다.
• 큰 페이지는 처리 전에 고정된 문자 제한으로 잘립니다.
• WebFetch는 기본적으로 각 응답을 15분 동안 캐시하므로, 동일한 URL의 반복된 가져오기가 빠르게 반환됩니다. Claude Code v2.1.233 이상에서는 CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS를 설정하여 WebFetch가 각 응답을 유지하는 기간을 변경할 수 있습니다.
• URL이 다른 호스트로 리디렉션될 때, WebFetch는 원본 URL과 리디렉션 대상을 이름으로 지정하는 텍스트 결과를 반환하고 따라가지 않습니다. 그러면 Claude는 두 번째 WebFetch 호출로 새 URL을 가져옵니다.
• 추출 단계가 과부하 API에 도달하면, Claude Code는 백오프로 재시도합니다. 여전히 실패하는 가져오기는 오류 결과를 반환합니다. v2.1.212 이전에는 API 오류 텍스트가 추출된 페이지 콘텐츠인 것처럼 Claude에 도달할 수 있었습니다.

Manual 및 acceptEdits 권한 모드에서, WebFetch는 가져오기 전에 프롬프트를 표시합니다. 단, 권한 규칙이 이미 허용하거나 거부하는 도메인과 프롬프트 없이 가져오는 사전 승인된 문서 도메인의 기본 제공 집합은 제외됩니다. 규칙이 허용하는 것이 무엇이든, 가져오기는 먼저 WebFetch 도메인 안전 검사를 통과합니다. 해당 섹션에서는 검사가 전송하는 내용과 이를 건너뛰는 설정을 다룹니다. 프롬프트는 세 가지 옵션을 제공합니다:

• Yes: 이 가져오기만 승인합니다. 다음 WebFetch 호출은 동일한 도메인이더라도 다시 프롬프트를 표시합니다.
• Yes, and don't ask again for <domain>: 가져오기를 승인하고 해당 도메인에 대한 WebFetch(domain:...) 허용 규칙을 해당 저장소의 .claude/settings.local.json에 저장합니다. 저장된 승인이 지속되는 방식을 참조하십시오. 조직이 allowManagedPermissionRulesOnly를 설정하면, Claude Code는 이 옵션을 숨깁니다.
• No, and tell Claude what to do differently: 가져오기를 거부합니다.

프롬프트 없이 미리 도메인을 허용하려면, WebFetch(domain:example.com)과 같은 허용 규칙을 추가하십시오. WebFetch(domain:*)는 모든 도메인을 허용합니다. auto 및 bypassPermissions 권한 모드는 명시적 ask 규칙이 일치하는 도메인을 제외하고 프롬프트를 건너뜁니다.

deny, ask 또는 allow의 명시적 WebFetch(domain:...) 규칙은 사전 승인된 집합보다 우선하므로, 사전 승인된 도메인을 차단하거나 이에 대한 프롬프트를 요구할 수 있습니다.

WebFetch는 Claude-User로 시작하는 User-Agent 헤더와 콘텐츠 협상을 지원하는 서버가 Markdown을 직접 반환할 수 있도록 HTML보다 Markdown을 선호하는 Accept 헤더를 설정합니다.

샌드박스된 명령은 WebFetch의 사전 승인된 문서 도메인의 기본 제공 집합을 상속하지 않습니다. 샌드박스된 명령이 프롬프트 없이 도메인에 도달하도록 하려면, 도메인을 allowedDomains에 추가하거나 WebFetch(domain:...) 규칙으로 허용하십시오. 샌드박스도 이를 준수합니다. WebFetch는 반대로 샌드박스 허용 목록을 읽지 않으므로, 샌드박스 또는 조직 네트워크 허용 목록에 도메인을 추가해도 WebFetch가 이에 대해 프롬프트를 표시하는 것을 중단하지 않습니다.

WebSearch 도구 동작

WebSearch는 Anthropic의 웹 검색 백엔드에 대해 쿼리를 실행하고 결과 제목과 URL을 반환합니다. 결과 페이지를 가져오지는 않습니다. Claude가 검색 결과에서 찾은 페이지를 읽으려면 WebFetch로 후속 조치를 합니다.

이 도구는 호출당 최대 8개의 백엔드 검색을 실행하여 결과를 반환하기 전에 검색을 내부적으로 개선할 수 있습니다. Claude는 allowed_domains으로 특정 호스트만 포함하거나 blocked_domains으로 제외하여 결과의 범위를 지정할 수 있습니다. 두 목록은 단일 호출에서 결합할 수 없습니다.

검색 요청이 과부하 상태의 API에 도달하면 Claude Code는 백오프를 사용하여 재시도합니다. 여전히 실패하는 호출은 오류 결과를 반환합니다. v2.1.212 이전에는 API 오류 텍스트가 검색 결과인 것처럼 Claude에 도달할 수 있었습니다.

WebSearch 권한 규칙은 지정자를 사용하지 않습니다. allow 또는 deny의 단순한 WebSearch 항목이 유일한 형식입니다.

검색 백엔드는 구성할 수 없습니다. 다른 공급자로 검색하려면 검색 도구를 노출하는 MCP 서버를 추가합니다.

세션 검색 제한

세션은 최대 200개의 WebSearch 호출을 수행할 수 있으며, 이는 주 대화와 생성하는 모든 하위 에이전트에서 계산되므로 병렬 연구 팬아웃에서 수행한 검색도 동일한 제한에 포함됩니다. 이 제한에는 Claude Code v2.1.212 이상이 필요합니다. Claude가 제한에 도달하면 추가 호출은 재시도를 유도할 오류 대신 Claude에 이미 수집한 정보로 계속 진행하도록 지시하는 알림을 반환합니다. 사용자는 알림을 볼 수 없습니다. 제한된 호출은 대화에 아무것도 하지 않은 검색으로 표시되며, Claude에 더 많은 검색이 필요한 경우 알림은 제한을 높이도록 요청하도록 지시합니다.

CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION 환경 변수를 설정하여 제한을 변경합니다. 양의 정수를 허용하므로 제한을 높일 수 있지만 끌 수는 없습니다. /clear를 실행하면 개수가 재설정됩니다. 실행 중인 워크플로우와 같이 여전히 하위 에이전트를 생성할 수 있는 작업이 명확한 후에도 남아 있으면 개수가 대신 이월됩니다.

Write 도구 동작

Write 도구는 새 파일을 생성하거나 기존 파일을 제공된 전체 콘텐츠로 덮어씁니다. 추가하거나 병합하지 않습니다.

Claude가 기존 파일을 덮어쓰기 전에 현재 대화에서 읽어야 하는지 여부는 모델과 파일에 따라 다릅니다.

• Claude Opus 4.6, Claude Haiku 4.5 및 이전 모델은 항상 읽기를 요구하므로, 읽지 않은 기존 파일에 대한 Write는 오류로 실패합니다.
• 최신 모델은 읽기-편집 전 동작과 동일한 조건에서 이 세션에서 읽지 않은 파일을 덮어쓸 수 있습니다. 읽기에 권한 프롬프트가 필요하지 않고 Read 도구를 사용할 수 있습니다.
• Jupyter 노트북 및 PARTIAL view 공지가 있는 부분적으로만 읽은 파일은 모든 모델에서 읽기를 요구합니다.

이 제약은 새 파일에는 적용되지 않습니다. v2.1.228 이전에는 모든 모델이 기존 파일을 덮어쓰기 전에 읽기를 요구했습니다.

Bash를 사용하여 파일을 보는 것도 Edit 도구 동작에 설명된 동일한 규칙에 따라 이 요구사항을 충족합니다.

기존 파일에 대한 부분적 변경의 경우 Claude는 Write 대신 Edit을 사용합니다.

사용 가능한 도구 확인

정확한 도구 세트는 제공자, 플랫폼 및 설정에 따라 다릅니다. 실행 중인 세션에서 로드된 항목을 확인하려면 Claude에 직접 문의합니다:

What tools do you have access to?

Claude는 대화형 요약을 제공합니다. 정확한 MCP 도구 이름의 경우 /mcp를 실행합니다.

참고 항목

• MCP 서버: 외부 서버를 연결하여 사용자 정의 도구 추가
• 권한: 권한 시스템, 규칙 구문, 도구별 패턴
• Subagents: subagent에 대한 도구 접근 구성
• Hooks: 도구 실행 전후에 사용자 정의 명령 실행