가이드

권한 구성

권한 모드, 훅, 선언적 허용/거부 규칙을 사용하여 에이전트의 도구 사용 방식을 제어합니다.

Claude Agent SDK는 Claude가 도구를 사용하는 방식을 관리하기 위한 권한 제어 기능을 제공합니다. 권한 모드와 규칙을 사용하여 자동으로 허용되는 항목을 정의하고, canUseTool 콜백을 사용하여 런타임에 나머지를 처리합니다.

이 페이지는 권한 모드와 규칙을 다룹니다. 사용자가 런타임에 도구 요청을 승인하거나 거부하는 대화형 승인 흐름을 구축하려면 승인 및 사용자 입력 처리를 참조하세요.

권한 평가 방식

Claude가 도구를 요청하면 SDK는 다음 순서로 권한을 확인합니다:

훅
훅을 먼저 실행하여 허용, 거부 또는 다음 단계로 진행할 수 있습니다
권한 규칙
settings.json에 정의된 규칙을 다음 순서로 확인합니다: deny 규칙 먼저(다른 규칙에 관계없이 차단), 그다음 allow 규칙(일치하면 허용), 그다음 ask 규칙(승인 요청). 이러한 선언적 규칙을 사용하면 코드를 작성하지 않고도 특정 도구를 사전 승인, 차단 또는 승인 요구할 수 있습니다.
권한 모드
활성 권한 모드(bypassPermissions, acceptEdits, dontAsk 등)를 적용합니다
canUseTool 콜백
규칙이나 모드로 해결되지 않으면 canUseTool 콜백을 호출하여 결정합니다

이 페이지는 기본 동작을 제어하는 정적 구성인 권한 모드(3단계)에 초점을 맞춥니다. 다른 단계에 대해서는:

훅: 도구 요청을 허용, 거부 또는 수정하는 사용자 정의 코드를 실행합니다. 훅으로 실행 제어를 참조하세요.
권한 규칙: settings.json에서 선언적 허용/거부 규칙을 구성합니다. 권한 설정을 참조하세요.
canUseTool 콜백: 런타임에 사용자에게 승인을 요청합니다. 승인 및 사용자 입력 처리를 참조하세요.

권한 모드

권한 모드는 Claude가 도구를 사용하는 방식에 대한 전역 제어를 제공합니다. query()를 호출할 때 권한 모드를 설정하거나 스트리밍 세션 중에 동적으로 변경할 수 있습니다.

사용 가능한 모드

SDK는 다음 권한 모드를 지원합니다:

모드	설명	도구 동작
`default`	표준 권한 동작	자동 승인 없음; 일치하지 않는 도구는 `canUseTool` 콜백을 트리거합니다
`acceptEdits`	파일 편집 자동 수락	파일 편집 및 파일시스템 작업(`mkdir`, `rm`, `mv` 등)이 자동으로 승인됩니다
`bypassPermissions`	모든 권한 검사 우회	모든 도구가 권한 프롬프트 없이 실행됩니다(주의하여 사용)
`plan`	계획 모드	도구 실행 없음; Claude가 변경 없이 계획만 수립합니다

하위 에이전트 상속: bypassPermissions를 사용할 때 모든 하위 에이전트가 이 모드를 상속하며 재정의할 수 없습니다. 하위 에이전트는 메인 에이전트와 다른 시스템 프롬프트를 가질 수 있으며 덜 제한된 동작을 할 수 있습니다. bypassPermissions를 활성화하면 승인 프롬프트 없이 전체적이고 자율적인 시스템 접근 권한이 부여됩니다.

권한 모드 설정

쿼리를 시작할 때 권한 모드를 한 번 설정하거나, 세션이 활성화된 동안 동적으로 변경할 수 있습니다.

모드 세부 정보

편집 수락 모드 (`acceptEdits`)

Claude가 프롬프트 없이 코드를 편집할 수 있도록 파일 작업을 자동 승인합니다. 다른 도구(파일시스템 작업이 아닌 Bash 명령 등)는 여전히 일반 권한이 필요합니다.

자동 승인되는 작업:

파일 편집 (Edit, Write 도구)
파일시스템 명령: mkdir, touch, rm, mv, cp

사용 시기: Claude의 편집을 신뢰하고 더 빠른 반복을 원할 때, 예를 들어 프로토타이핑 중이거나 격리된 디렉토리에서 작업할 때 사용합니다.

권한 우회 모드 (`bypassPermissions`)

프롬프트 없이 모든 도구 사용을 자동 승인합니다. 훅은 여전히 실행되며 필요한 경우 작업을 차단할 수 있습니다.

극도로 주의하여 사용하세요. 이 모드에서 Claude는 전체 시스템 접근 권한을 가집니다. 모든 가능한 작업을 신뢰할 수 있는 통제된 환경에서만 사용하세요.

계획 모드 (`plan`)

