SpyBara
Go Premium

tools-reference.md 2026-10-22 22:58 UTC to 2026-10-23 22:59 UTC

This page contains 151 additions and 142 deletions.

2026
Thu 1 23:59 Fri 2 22:59 Sun 4 23:58 Tue 6 23:59 Thu 8 22:58 Fri 9 23:02 Sat 10 23:01 Tue 13 23:57 Wed 14 22:58 Mon 19 23:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Sun 25 23:58 Fri 30 23:01

도구 참조

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

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

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

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

[!NOTE]

자동 모드에서 분류기가 대부분의 권한 프롬프트를 사용자 대신 결정합니다. 권한 필요 열은 작업 디렉토리 내의 경로에 대해 수동 모드에서 도구가 프롬프트하는지 여부를 보여줍니다. Read, Grep 및 Glob을 포함한 파일 액세스 도구는 아니오로 표시되지만 작업 디렉토리 및 추가 디렉토리 외부의 경로에 대해 여전히 프롬프트합니다. Bash는 예로 표시되지만 프롬프트 없이 기본 제공 읽기 전용 명령 세트를 실행합니다.

도구 설명 권한 필요
Agent 작업을 처리하기 위해 자체 컨텍스트 윈도우가 있는 서브에이전트를 생성합니다. 에이전트 팀이 활성화된 경우, name을 전달하는 호출은 팀원을 시작할 수 있습니다. Agent 도구 동작을 참조하세요 아니오
Artifact HTML 또는 Markdown 파일을 아티팩트로 게시합니다. claude.ai의 비공개 대화형 페이지입니다. 공개 링크로 공유하거나 Team 및 Enterprise 플랜에서는 조직 내에서 공유할 수 있으며, 이 플랜에서는 Owner가 공개 공유를 활성화해야 합니다. Pro, Max, Team 또는 Enterprise 플랜이 필요하며 /login 인증이 필요합니다. 가용성을 참조하세요 예
AskUserQuestion 요구사항을 수집하거나 모호함을 명확히 하기 위해 객관식 질문을 합니다. 질문은 기본적으로 답변할 때까지 열려 있습니다. AskUserQuestion 도구 동작을 참조하세요 아니오
Bash 환경에서 셸 명령을 실행합니다. Bash 도구 동작을 참조하세요 예
CronCreate 현재 세션 내에서 반복 또는 일회성 프롬프트를 예약합니다. 작업은 세션 범위이며 만료되지 않은 경우 --resume 또는 --continue에서 복원됩니다. 세션 범위 예약 작업을 참조하세요 아니오
CronDelete ID로 세션 범위 예약 작업을 취소합니다 아니오
CronList 모든 세션 범위 예약 작업을 나열합니다 아니오
Edit 특정 파일에 대한 대상 편집을 수행합니다. Edit 도구 동작을 참조하세요 예
EndConversation 지속적인 학대 입력이 있는 드문 경우 또는 Claude에게 도구를 시연하도록 요청할 때 세션을 종료합니다. EndConversation 도구 동작을 참조하세요 아니오
EnterPlanMode 코딩 전에 접근 방식을 설계하기 위해 계획 모드로 전환합니다 아니오
EnterWorktree 격리된 git worktree를 생성하고 이를 전환합니다. 새 worktree를 생성하는 대신 기존 worktree로 전환하려면 path를 전달합니다. 처음 진입할 때 대상은 현재 저장소의 worktree이거나 다중 저장소 작업 공간에서 그 안에 중첩된 저장소의 worktree일 수 있습니다. v2.1.203 이전에는 중첩된 저장소의 worktree가 거부되었습니다. .claude/worktrees/ 외부의 path는 세션의 작업 디렉토리와 쓰기 액세스를 해당 위치로 이동하므로 진입하기 전에 승인을 요청합니다. 새 worktree 생성 및 .claude/worktrees/ 아래의 경로는 프롬프트하지 않습니다. v2.1.206 이전에는 Claude가 .claude/worktrees/ 외부의 경로에 프롬프트 없이 진입했습니다. worktree 세션 내에서 또는 isolation: worktree와 같은 고정된 작업 디렉토리가 있는 서브에이전트에서는 path 형식만 사용 가능하며 대상은 세션의 저장소의 .claude/worktrees/ 아래에 있어야 합니다 예
ExitPlanMode 승인을 위한 계획을 제시하고 계획 모드를 종료합니다 예
ExitWorktree worktree 세션을 종료하고 원래 디렉토리로 돌아갑니다. isolation: worktree와 같이 자체 작업 디렉토리에서 이미 실행되는 서브에이전트는 사용할 수 없습니다 아니오
Glob 패턴 매칭을 기반으로 파일을 찾습니다. macOS, Linux 및 WSL에서 기본적으로 없습니다. Glob 도구 동작을 참조하세요 아니오
Grep 파일 내용에서 패턴을 검색합니다. macOS, Linux 및 WSL에서 기본적으로 없습니다. Grep 도구 동작을 참조하세요 아니오
ListAgents Claude가 SendMessage로 메시지를 보낼 수 있는 에이전트를 나열합니다. 세션의 서브에이전트, 에이전트 팀 팀원, 다른 로컬 Claude Code 세션, 그리고 이 세션이 Remote Control에 연결되어 있는 동안 웹의 Claude Code 세션 및 다른 머신의 Remote Control 세션입니다. /list-agents 명령을 지원합니다. 크로스 세션 메시징을 참조하세요. Claude Code v2.1.224 이상이 필요하며 크로스 세션 메시징이 활성화된 세션에만 나타납니다. 팀원 행 및 이 세션의 자체 이름을 보여주는 첫 번째 줄은 v2.1.239 이상이 필요합니다 아니오
ListMcpResourcesTool 연결된 MCP 서버에서 노출한 리소스를 나열합니다. MCP Apps UI 리소스는 제외합니다. 이는 호스트 애플리케이션이 렌더링할 페이지입니다 아니오
LSP 언어 서버를 통한 코드 인텔리전스: 정의로 이동, 참조 찾기, 유형 오류 및 경고 보고. LSP 도구 동작을 참조하세요 아니오
Monitor 백그라운드에서 명령을 실행하고 각 출력 줄을 Claude에게 다시 피드하므로 로그 항목, 파일 변경 또는 폴링된 상태에 대화 중에 반응할 수 있습니다. WebSocket을 열고 각 수신 메시지를 이벤트로 처리할 수도 있습니다. Monitor 도구를 참조하세요 예
NotebookEdit Jupyter 노트북 셀을 수정합니다. NotebookEdit 도구 동작을 참조하세요 예
PowerShell PowerShell 명령을 기본적으로 실행합니다. 가용성은 PowerShell 도구를 참조하세요 예
PushNotification 데스크톱 알림을 보내고 Remote Control이 연결되어 있을 때 휴대폰 푸시를 보냅니다. 따라서 장시간 실행되는 작업 또는 세션 범위 예약 작업이 사용자가 자리를 떠날 때 연락할 수 있습니다. 푸시 배달은 Anthropic 호스팅 인프라를 통해 실행되며, Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서는 액세스할 수 없습니다 아니오
Read 파일의 내용을 읽습니다. Read 도구 동작을 참조하세요 아니오
ReadMcpResourceTool URI로 특정 MCP 리소스를 읽습니다 아니오
RemoteTrigger claude.ai에서 클라우드 예약 작업(이전 명칭: 루틴)을 생성, 업데이트, 실행 및 나열합니다. /schedule 명령을 지원합니다. RemoteTrigger 입력 참조는 모든 작업 및 도구를 제거하는 조직 정책을 문서화합니다. 클라우드 예약 작업은 claude.ai에 있으며 Pro, Max, Team 또는 Enterprise 플랜이 필요합니다. 따라서 이 도구는 Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서 액세스할 수 없습니다 아니오
ReportFindings 코드 리뷰 결과를 구조화된 목록으로 보고합니다. 각 결과마다 파일, 요약 및 실패 시나리오가 있으므로 Claude Code가 텍스트로 인쇄하는 대신 렌더링할 수 있습니다. Claude는 활성 코드 리뷰 지침이 이를 수행하도록 지시할 때 호출합니다. 결과는 correctness 또는 test-coverage와 같은 선택적 category 슬러그를 전달할 수도 있으며, 렌더링된 목록의 파일 위치 옆에 표시됩니다 아니오
ScheduleWakeup 자체 페이스 /loop의 다음 반복을 다시 예약합니다. Claude는 각 반복이 끝날 때 이를 호출하여 다음 반복이 실행될 시기를 선택합니다. 1분에서 1시간 사이입니다. 직접 호출하지 않습니다. 루프를 대신 종료하려면 Claude는 stop: true로 호출하여 보류 중인 웨이크업을 취소합니다. 보류 중인 웨이크업은 Stop 훅 입력의 session_crons에 나타납니다 아니오
SendFeedback Claude Code에 대한 피드백 보고서를 작성합니다. 제품 문제 또는 세션에서 Claude의 자체 동작을 다룹니다. 검토할 수 있도록 머신에서 대기열에 넣습니다. Claude Code는 초안을 보내도록 선택할 때까지 아무것도 보내지 않습니다. SendFeedback 도구 동작을 참조하세요. Claude Code v2.1.238 이상이 필요합니다 아니오
SendMessage 다른 에이전트에게 메시지를 보냅니다. 에이전트 팀 팀원, 에이전트 ID 또는 이름으로 재개하는 [서브에이전트], 또는 다른 Claude Code 세션 중 하나입니다. 이 머신 또는 그 이상입니다. 다른 세션으로 메시징하려면 Claude Code v2.1.224 이상이 필요합니다. 크로스 세션 메시징은 Claude가 도달할 수 있는 세션, 메시지가 도착할 때의 모습, 및 다른 세션이 유휴 상태가 될 때 Claude가 공지를 받는 방법을 다룹니다. Claude는 선택적 summary 입력을 포함할 수 있습니다. 일반적으로 5-10단어이며, Claude Code는 한 줄 미리보기로 표시합니다. Claude가 일반 텍스트 메시지에서 생략하면 Claude Code는 메시지의 첫 번째 줄을 요약으로 사용합니다. Claude Code는 200자보다 긴 요약을 줄임표로 자릅니다 아니오
SendUserFile 세션의 파일을 선택적 캡션과 함께 사용자에게 보냅니다. 생성된 보고서, 다이어그램, 스크린샷 또는 빌드된 아티팩트가 트랜스크립트에서만 언급되는 대신 장치에 도달합니다. 선택적 display 입력은 프레젠테이션을 제어합니다. render는 파일을 클라이언트에서 인라인으로 열고, attach는 다운로드 카드만 표시하며, 설정되지 않으면 클라이언트가 파일 유형으로 결정합니다. Remote Control 클라이언트가 연결되어 있거나 클라우드 세션에서 사용 가능합니다. 배달은 Anthropic 호스팅 인프라를 통해 실행되므로 도구는 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서 사용할 수 없습니다 아니오
ShareOnboardingGuide ONBOARDING.md를 업로드하고 팀원이 Claude Code에서 열 수 있는 공유 링크를 반환합니다. 가이드가 작성된 후 /team-onboarding에서 호출됩니다. Team 및 Enterprise 플랜의 claude.ai 구독자가 사용할 수 있습니다 예
Skill 주 대화 내에서 스킬을 실행합니다 예
SubagentHandback 서브에이전트의 최종 보고서를 해당 서브에이전트의 결과를 받는 대화에 전달합니다. 자동 모드에서만 제공되며, Agent 도구가 포크 이외의 로컬에서 실행하는 서브에이전트에만 제공되며, 터미널 CLI, IDE 확장, 클라우드 세션 및 Agent SDK에서 사용 가능합니다. 분류기는 보고서가 전달되기 전에 검토합니다. Claude Code v2.1.271 이상이 필요합니다 아니오
TaskCreate 작업 목록에 새 작업을 생성합니다. 작업 도구 가용성 아래에 나열된 모델에서만 기본적으로 제공되며, 다른 모델에서는 옵트인할 때만 제공됩니다 아니오
TaskGet 특정 작업의 전체 세부 정보를 검색합니다. 작업 도구 가용성 아래에 나열된 모델에서만 기본적으로 제공되며, 다른 모델에서는 옵트인할 때만 제공됩니다 아니오
TaskList 현재 상태와 함께 모든 작업을 나열합니다. 작업 도구 가용성 아래에 나열된 모델에서만 기본적으로 제공되며, 다른 모델에서는 옵트인할 때만 제공됩니다 아니오
TaskOutput v2.1.277에서 제거되었습니다. 이전에는 백그라운드 작업에서 출력을 검색했습니다. 이제 Claude는 대신 Read로 백그라운드 작업의 출력 파일을 읽습니다 아니오
TaskStop ID로 실행 중인 백그라운드 작업을 중지합니다. 또한 에이전트 팀 팀원 또는 에이전트 ID 또는 이름으로 명명된 백그라운드 에이전트를 허용합니다. ID와 일치하는 작업이 없으면 오류는 다른 에이전트가 생성한 에이전트를 포함하여 실행 중인 백그라운드 에이전트를 ID 및 설명으로 나열합니다 아니오
TaskUpdate 작업 상태, 종속성, 세부 정보를 업데이트하거나 작업을 삭제합니다. 작업 도구 가용성 아래에 나열된 모델에서만 기본적으로 제공되며, 다른 모델에서는 옵트인할 때만 제공됩니다 아니오
TodoWrite 세션 작업 체크리스트를 관리합니다. TaskCreate, TaskGet, TaskList 및 TaskUpdate를 선호하여 기본적으로 비활성화됩니다. 작업 추적 도구가 있는 세션에서 다시 활성화하려면 CLAUDE_CODE_ENABLE_TASKS=0을 설정합니다 아니오
ToolSearch 도구 검색이 활성화되어 있을 때 지연된 도구를 검색하고 로드합니다 아니오
WaitForMcpServers 백그라운드에서 여전히 연결 중인 하나 이상의 MCP 서버를 기다립니다. 따라서 요청이 세션을 다시 시작하지 않고도 해당 도구를 사용할 수 있습니다. Claude는 필요한 서버가 아직 연결되지 않았을 때 호출합니다. 도구 검색이 비활성화되어 있을 때만 나타납니다. ToolSearch는 활성화되어 있을 때 대기를 처리합니다 아니오
WebFetch 지정된 URL에서 콘텐츠를 가져옵니다. WebFetch 도구 동작을 참조하세요 예
WebSearch 웹 검색을 수행합니다. WebSearch 도구 동작을 참조하세요 예
Workflow 동적 워크플로우를 실행합니다. 백그라운드에서 많은 서브에이전트를 조율하고 하나의 통합된 결과를 반환하는 스크립트입니다 예
Write 파일을 생성하거나 덮어씁니다. Write 도구 동작을 참조하세요 예

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

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

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

