canUseTool 콜백을 사용하여 런타임에 다른 모든 항목을 처리합니다.
권한이 평가되는 방식
Claude가 도구를 요청할 때 SDK는 다음 순서로 권한을 확인합니다.1
2
거부 규칙
deny 규칙(disallowed_tools 및 settings.json에서)을 확인합니다. 거부 규칙이 일치하면 bypassPermissions 모드에서도 도구가 차단됩니다. Bash와 같은 단순 이름 거부 규칙은 이 평가가 시작되기 전에 Claude의 컨텍스트에서 도구를 제거하므로 Bash(rm *)과 같은 범위가 지정된 규칙만 이 단계에서 확인됩니다.3
확인 규칙
settings.json에서
ask 규칙을 확인합니다. ask 규칙이 일치하면 bypassPermissions 모드에서도 호출이 확인을 위해 canUseTool 콜백으로 전달됩니다.사용자 상호작용이 필요한 도구는 동일하게 작동합니다. AskUserQuestion 및 서버가 _meta["anthropic/requiresUserInteraction"]을 설정하는 MCP 도구는 allow 규칙이 일치할 때도 항상 콜백으로 전달됩니다. dontAsk 모드에서는 이 모드가 절대 프롬프트하지 않기 때문에 두 경우 모두 거부됩니다. MCP 주석에는 Claude Code v2.1.199 이상이 필요합니다.조직이 ask로 설정한 claude.ai connector 도구도 이 단계에서 흐름을 떠납니다. 모든 호출은 bypassPermissions 모드에서도, allow 규칙이 일치할 때도 콜백으로 전달됩니다. 콜백은 Your organization requires approval for this tool 이유를 받습니다. dontAsk 모드에서는 이 모드가 절대 프롬프트하지 않기 때문에 호출이 거부됩니다.4
권한 모드
활성 권한 모드를 적용합니다.
bypassPermissions모드에서 Claude Code는 이 단계에 도달하는 모든 것을 승인합니다. 단, 중요 경로를 대상으로 하는rm및rmdir제거는 대신 전달됩니다.acceptEdits모드에서 Claude Code는 Accept edits mode에 나열된 파일 작업을 승인합니다.plan모드에서 Claude Code는 allow 규칙과 관계없이 파일 편집 및 셸 쓰기 도구를canUseTool콜백으로 보내므로 계획 중에 쓰기 작업을 자동 승인할 수 없습니다.- 다른 모드에서는 요청이 전달됩니다.
5
허용 규칙
allow 규칙(allowed_tools 및 settings.json에서)을 확인합니다. 규칙이 일치하면 도구가 승인됩니다. 도구가 자체적으로 승인하는 호출도 이 단계에서 규칙 없이 해결됩니다. 예를 들어 작업 디렉토리 내의 파일 읽기 또는 읽기 전용 Bash 명령입니다. rm 및 rmdir 제거는 중요 경로를 대상으로 하는 경우 allow 규칙으로 절대 승인되지 않습니다. 프롬프트하는 모드에서는 콜백에 도달하고, Claude Code v2.1.218 이상의 auto 모드에서는 분류기로 이동하며, dontAsk 모드에서는 거부됩니다.6
canUseTool 콜백
위의 어느 것도 해결하지 못하면 결정을 위해
canUseTool 콜백을 호출합니다. dontAsk 모드에서는 이 단계를 건너뛰고 도구가 거부됩니다.TypeScript SDK에서 permissionPrompts: 'none'을 설정하면 콜백이 이 단계에서 호출되지 않습니다. PermissionRequest hook은 여전히 결정할 기회를 얻으며, 그렇지 않으면 Claude Code가 호출을 거부합니다. 이 옵션에는 Claude Code v2.1.259 이상이 필요합니다.canUseTool 콜백을 전달하면 쿼리가 구성될 때 SDK는 Node.js 프로세스 경고를 한 번 내보냅니다. 경고의 코드는 CLAUDE_SDK_CAN_USE_TOOL_SHADOWED입니다. 두 가지 구성이 이를 트리거합니다.
permissionMode: 'bypassPermissions'는 모드가 자동 승인하지 않는 작업을 제외하고 권한 모드 단계에 도달하는 모든 호출을 자동 승인합니다."Read"와 같은 각 단순allowedTools항목은 모드가 자동 승인하지 않는 작업을 제외하고 콜백이 참조되기 전에 전체 도구를 자동 승인합니다.
Bash(ls *)와 같은 지정자가 있는 항목과 acceptEdits 모드는 이를 트리거하지 않으며, 설정 파일에서 오는 허용 규칙은 확인에 표시되지 않습니다.
process.on('warning', ...)으로 수신하고 코드를 일치시켜 로깅하거나 억제합니다. 모드와 규칙과 관계없이 모든 도구 호출을 제어하려면 대신 PreToolUse hook을 사용합니다.
이 페이지는 허용 및 거부 규칙 및 권한 모드에 중점을 둡니다. 다른 단계의 경우:
- Hooks: 도구 요청을 허용, 거부 또는 수정하는 사용자 정의 코드를 실행합니다. Hooks로 실행 제어를 참조하세요.
- canUseTool 콜백: 이전 단계에서 호출을 해결하지 못할 때 런타임에 사용자에게 승인을 요청합니다. 승인 및 사용자 입력 처리를 참조하세요.
허용 및 거부 규칙
allowed_tools 및 disallowed_tools (TypeScript: allowedTools / disallowedTools)는 위의 평가 흐름에서 허용 및 거부 규칙 목록에 항목을 추가합니다. 작업 추적 도구 중 하나를 allowed_tools에 이름 지으면 Claude Code도 세션을 옵트인합니다. allowed_tools에 나열되지 않은 다른 도구는 여전히 Claude에서 사용 가능하며, 승인이 필요한 호출은 권한 모드로 넘어갑니다. 거부 규칙은 도구의 이름을 지정하는지 또는 도구 내의 패턴을 범위 지정하는지에 따라 다르게 작동합니다.
허용 규칙은 리터럴
mcp__<server>__ 접두사 이후에만 도구 이름 글롭을 허용합니다. 서버 세그먼트는 글롭이 없어야 하므로 규칙이 구성한 특정 서버의 이름을 지정합니다: mcp__puppeteer__*는 puppeteer 서버의 모든 도구와 일치하고, mcp__github__get_*는 해당 get_ 도구와 일치합니다. allowed_tools=["*"] 또는 allowed_tools=["mcp__*"]와 같은 앵커되지 않은 항목은 시작 경고와 함께 무시되며 아무것도 자동 승인하지 않습니다.
Read 및 Edit에 대한 범위 지정 규칙은 경로 패턴을 사용합니다. Edit(path) 규칙은 Write 및 NotebookEdit을 포함하여 파일을 쓰는 모든 기본 제공 도구를 관리합니다. Write(path) 규칙은 파일 권한 검사에 의해 일치되지 않습니다.
절대 파일 시스템 경로에는 //path를 사용합니다: Edit(//secrets/**) 거부 규칙은 디스크의 /secrets 아래 어디든지 쓰기를 차단합니다. 단일 슬래시를 사용하면 Edit(/secrets/**)는 규칙의 소스에서 앵커됩니다. allowed_tools 또는 disallowed_tools를 통해 전달된 규칙의 경우, 이는 세션의 작업 디렉토리를 의미하므로 규칙은 디스크의 /secrets를 차단하지 않습니다. 네 가지 앵커 형식과 설정 파일의 규칙이 어떻게 해결되는지는 Read 및 Edit 규칙을 참조하십시오.
잠금된 에이전트의 경우 allowedTools를 permissionMode: "dontAsk"와 쌍으로 지정합니다:
default 모드에서 승인이 필요 없는 호출은 나열 여부와 관계없이 실행됩니다. 예를 들어 읽기 전용 Bash 명령, 실행 전에 묻지 않는 Agent와 같은 도구, 작업 디렉토리 내의 파일 읽기 등입니다. 도구를 Claude의 범위에서 완전히 제거하려면 disallowedTools에 단순 이름을 추가합니다.
.claude/settings.json에서 허용, 거부 및 요청 규칙을 선언적으로 구성할 수도 있습니다. 이러한 규칙은 project 설정 소스가 활성화될 때 읽혀지며, 기본 query() 옵션에 대해 활성화됩니다. setting_sources (TypeScript: settingSources)를 명시적으로 설정하면 적용되도록 "project"를 포함합니다. 규칙 구문은 권한 설정을 참조하십시오.
권한 모드
권한 모드는 Claude가 도구를 사용하는 방식을 전역적으로 제어합니다.query()를 호출할 때 권한 모드를 설정하거나 스트리밍 세션 중에 동적으로 변경할 수 있습니다.
사용 가능한 모드
SDK는 다음 권한 모드를 지원합니다.권한 모드 설정
쿼리를 시작할 때 권한 모드를 한 번 설정하거나 세션이 활성화된 동안 동적으로 변경할 수 있습니다.- 쿼리 시간에
- 스트리밍 중
쿼리를 생성할 때
permission_mode(Python) 또는 permissionMode(TypeScript)를 전달합니다. 이 모드는 동적으로 변경되지 않는 한 전체 세션에 적용됩니다.모드 세부 정보
편집 수락 모드(acceptEdits)
파일 작업을 자동 승인하여 Claude가 프롬프트 없이 코드를 편집할 수 있도록 합니다. 다른 도구(예: 파일시스템 작업이 아닌 Bash 명령)는 여전히 일반 권한이 필요합니다.
자동 승인 작업:
- 파일 편집(Edit, Write 도구)
- 파일시스템 명령:
mkdir,touch,rm,rmdir,mv,cp,sed
additionalDirectories 내의 경로에만 적용됩니다. acceptEdits 모드에서 Claude Code는 Claude가 다음을 수행할 때 요청을 자동 승인하지 않습니다.
- 해당 범위 외의 경로에서 작업
- 보호된 경로에 쓰기
rm또는rmdir로 중요 경로 제거
묻지 않기 모드(dontAsk)
canUseTool을 호출하지 않고 모든 권한 프롬프트를 거부로 변환합니다. allowed_tools, settings.json 허용 규칙 또는 훅으로 사전 승인된 도구와 파일 읽기(작업 디렉토리 내) 및 Agent 호출과 같이 default 모드에서 승인이 필요 없는 호출은 정상적으로 실행됩니다. 조직에서 ask로 설정한 커넥터 도구, 사용자 상호작용이 필요한 도구, 그리고 중요 경로를 대상으로 하는 rm 및 rmdir 제거는 허용 규칙이 일치하더라도 거부됩니다. PreToolUse 훅 허용도 중요 경로 제거를 해제하지 않습니다.
사용 시기: 헤드리스 에이전트에 대해 고정된 명시적 도구 표면을 원하고 canUseTool이 없는 것에 대한 자동 의존보다 명확한 거부를 선호할 때.
권한 무시 모드(bypassPermissions)
아래 나열된 경우를 제외하고 프롬프트 없이 도구 사용을 자동 승인합니다. 훅은 여전히 실행되며 필요한 경우 작업을 차단할 수 있습니다.
계획 모드(plan)
Claude는 소스 파일을 편집하지 않고 코드베이스를 탐색하고 계획을 생성합니다. 읽기 전용 도구는 default 권한 모드에서와 같이 실행됩니다.
파일 편집은 허용 규칙이 일치하더라도 계획 모드에서 자동 승인되지 않습니다. 대신 canUseTool 콜백을 통해 프롬프트됩니다. Claude Code v2.1.212 이상에서는 touch 및 rm과 같이 파일을 수정하는 셸 명령도 동일한 방식으로 canUseTool 콜백에 도달합니다.
Claude는 계획을 최종화하기 전에 요구 사항을 명확히 하기 위해 AskUserQuestion을 사용할 수 있습니다. 이러한 프롬프트 처리에 대해서는 승인 및 사용자 입력 처리를 참조하세요.
사용 시기: Claude가 변경 사항을 실행하지 않고 제안하기를 원할 때(예: 코드 검토 중이거나 변경 사항이 적용되기 전에 승인해야 할 때).
관련 리소스
권한 평가 흐름의 다른 단계들:- 승인 및 사용자 입력 처리: 대화형 승인 프롬프트 및 명확히 하는 질문
- Hooks 가이드: 에이전트 라이프사이클의 주요 지점에서 사용자 정의 코드 실행
- 권한 규칙:
settings.json의 선언적 허용/거부 규칙