도구 실행을 완전히 방지합니다. Claude는 코드를 분석하고 계획을 수립할 수 있지만 변경할 수는 없습니다. Claude는 계획을 확정하기 전에 요구 사항을 명확히 하기 위해 AskUserQuestion을 사용할 수 있습니다. 이러한 프롬프트 처리에 대해서는 승인 및 사용자 입력 처리를 참조하세요.

사용 시기: Claude가 변경을 실행하지 않고 제안만 하기를 원할 때, 예를 들어 코드 리뷰 중이거나 변경 사항이 적용되기 전에 승인해야 할 때 사용합니다.

권한 구성

권한 모드, 훅, 선언적 허용/거부 규칙을 사용하여 에이전트의 도구 사용 방식을 제어합니다.

권한 평가 방식

Claude가 도구를 요청하면 SDK는 다음 순서로 권한을 확인합니다:

훅
훅을 먼저 실행하여 허용, 거부 또는 다음 단계로 진행할 수 있습니다
권한 규칙
settings.json에 정의된 규칙을 다음 순서로 확인합니다: deny 규칙 먼저(다른 규칙에 관계없이 차단), 그다음 allow 규칙(일치하면 허용), 그다음 ask 규칙(승인 요청). 이러한 선언적 규칙을 사용하면 코드를 작성하지 않고도 특정 도구를 사전 승인, 차단 또는 승인 요구할 수 있습니다.
권한 모드
활성 권한 모드(bypassPermissions, acceptEdits, dontAsk 등)를 적용합니다
canUseTool 콜백
규칙이나 모드로 해결되지 않으면 canUseTool 콜백을 호출하여 결정합니다

이 페이지는 기본 동작을 제어하는 정적 구성인 권한 모드(3단계)에 초점을 맞춥니다. 다른 단계에 대해서는:

훅: 도구 요청을 허용, 거부 또는 수정하는 사용자 정의 코드를 실행합니다. 훅으로 실행 제어를 참조하세요.
권한 규칙: settings.json에서 선언적 허용/거부 규칙을 구성합니다. 권한 설정을 참조하세요.
canUseTool 콜백: 런타임에 사용자에게 승인을 요청합니다. 승인 및 사용자 입력 처리를 참조하세요.

권한 모드

사용 가능한 모드

SDK는 다음 권한 모드를 지원합니다:

모드	설명	도구 동작
`default`	표준 권한 동작	자동 승인 없음; 일치하지 않는 도구는 `canUseTool` 콜백을 트리거합니다
`acceptEdits`	파일 편집 자동 수락	파일 편집 및 파일시스템 작업(`mkdir`, `rm`, `mv` 등)이 자동으로 승인됩니다
`bypassPermissions`	모든 권한 검사 우회	모든 도구가 권한 프롬프트 없이 실행됩니다(주의하여 사용)
`plan`	계획 모드	도구 실행 없음; Claude가 변경 없이 계획만 수립합니다

권한 모드 설정

쿼리를 시작할 때 권한 모드를 한 번 설정하거나, 세션이 활성화된 동안 동적으로 변경할 수 있습니다.

모드 세부 정보

편집 수락 모드 (`acceptEdits`)

자동 승인되는 작업:

파일 편집 (Edit, Write 도구)
파일시스템 명령: mkdir, touch, rm, mv, cp

사용 시기: Claude의 편집을 신뢰하고 더 빠른 반복을 원할 때, 예를 들어 프로토타이핑 중이거나 격리된 디렉토리에서 작업할 때 사용합니다.

권한 우회 모드 (`bypassPermissions`)

프롬프트 없이 모든 도구 사용을 자동 승인합니다. 훅은 여전히 실행되며 필요한 경우 작업을 차단할 수 있습니다.

권한 구성

권한 평가 방식

권한 모드

사용 가능한 모드

권한 모드 설정

모드 세부 정보

편집 수락 모드 (`acceptEdits`)

권한 우회 모드 (`bypassPermissions`)

계획 모드 (`plan`)

관련 리소스

권한 구성

권한 평가 방식

권한 모드

사용 가능한 모드

권한 모드 설정

모드 세부 정보

편집 수락 모드 (`acceptEdits`)

권한 우회 모드 (`bypassPermissions`)

계획 모드 (`plan`)

관련 리소스

권한 평가 방식

권한 모드

사용 가능한 모드

권한 모드 설정

모드 세부 정보

편집 수락 모드 (acceptEdits)

권한 우회 모드 (bypassPermissions)

계획 모드 (plan)

관련 리소스

권한 평가 방식

권한 모드

사용 가능한 모드

권한 모드 설정

모드 세부 정보

편집 수락 모드 (acceptEdits)

권한 우회 모드 (bypassPermissions)

계획 모드 (plan)

관련 리소스

편집 수락 모드 (`acceptEdits`)

권한 우회 모드 (`bypassPermissions`)

계획 모드 (`plan`)

편집 수락 모드 (`acceptEdits`)

권한 우회 모드 (`bypassPermissions`)

계획 모드 (`plan`)