규칙 형식 적용 대상 세부 정보
Bash(npm run *) Bash, Monitor 명령 패턴 매칭
PowerShell(Get-ChildItem *) PowerShell 명령 패턴 매칭
Read(~/secrets/**) Read, Grep, Glob, LSP 경로 패턴 매칭
Edit(/src/**) Edit, Write, NotebookEdit 경로 패턴 매칭
Skill(deploy *) Skill Skill 이름 매칭
Agent(Explore) Agent Subagent 유형 매칭
WebFetch(domain:example.com) WebFetch 도메인 매칭
WebSearch WebSearch specifier 없음; 도구 전체를 허용하거나 거부합니다

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

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

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

에이전트 도구 동작

에이전트 도구는 별도의 컨텍스트 윈도우에서 서브에이전트를 생성합니다. 서브에이전트는 자율적으로 작업을 진행한 후 부모 대화에 최종 결과를 반환합니다. 부모는 서브에이전트의 중간 도구 호출이나 출력을 보지 못하고 최종 결과만 봅니다. 동일한 도구로 팀원이나 포크를 시작할 수도 있습니다:

  • 팀원: 에이전트 팀이 활성화된 경우, name을 포함하는 호출은 대신 팀원을 시작할 수 있으며, 팀원은 결과를 반환하는 대신 팀 메시지를 통해 보고합니다
  • 포크: 포크 모드가 켜져 있는 곳에서는 이 도구가 포크된 서브에이전트를 시작할 수 있으며, 포크된 서브에이전트는 새로 시작하는 대신 전체 부모 대화를 상속합니다

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

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

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

모든 경우에 해결된 집합은 서브에이전트에서 사용 가능한 도구로 제한됩니다. 서브에이전트에서 사용할 수 없는 도구는 tools에 나열되어 있어도 절대 부여되지 않습니다. SubagentHandback 도구 테이블 항목의 조건이 유지되는 경우, Claude Code는 tools에서 생략하거나 disallowedTools에 나열하더라도 서브에이전트에 해당 도구를 제공합니다.

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

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

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

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

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

AskUserQuestion 도구 동작

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

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

질문 자동 계속 타임아웃

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

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

Claude가 백그라운드 세션에서 묻는 질문, 스크린 리더 모드에서 묻는 질문, 또는 세션이 Remote Control에 연결된 동안 묻는 질문에는 타이머가 시작되지 않습니다. 이러한 질문은 답변할 때까지 대기합니다. 타임아웃은 AskUserQuestion의 객관식 질문에만 적용됩니다. 계획 승인을 포함한 권한 프롬프트는 유휴 상태에서 자동으로 해결되지 않습니다.

Bash 도구 동작

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

명령 간에 유지되는 항목

  • Claude가 주 세션에서 cd를 실행할 때, 새로운 작업 디렉터리는 프로젝트 디렉터리 내에 있거나 --add-dir, /add-dir 또는 설정의 additionalDirectories로 추가한 추가 작업 디렉터리 내에 있는 한 이후의 Bash 명령으로 이월됩니다. 이는 나중의 메시지에 응답하여 Claude가 실행하는 명령을 포함합니다.
    • 서브에이전트 세션은 작업 디렉터리 변경을 절대 이월하지 않습니다.
    • 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가 백그라운드에서 시작하는 명령의 timeout이 대신 해당 명령이 백그라운드에서 실행될 수 있는 기간을 설정하며, 이 제한의 별도 기본값과 최대값이 적용됩니다. PowerShell 도구는 동일한 타임아웃 규칙을 따르고 동일한 두 변수를 읽습니다.

출력 제한

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

결과 Claude가 받는 것
유효 기본값으로 대략 30,000자까지 인라인입니다. 그 이상은 세션 디렉터리에 저장되고 64MiB를 초과하여 잘린 파일의 경로와 처음 최대 2,000자까지의 미리보기이며, Claude는 나머지가 필요할 때 파일을 읽거나 검색합니다.
실패 대략 10,000자까지 인라인입니다. 그 이상은 읽기 창에서 잘린 해당 크기의 머리-꼬리 발췌이며, 파일 경로는 없습니다.

종료 코드 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 플래그를 사용한 비대화형 모드의 실행은 해당 명령이 종료되거나 시간 제한에 도달할 때까지 결과 이후에도 열린 상태로 유지됩니다. 백그라운드 서브에이전트가 시작한 명령은 실행이 종료될 때 중지됩니다.

백그라운드 명령의 시간 제한

-p 플래그를 사용한 실행, Agent SDK 애플리케이션, CI 작업 또는 클라우드 세션처럼 사람의 개입 없이 실행되는 세션에서는 Bash 및 PowerShell 백그라운드 명령에 시간 제한이 있습니다. 터미널, 데스크톱 앱 또는 VS Code 확장 프로그램에서 작업하는 로컬 세션에는 백그라운드 명령에 대한 시간 제한이 없습니다.

시간 제한에는 Claude Code v2.1.285 이상이 필요합니다. v2.1.288 이전에는 모든 세션에 적용되었습니다.

시간 제한은 명령이 백그라운드에 진입하는 순간부터 계산됩니다:

  • Claude가 백그라운드에서 시작하는 명령은 30분 또는 run_in_background로 전달하는 timeout을 받으며, 최대 2시간입니다.
  • 포그라운드에서 시작한 후 백그라운드로 이동하는 명령(예: 타임아웃 시)은 이동 시점부터 30분을 받습니다.

프롬프트를 --input-format stream-json이 아닌 텍스트로 전달하는 -p 플래그 실행에서는, 실행이 결과 이후 백그라운드 명령을 기다리기 때문에 두 기본값 모두 30분이 아닌 10분입니다.

백그라운드 명령이 시간 제한에 도달하면, Claude Code는 이를 중지하고 Claude에 이유를 알립니다. Claude는 작업이 여전히 필요하면 더 긴 timeout으로 명령을 다시 시작할 수 있습니다. 중지 알림은 Background command "<description>" was stopped after reaching its background time limit를 읽습니다.

백그라운드 명령의 시간 제한 높이기

두 개의 환경 변수는 Bash 및 PowerShell 명령 모두에 대해 이러한 제한을 높입니다. 둘 다 밀리초를 사용하며, 어느 것도 제한을 단축할 수 없습니다. 더 낮은 값은 기본값과 2시간 최대값을 그대로 둡니다.

  • BASH_DEFAULT_TIMEOUT_MS를 1800000 이상으로 설정하여 30분 기본값을 해당 값으로 바꿉니다. Claude가 timeout 없이 시작하는 명령과 이동된 명령 모두에 적용됩니다. 프롬프트를 텍스트로 전달하는 -p 실행에서는 600000을 초과하는 모든 값이 10분 기본값을 대체합니다.
  • BASH_MAX_TIMEOUT_MS를 7200000 이상으로 설정하여 2시간 최대값을 해당 값으로 높입니다. BASH_DEFAULT_TIMEOUT_MS를 7200000 이상으로 설정하면 최대값을 동일한 방식으로 높입니다.

포그라운드 명령이 백그라운드로 이동

포그라운드 명령이 완료되지 않고 타임아웃에 도달하면, Claude Code는 이를 중지하지 않고 백그라운드로 이동합니다. 단, 명령이 sleep으로 시작하는 경우는 제외됩니다. 이동된 명령의 시간 제한은 이동 시점부터 계산되며, 포그라운드 서브에이전트의 이동된 명령은 여전히 해당 서브에이전트의 실행이 끝날 때 중지됩니다.

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1을 설정하거나 bare 모드에서 실행하면 자동 백그라운드 처리가 비활성화되므로, 타임아웃에 도달한 명령은 대신 중지됩니다.

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

  • 타임아웃이 이동을 트리거할 때, 결과는 명시적으로 보고합니다: 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 이상이 필요합니다. 명명할 수 있는 종류:

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

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

Edit 도구 동작

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

편집을 적용하기 위해 다음 검사를 통과해야 합니다. 그 전에, Read 거부 규칙과 일치하는 경로는 거부되며, 여기에 새 파일을 만드는 것도 포함됩니다.

  • 편집 전 읽기: 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는 cat이나 grep 같은 Bash 명령으로 파일을 본 후에도 별도의 Read 없이 파일을 편집할 수 있습니다. 해당 명령은 cat, nl, bat, batcat, head, tail, sed -n 'X,Yp', grep, egrep, fgrep, rg이며, 각각 파이프나 리디렉션 없이 단일 파일에 대해 실행되어야 합니다. 일치 항목을 출력하지 않는 검색은 읽기로 간주되지 않으며, 이 목록에 없는 명령도 마찬가지입니다.

Claude가 이 방식으로 파일을 볼 때, Claude Code는 해당 파일에 적용되는 하위 디렉터리 CLAUDE.md 및 경로 범위 규칙도 로드합니다. Read 및 Edit 권한 규칙에서 Read 및 Edit 거부 규칙이 적용되는 Bash 명령을 확인하십시오.

UTF-8이 아닌 파일

Claude는 유효한 UTF-8이 아닌 파일에 NotebookEdit를 사용할 수 없습니다. Edit도 마찬가지이며, 파일이 리틀 엔디언 UTF-16 바이트 순서 표시로 시작하는 경우는 예외입니다. Claude가 시도하면 도구는 변경을 거부하고 파일을 그대로 둡니다. 거부되는 파일에는 Windows-1252나 Shift-JIS 같은 레거시 인코딩으로 저장된 비ASCII 텍스트, 바이너리 파일, 잘못된 바이트 시퀀스가 있는 UTF-8이 포함됩니다.

도구가 거부하는 이유는 전체 파일을 UTF-8로 다시 저장하면 디코딩할 수 없는 모든 바이트가 대체 문자 U+FFFD로 바뀌기 때문입니다. 대신 Claude가 받는 오류는 파일의 인코딩을 유지하는 셸 명령으로 변경하거나, 먼저 파일을 UTF-8로 변환할지 사용자에게 묻도록 Claude에게 안내합니다.

Claude는 이러한 파일을 Write로 교체할 수는 있지만, 새 콘텐츠에 U+FFFD(Read가 디코딩할 수 없는 바이트 대신 Claude에게 표시하는 문자)가 포함된 경우는 예외입니다. 이 보호 장치는 Claude가 읽은 깨진 텍스트를 다시 쓰지 못하도록 막습니다. Write가 파일을 교체하면 새 콘텐츠를 UTF-8로 저장하므로 파일의 원래 인코딩이 손실됩니다.

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과 일치하지 않는 거부 목록은 이를 제자리에 둡니다.

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

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

Glob 도구 동작

Glob 도구는 이름 패턴으로 파일을 찾습니다. Windows에서는 기본 도구 세트의 일부입니다. macOS, Linux 및 WSL에서 Claude Code는 Glob과 Grep을 기본 도구 세트에서 제외하고, Claude는 Bash 도구를 통해 find 및 grep으로 검색합니다. Claude의 셸에서 이 두 명령은 bfs 및 ugrep의 임베드된 버전을 실행하며, 검색은 Bash 호출로 훅과 권한 규칙에 도달합니다.

macOS, Linux 및 WSL에서 다음의 경우에 Glob과 Grep 도구를 다시 얻습니다:

  • 세션을 시작할 때 --tools 또는 --allowedTools에서 Glob 또는 Grep을 명명하거나, 동등한 Agent SDK 옵션에서 명명합니다. --tools를 사용하면 나열한 도구를 얻고, --allowedTools에서 도구 중 하나를 명명하면 둘 다 복원됩니다. 설정 파일의 허용 규칙은 이 효과를 갖지 않습니다.
  • 권한 거부 규칙, --disallowedTools 플래그 또는 --restricted가 세션에서 Bash를 제거합니다.
  • 서브에이전트가 tools 필드에 Glob 또는 Grep을 나열하고 Bash를 제외합니다. 나열된 도구는 해당 서브에이전트에만 돌아오거나, --agent 또는 agent 설정을 통해 주 세션 에이전트로 실행될 때 전체 세션에 돌아옵니다.

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은 파일 내부의 줄을 찾습니다. macOS, Linux 및 WSL에서 Grep은 Glob과 동일한 조건에서 기본적으로 없습니다. 두 도구를 사용할 수 있는 경우는 Glob 도구 동작을 참조하십시오.

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 매개변수가 나열된 파일별 항목을 자르더라도 모든 일치를 포함합니다.

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가 시작하는 모든 감시에는 기한이 있습니다: 기본값은 5분, 최대 30분이며, -p를 사용하여 단일 프롬프트가 주어진 비대화형 실행에서는 최대 10분입니다.

기한에 감시가 종료됩니다. Claude는 한 번의 알림을 받으므로 여전히 필요한 경우 감시를 다시 시작할 수 있습니다.

Claude에게 취소를 요청하거나 세션을 종료하여 모니터를 중지합니다. 모니터를 시작한 서브에이전트를 중지하면(예: /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이 설정된 경우에도 사용할 수 없습니다. Windows에서는 Git Bash가 설치된 경우에만 이 도구를 사용할 수 있습니다.

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

WebSocket 소스

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

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

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

필드 필수 설명
url 예 연결할 엔드포인트입니다. ws:// 또는 wss:// URL이어야 하며 포함된 자격 증명이나 공백이 없어야 하고 ASCII 문자만 사용해야 합니다
protocols 아니요 핸드셰이크 중에 제공할 WebSocket 하위 프로토콜 이름입니다. 각 항목은 유효한 하위 프로토콜 토큰이어야 하며 목록에 중복이 포함될 수 없습니다

timeout_ms 기한은 WebSocket 감시에도 적용됩니다: 감시가 기한에 종료되고 TaskStop이 조기에 취소합니다.

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

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

NotebookEdit 도구 동작

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

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

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

NotebookEdit은 Edit과 동일한 규칙에 따라 UTF-8로 디코딩되지 않는 노트북 파일을 거부하며, 아무것도 쓰지 않습니다.

권한 규칙은 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을 설정합니다.

Bash 거부 규칙은 PowerShell 도구도 끕니다

Git Bash가 설치된 Windows에서 Bash를 거부하면 해당 세션에서 PowerShell 도구도 꺼집니다. 이는 단독 Bash뿐 아니라 Bash(git push *)와 같은 범위 지정 규칙에도 적용되며, 설정 파일 중 하나 또는 --disallowedTools에서 지정된 규칙에도 적용됩니다. Claude Code가 이렇게 하는 이유는 Bash 규칙이 자체 권한 규칙을 가진 PowerShell 도구를 제한하지 않기 때문입니다. PowerShell이 켜진 상태로 남아 있으면 Claude는 규칙이 Bash에서 거부하는 작업을 PowerShell에서 실행할 수 있습니다.

Bash 거부 규칙과 함께 PowerShell 도구를 켜 두려면 다음 중 하나를 수행합니다.

  • PowerShell 도구 활성화에 표시된 대로 환경 또는 설정 파일의 env 블록에서 CLAUDE_CODE_USE_POWERSHELL_TOOL=1을 설정합니다.
  • PowerShell(git push *) 거부 규칙과 같은 범위 지정 PowerShell 권한 규칙을 설정 파일에 추가합니다.

이 중 하나가 없으면 범위 지정 Bash 거부 규칙은 Bash 도구를 사용 가능한 상태로 두지만, Claude Code는 경고 없이 PowerShell을 끕니다. Bash 도구 전체를 제거하는 규칙은 해당 세션에서 Claude가 사용할 수 있는 셸 도구를 하나도 남기지 않습니다.

설정, 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 도구가 활성화되어야 합니다.

PowerShell 명령은 CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR 환경 변수를 포함하여 Bash 명령과 동일한 주 세션 작업 디렉터리 재설정 동작을 따릅니다.

PowerShell 명령은 PowerShell 명령의 지속 변수에 설명된 조건에 따라 훅이 CLAUDE_ENV_FILE을 통해 유지하는 변수도 수신합니다. Claude Code v2.1.296 이상이 필요합니다.

PowerShell에서 검색 및 git diff의 종료 코드 1

Claude가 PowerShell 도구에서 실행한 grep 또는 rg 검색이 아무것도 일치하지 않을 때 Error: Exit code 1이 표시되더라도 검색이 실패한 것은 아닙니다. 별도로 조치할 필요가 없습니다. 이 오류는 검색이 더 긴 명령의 일부일 때 나타날 수 있습니다. 예를 들어 rg가 코드 1로 종료되면 rg foo | Out-Null은 오류를 표시하지만 rg foo는 표시하지 않습니다.

PowerShell 도구는 grep, rg, egrep, fgrep, findstr, git grep 및 git diff의 종료 코드 1을 정상적인 결과로 간주할 수 있습니다. 검색 명령은 일치하는 항목이 없음을 알리기 위해 종료 코드 1을 사용합니다. git diff에서 종료 코드 1은 파일이 다르다는 것을 의미합니다. Claude가 실행할 때 오류를 표시하는 명령은 shell: powershell이 지정된 스킬에서 실패한 것으로 간주됩니다.

Windows 인코딩 및 종료 코드

  • >와 >>를 사용한 리디렉션은 PowerShell 5.1에서 UTF-8 파일을 작성합니다.
  • Claude Code는 기본 명령의 표준 입력으로 파이프된 텍스트를 UTF-8로 인코딩합니다.
  • Claude Code는 ANSI 이스케이프 시퀀스 없이 오류 출력을 캡처합니다.
  • 자식 프로세스가 표준 입력을 대기하는 명령은 행(hang)되는 대신 파일 끝을 수신합니다.
  • where.exe가 일치하는 항목을 찾지 못하거나 fc.exe 또는 diff.exe가 파일이 다르다는 것을 발견하면, 명령이 실패하지 않았더라도 결과에 Error: Exit code 1이 표시될 수 있습니다. 별도로 조치할 필요가 없습니다.
  • robocopy의 종료 코드 1부터 7까지가 오류로 표시되더라도 복사가 실패한 것은 아니며 별도로 조치할 필요가 없습니다. robocopy는 복사된 파일과 같은 결과를 알리기 위해 코드 0부터 7까지로 종료하며, 실패할 때는 8 이상으로 종료합니다.

미리보기 제한 사항

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

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

Read 도구 동작

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

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

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

  • 이미지: PNG, JPEG, GIF 및 WebP 파일은 원본 바이트가 아닌 Claude가 볼 수 있는 시각적 콘텐츠로 반환됩니다. Claude Code는 모델의 이미지 크기 제한에 맞추기 위해 큰 이미지를 전송 전에 크기 조정하고 재압축하므로, Claude는 큰 스크린샷의 축소된 버전을 볼 수 있습니다.

    Claude가 큰 이미지에서 세밀한 픽셀 수준의 세부 정보를 놓친 경우, 예를 들어 Bash를 통해 ImageMagick으로 관심 영역을 자른 다음 잘라낸 이미지를 읽도록 요청하십시오.

    Read는 128 MB보다 큰 이미지 파일을 거부하며, 이미지 크기를 조정하거나 더 작은 사본을 내보낸 다음 그 사본을 읽도록 Claude에게 안내하는 오류를 반환합니다. Claude가 그렇게 하지 않고 오류에서 멈추는 경우 File is too large to read as an image를 참조하십시오.

  • PDF: Claude는 짧은 .pdf 파일을 전체적으로 읽습니다. 10페이지보다 긴 PDF의 경우, pages 매개변수(예: "1-5")를 사용하여 범위로 읽으며, 한 번에 최대 20페이지까지 읽습니다. 페이지 범위 읽기는 poppler-utils의 pdftoppm으로 페이지를 렌더링하므로, macOS에서는 brew install poppler로, Debian 및 Ubuntu에서는 apt-get install poppler-utils로 설치하십시오. Windows 및 기타 플랫폼에서는 pdftoppm을 PATH에 배치하는 poppler 빌드를 설치하십시오. 이것이 없으면 페이지 범위 읽기가 pdftoppm is not installed 오류로 실패합니다.

  • Jupyter 노트북: .ipynb 파일은 코드, 마크다운 및 시각화를 포함한 모든 셀과 해당 출력을 반환합니다. 셀의 크기가 256 KB를 초과하거나 토큰 제한을 초과하는 노트북은 대신 오류를 반환합니다. Claude Code는 100MB를 초과하는 노트북 파일을 읽기를 거부합니다. 오류는 Claude에게 셀 슬라이스와 같은 노트북의 일부를 읽는 방법을 알려주며, 셸 명령을 사용합니다.

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

Read는 .xlsx, .parquet, .heic, .zip과 같이 바이너리로 취급하는 확장자의 파일을 거부합니다. 거부된 후에도 Claude는 작업을 계속합니다. 오류는 해당 파일 유형에 사용할 수 있는 스킬이 있으면 그 스킬을 제안하고, 없으면 해당 형식을 읽는 셸 명령이나 스크립트를 제안합니다. Read가 거부하는 파일을 @-멘션하면 Claude는 파일의 경로는 받지만 내용은 받지 않습니다.

대용량 파일

Claude는 한 번의 Read 호출로 반환되는 양보다 큰 텍스트 파일도 읽을 수 있습니다. 기본적으로 한 번의 호출은 최대 25,000 토큰 또는 CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS에 설정한 값까지 반환하며, 256 KB를 초과하는 전체 파일은 거부하므로, Claude는 더 큰 파일을 offset 및 limit을 사용하여 페이지 단위로 읽습니다. Claude Code v2.1.296 이상에서는 필요한 경우(예: 사용자가 전체 파일을 요청한 경우) allow_large: true를 설정하여 전체 파일 또는 긴 줄 범위를 한 번의 호출로 읽을 수 있습니다. 이 읽기는 기본 제한 대신 세션의 컨텍스트 윈도우에 남아 있는 공간을 기준으로 크기가 정해집니다. 이미지, PDF 및 노트북에는 기존 제한이 그대로 적용됩니다.

읽기가 기본 제한을 초과할 때 Claude가 받는 내용은 다음과 같습니다:

  • 토큰 제한을 초과하는 전체 파일: 파일의 첫 번째 페이지와 함께, Claude가 받은 파일의 양과 offset 및 limit을 사용하여 더 읽는 방법을 알려주는 PARTIAL view 공지
  • 256 KB를 초과하는 전체 파일, 또는 토큰 제한을 초과하는 offset 또는 limit 읽기: offset 및 limit을 사용하여 일부를 읽거나, 대신 Grep으로 특정 내용을 검색하도록 지시하는 오류

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는 전사본을 찾을 수 있도록 로컬 초안에 작업 디렉토리를 유지하며, 디렉토리를 전송하지 않습니다.

Zero Data Retention이 적용된 조직과 HIPAA 구성이 적용된 조직에서는 Claude Code가 세션에서 SendFeedback 도구를 제외합니다. Zero Data Retention이 적용된 조직의 세션에서 여전히 도구를 제공하는 경우, 초안은 머신에 남아 있으며 전송은 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를 사용하는 머신의 대화형 터미널 세션에 도구를 포함합니다. 다음에서는 도구를 제외합니다:

Task 도구 가용성

작업 추적 도구인 TaskCreate, TaskGet, TaskUpdate, TaskList, TodoWrite는 기본적으로 Opus 4.7, Sonnet 4.6, Haiku 4.5 및 그 이전 모델에서만 사용 가능합니다. 도구를 사용할 수 있는 곳이면 네 가지 Task 도구를 얻거나, CLAUDE_CODE_ENABLE_TASKS=0을 설정할 때 대신 TodoWrite를 얻습니다.

다른 모든 모델에서는 Claude Code가 사용자가 명시적으로 선택하지 않는 한 도구를 제공하지 않습니다. 이는 Claude Code가 인식하지 못하는 모델 ID(예: LLM 게이트웨이를 통해 제공되는 사용자 정의 모델 이름)에도 동일하게 적용됩니다. 최신 모델에서는 Claude가 작성된 체크리스트 없이 다단계 작업을 추적하며, 도구의 정의와 알림은 컨텍스트를 차지합니다. 도구가 없으면 Claude는 작업 중에 작업 목록에 아무것도 추가하지 않습니다.

기본적으로 이러한 도구가 없는 모델에서 이 도구들을 사용하려면 다음 중 하나를 수행하십시오:

  • 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 v2.1.268 이상에 적용됩니다.

서브에이전트 및 에이전트 팀의 작업 추적 도구

서브에이전트는 어떤 모델을 실행하든 사용자의 세션에 작업 추적 도구가 있을 때만 해당 도구를 갖습니다. 프로세스 내 에이전트 팀 팀원은 사용자의 세션에 작업 추적 도구가 있을 때 해당 도구를 갖습니다. 분할 창 팀원은 별도의 Claude Code 프로세스로, --allowedTools가 아니라 사용자의 --tools 목록과 거부 규칙을 상속하므로 설정한 내용을 확인하십시오:

  • --tools 목록이나 거부 규칙이 없고, 팀원에 대해 CLAUDE_CODE_ENABLE_TODO_TOOLS가 설정되지 않은 경우: 팀원은 자체 모델이 기본적으로 갖는 작업 추적 도구를 갖습니다.
  • 셸에서 CLAUDE_CODE_ENABLE_TODO_TOOLS를 내보낸 경우: Claude Code는 팀원에게 고정된 환경 변수 집합을 전달하며, 여기에는 사용자가 내보낸 변수가 포함되지 않습니다. 팀원에게도 이를 설정하려면 셸에서 claude --settings '{"env":{"CLAUDE_CODE_ENABLE_TODO_TOOLS":"1"}}'를 실행하여 세션을 시작하십시오. 팀원은 사용자의 --settings 값도 전달받습니다.
  • --tools에 작업 추적 도구가 지정된 경우: 팀원은 모든 모델에서 해당 도구를 갖습니다.
  • 작업 추적 도구가 --tools에 없거나 거부 규칙에 지정된 경우: 팀원은 해당 도구를 갖지 않습니다.

Task 도구가 없으면 에이전트는 공유 작업 목록 대신 메시지를 통해 팀과 조율합니다.

WebFetch 도구 동작

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

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

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

  • WebFetch는 요청을 하기 전에 localhost 및 점이 없는 다른 호스트명(예: 베어 인트라넷 이름)을 거부합니다. 반환되는 오류는 Claude에 Bash를 통해 curl로 로컬 서버에 도달하도록 지시합니다.
  • HTTP URL은 자동으로 HTTPS로 업그레이드됩니다.
  • WebFetch는 호출당 페이지 콘텐츠를 최대 100,000자까지 읽습니다. Claude Code v2.1.290 이상에서는 더 긴 페이지에 대한 결과가 읽지 않은 분량을 Claude에 알려 주므로, Claude가 다음 부분을 가져올 수 있습니다.
  • WebFetch는 기본적으로 각 응답을 15분 동안 캐시하므로, 동일한 URL의 반복된 가져오기가 빠르게 반환됩니다. Claude Code v2.1.233 이상에서는 CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS를 설정하여 WebFetch가 각 응답을 유지하는 기간을 변경할 수 있습니다.
  • 5분 이내에 다운로드를 완료하지 못한 페이지(WebFetch가 따라가는 모든 리디렉션 포함)는 마감 오류로 실패합니다. Claude Code v2.1.268 이상에서는 CLAUDE_CODE_WEBFETCH_DEADLINE_MS를 설정하여 제한을 변경하거나, 0으로 설정하여 제거할 수 있습니다.
  • URL이 다른 호스트로 리디렉션될 때, WebFetch는 원본 URL과 리디렉션 대상을 이름으로 지정하는 텍스트 결과를 반환하고 따라가지 않습니다. 그러면 Claude는 두 번째 WebFetch 호출로 새 URL을 가져옵니다.
  • 추출 단계가 과부하 API에 도달하면, Claude Code는 백오프로 재시도합니다. 여전히 실패하는 가져오기는 오류 결과를 반환합니다.

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:...) 규칙은 사전 승인된 집합보다 우선하므로, 사전 승인된 도메인을 차단하거나 이에 대한 프롬프트를 요구할 수 있습니다.

URL이 claude.ai 아티팩트 링크인 경우, Claude Code는 아티팩트 자체를 읽기 위한 승인을 요청할 수도 있습니다. 승인을 요청하는 경우에 대해서는 공유받은 아티팩트 읽기를 참조하십시오.

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

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

WebFetch 가용성

Claude Code v2.1.285 이상에서는 CLAUDE_CODE_DISABLE_WEB_FETCH를 1로 설정하여 WebFetch를 끌 수 있습니다.

Team 또는 Enterprise claude.ai 계정으로 로그인하고 LLM 게이트웨이를 통해 연결하지 않으면, WebFetch는 또한 조직의 정책에 따라 달라집니다. Claude Code는 세션이 시작될 때 api.anthropic.com에서 이 정책을 요청합니다. 다른 앱이 제공한 claude.ai 토큰 아래에서 실행되는 것과 같이 Claude Code가 계획을 결정할 수 없는 세션도 마찬가지입니다.

WebFetch가 세션에서 누락된 경우, 세션에서 /status를 실행하십시오. Organization policy 줄이 정책이 로드되지 않았으며 웹 가져오기를 기다리는 기능 중 하나로 이름을 지정하면, Claude Code는 조직이 이를 허용하는지 확인할 때까지 WebFetch를 보류합니다. 세션 외부에서 claude doctor는 자체 요청을 하고 동일한 줄을 인쇄합니다. WebFetch를 허용하는 정책이 로드되면, 도구는 재시작 없이 반환됩니다.

WebSearch 도구 동작

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

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

검색 요청이 과부하 상태의 API에 도달하면 Claude Code는 백오프를 사용하여 재시도합니다. 여전히 실패하는 호출은 오류 결과를 반환합니다.

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

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

[!NOTE]

WebSearch는 Claude API, AWS의 Claude Platform, Microsoft Foundry에서 사용할 수 있습니다. Google Cloud의 Agent Platform에서는 Opus 4, Sonnet 4, Haiku 4.5 및 이후 모델에서 작동합니다. Amazon Bedrock은 서버 측 웹 검색 도구를 노출하지 않습니다.

세션 검색 제한

대화형 터미널 세션에는 200개의 WebSearch 호출 제한이 있습니다. 주 대화와 병렬 연구 팬아웃 같은 서브에이전트에서 수행한 검색은 동일한 제한에 합산됩니다.

세션이 제한에 도달한 동안에는 검색이 대화에 아무것도 하지 않은 호출로 표시됩니다. Claude는 이미 수집한 정보로 계속 진행하고, 답변에서 그 사실을 밝히며, 더 많은 검색이 필요한 경우 사용자에게 제한을 높이도록 요청하라는 알림을 받습니다.

더 많은 검색을 하려면 상한을 높이거나, 제한이 다시 채워질 때까지 기다리거나, 새 대화를 시작합니다:

  • 상한 높이기: CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION 환경 변수를 500과 같은 양의 정수로 설정합니다. 상한은 높일 수 있지만 끌 수는 없습니다.
  • 다시 채워질 때까지 기다리기: Claude Code v2.1.290 이상에서는 대화형 터미널 세션의 제한이 시간당 약 100회 호출씩 다시 채워집니다. 속도를 변경하려면 CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR를 50과 같은 시간당 호출 수로 설정합니다.
  • 새 대화 시작하기: Claude Code 프롬프트에서 /clear를 실행해도 개수가 재설정됩니다. 실행 중인 워크플로와 같이 여전히 서브에이전트를 생성할 수 있는 작업이 초기화 후에도 남아 있으면 개수가 대신 이월됩니다.

-p를 사용하는 비대화형 모드와 Agent SDK에서는 제한이 세션 단위가 아니라 턴 단위로 적용됩니다. 턴은 사용자가 메시지를 보낸 시점부터 Claude가 응답을 마칠 때까지 지속됩니다. 그 이후 다음 메시지를 보내거나 새 claude -p 실행을 시작하면 제한이 재설정되며, --continue 또는 --resume을 사용하는 경우에도 마찬가지입니다. 더 많은 검색이 필요하면 CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION을 높이거나 CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR로 재충전 속도를 설정합니다.

Write 도구 동작

Write 도구는 새 파일을 생성하거나 기존 파일을 제공된 전체 콘텐츠로 덮어씁니다. 추가하거나 병합하지 않습니다. 또한 Write는 UTF-8이 아닌 파일에 설명된 대로 바이트가 디코딩되지 않는 기존 파일도 덮어쓰며, 새 콘텐츠를 UTF-8로 저장합니다.

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를 실행합니다.

[!NOTE]

advisor tool은 Claude Code가 구현하는 도구가 아니라 API가 실행하는 server tool입니다. 권한 규칙이나 hook 매처에서 참조할 수 있는 이름이 없습니다.

참고 항목

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