Claude Code SDK에서 도구 사용 및 권한을 제어하는 방법
canUseTool
콜백, 훅, 그리고 settings.json 권한 규칙을 사용하여 권한 시스템을 구현하는 방법을 다룹니다. 완전한 API 문서는 TypeScript SDK 참조를 참조하세요.
canUseTool
- 다루어지지 않은 경우에 대한 동적 승인, 사용자에게 권한 요청query()
를 호출할 때 권한 모드를 설정하거나 스트리밍 세션 중에 동적으로 변경할 수 있습니다.
모드 | 설명 | 도구 동작 |
---|---|---|
default | 표준 권한 동작 | 일반적인 권한 검사가 적용됨 |
plan | 계획 모드 - 실행 없음 | Claude는 읽기 전용 도구만 사용 가능; 실행 전에 계획을 제시 (현재 SDK에서 지원되지 않음) |
acceptEdits | 파일 편집 자동 승인 | 파일 편집 및 파일시스템 작업이 자동으로 승인됨 |
bypassPermissions | 모든 권한 검사 우회 | 모든 도구가 권한 프롬프트 없이 실행됨 (주의해서 사용) |
acceptEdits
)bypassPermissions
)bypassPermissions
모드 - 활성화되면 나머지 모든 도구를 허용함canUseTool
콜백 - 나머지 경우를 처리함bypassPermissions
모드에서도 항상 도구 사용을 차단할 수 있음bypassPermissions
모드는 허용 규칙과 canUseTool
을 재정의함canUseTool
콜백은 query
함수를 호출할 때 옵션으로 전달됩니다. 도구 이름과 입력 매개변수를 받아서 허용 또는 거부 결정을 반환해야 합니다.
canUseTool은 Claude Code가 사용자에게 권한 프롬프트를 표시할 때마다 실행됩니다. 예를 들어 훅과 권한 규칙이 이를 다루지 않고 자동 승인 모드가 아닐 때입니다.
다음은 대화형 도구 승인을 구현하는 방법을 보여주는 완전한 예시입니다:
canUseTool
은 권한 규칙으로 다루어지지 않는 경우를 처리함settings.json
의 권한 규칙은 내장된 bash 명령 파싱을 통한 선언적 제어를 제공합니다. 이러한 규칙은 canUseTool
이 호출되기 전에 평가됩니다. 설정 구성에 대한 자세한 내용은 Claude Code 설정 문서를 참조하세요.
ToolName(pattern)
패턴을 따릅니다:
Bash(npm:*)
는 “npm”으로 시작하는 모든 명령과 일치Read(./src/**/*.ts)
는 src의 TypeScript 파일과 일치WebFetch
는 모든 웹 페치를 차단rm -rf
또는 curl | sh
와 같은 위험한 패턴을 인식함Bash(git:*)
- 모든 git 명령과 일치Bash(npm run test)
- 정확한 명령과 일치Bash(npm run test:*)
- npm run test:unit, test:integration 등과 일치