SDK 권한

Claude Agent SDK는 애플리케이션에서 Claude가 도구를 사용하는 방법을 관리할 수 있는 강력한 권한 제어 기능을 제공합니다.

이 가이드는 canUseTool 콜백, 훅, settings.json 권한 규칙을 사용하여 권한 시스템을 구현하는 방법을 다룹니다. 완전한 API 문서는 TypeScript SDK 참조를 참조하세요.

개요

Claude Agent SDK는 도구 사용을 제어하는 네 가지 보완적인 방법을 제공합니다:

1. 권한 모드 - 모든 도구에 영향을 미치는 전역 권한 동작 설정
2. canUseTool 콜백 - 다른 규칙으로 다루어지지 않는 경우를 위한 런타임 권한 핸들러
3. 훅 - 사용자 정의 로직으로 모든 도구 실행에 대한 세밀한 제어
4. 권한 규칙 (settings.json) - 통합된 bash 명령 파싱을 포함한 선언적 허용/거부 규칙

각 접근 방식의 사용 사례:

• 권한 모드 - 전체 권한 동작 설정 (계획, 편집 자동 승인, 검사 우회)
• canUseTool - 다루어지지 않은 경우에 대한 동적 승인, 사용자에게 권한 요청
• 훅 - 모든 도구 실행에 대한 프로그래밍적 제어
• 권한 규칙 - 지능적인 bash 명령 파싱을 포함한 정적 정책

권한 흐름 다이어그램

%%{init: {"theme": "base", "themeVariables": {"edgeLabelBackground": "#F0F0EB", "lineColor": "#91918D"}, "flowchart": {"edgeLabelMarginX": 12, "edgeLabelMarginY": 8}}}%%
flowchart TD
    Start([도구 요청]) --> PreHook(PreToolUse Hook)

    PreHook -->|  허용  | Execute(도구 실행)
    PreHook -->|  거부  | Denied(거부됨)
    PreHook -->|  문의  | Callback(canUseTool Callback)
    PreHook -->|  계속  | Deny(거부 규칙 확인)

    Deny -->|  일치  | Denied
    Deny -->|  일치하지 않음  | Allow(허용 규칙 확인)

    Allow -->|  일치  | Execute
    Allow -->|  일치하지 않음  | Ask(문의 규칙 확인)

    Ask -->|  일치  | Callback
    Ask -->|  일치하지 않음  | Mode{권한 모드?}

    Mode -->|  bypassPermissions  | Execute
    Mode -->|  기타 모드  | Callback

    Callback -->|  허용  | Execute
    Callback -->|  거부  | Denied

    Denied --> DeniedResponse([에이전트에 피드백])

    Execute --> PostHook(PostToolUse Hook)
    PostHook --> Done([도구 응답])

    style Start fill:#F0F0EB,stroke:#D9D8D5,color:#191919

    style Denied fill:#BF4D43,color:#fff
    style DeniedResponse fill:#BF4D43,color:#fff
    style Execute fill:#DAAF91,color:#191919
    style Done fill:#DAAF91,color:#191919

    classDef hookClass fill:#CC785C,color:#fff
    class PreHook,PostHook hookClass

    classDef ruleClass fill:#EBDBBC,color:#191919
    class Deny,Allow,Ask ruleClass

    classDef modeClass fill:#A8DAEF,color:#191919
    class Mode modeClass

    classDef callbackClass fill:#D4A27F,color:#191919
    class Callback callbackClass

처리 순서: PreToolUse Hook → 거부 규칙 → 허용 규칙 → 문의 규칙 → 권한 모드 확인 → canUseTool Callback → PostToolUse Hook

권한 모드

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

사용 가능한 모드

SDK는 각각 다른 동작을 가진 네 가지 권한 모드를 지원합니다:

권한 모드 설정

권한 모드를 설정하는 두 가지 방법이 있습니다:

1. 초기 구성

쿼리를 생성할 때 모드를 설정합니다:

import { query } from "@anthropic-ai/claude-agent-sdk";

const result = await query({
  prompt: "이 코드를 리팩터링하는 데 도움을 주세요",
  options: {
    permissionMode: 'default'  // 표준 권한 모드
  }
});

2. 동적 모드 변경 (스트리밍만)

스트리밍 세션 중에 모드를 변경합니다:

import { query } from "@anthropic-ai/claude-agent-sdk";

// 스트리밍 입력을 위한 비동기 제너레이터 생성
async function* streamInput() {
  yield { 
    type: 'user',
    message: { 
      role: 'user', 
      content: "기본 권한으로 시작해봅시다" 
    }
  };
  
  // 대화 중 나중에...
  yield {
    type: 'user',
    message: {
      role: 'user',
      content: "이제 개발 속도를 높여봅시다"
    }
  };
}

const q = query({
  prompt: streamInput(),
  options: {
    permissionMode: 'default'  // 기본 모드로 시작
  }
});

// 동적으로 모드 변경
await q.setPermissionMode('acceptEdits');

// 메시지 처리
for await (const message of q) {
  console.log(message);
}

모드별 동작

편집 승인 모드 (acceptEdits)

편집 승인 모드에서:

• 모든 파일 편집이 자동으로 승인됩니다
• 파일시스템 작업 (mkdir, touch, rm 등)이 자동 승인됩니다
• 다른 도구들은 여전히 일반적인 권한이 필요합니다
• Claude의 편집을 신뢰할 때 개발 속도를 높입니다
• 빠른 프로토타이핑과 반복에 유용합니다

자동 승인되는 작업:

• 파일 편집 (Edit, Write 도구)
• Bash 파일시스템 명령 (mkdir, touch, rm, mv, cp)
• 파일 생성 및 삭제

권한 우회 모드 (bypassPermissions)

권한 우회 모드에서:

• 모든 도구 사용이 자동으로 승인됩니다
• 권한 프롬프트가 나타나지 않습니다
• 훅은 여전히 실행됩니다 (여전히 작업을 차단할 수 있음)
• 극도로 주의해서 사용하세요 - Claude가 전체 시스템 액세스 권한을 갖습니다
• 제어된 환경에서만 권장됩니다

권한 흐름에서의 모드 우선순위

권한 모드는 권한 흐름의 특정 지점에서 평가됩니다:

1. 훅이 먼저 실행됩니다 - 허용, 거부, 문의 또는 계속할 수 있습니다
2. 거부 규칙이 확인됩니다 - 모드에 관계없이 도구를 차단합니다
3. 허용 규칙이 확인됩니다 - 일치하면 도구를 허용합니다
4. 문의 규칙이 확인됩니다 - 일치하면 권한을 요청합니다
5. 권한 모드가 평가됩니다:
   • bypassPermissions 모드 - 활성화되면 나머지 모든 도구를 허용합니다
   • 기타 모드 - canUseTool 콜백에 위임합니다
6. canUseTool 콜백 - 나머지 경우를 처리합니다

이는 다음을 의미합니다:

• 훅은 bypassPermissions 모드에서도 항상 도구 사용을 제어할 수 있습니다
• 명시적 거부 규칙은 모든 권한 모드를 재정의합니다
• 문의 규칙은 권한 모드보다 먼저 평가됩니다
• bypassPermissions 모드는 일치하지 않는 도구에 대해 canUseTool 콜백을 재정의합니다

모범 사례

1. 기본 모드 사용 - 일반적인 권한 검사로 제어된 실행을 위해
2. acceptEdits 모드 사용 - 격리된 파일이나 디렉터리에서 작업할 때
3. bypassPermissions 피하기 - 프로덕션이나 민감한 데이터가 있는 시스템에서
4. 모드와 훅 결합 - 세밀한 제어를 위해
5. 동적으로 모드 전환 - 작업 진행 상황과 신뢰도에 따라

모드 진행 예시:

// 제어된 실행을 위해 기본 모드로 시작
permissionMode: 'default'

// 빠른 반복을 위해 acceptEdits로 전환
await q.setPermissionMode('acceptEdits')

canUseTool

canUseTool 콜백은 query 함수를 호출할 때 옵션으로 전달됩니다. 도구 이름과 입력 매개변수를 받고, 허용 또는 거부 결정을 반환해야 합니다.

canUseTool은 Claude Code가 사용자에게 권한 프롬프트를 표시할 때마다 실행됩니다. 예를 들어, 훅과 권한 규칙이 이를 다루지 않고 acceptEdits 모드가 아닐 때입니다.

다음은 대화형 도구 승인을 구현하는 방법을 보여주는 완전한 예시입니다:

import { query } from "@anthropic-ai/claude-agent-sdk";

async function promptForToolApproval(toolName: string, input: any) {
  console.log("\n🔧 도구 요청:");
  console.log(`   도구: ${toolName}`);
  
  // 도구 매개변수 표시
  if (input && Object.keys(input).length > 0) {
    console.log("   매개변수:");
    for (const [key, value] of Object.entries(input)) {
      let displayValue = value;
      if (typeof value === 'string' && value.length > 100) {
        displayValue = value.substring(0, 100) + "...";
      } else if (typeof value === 'object') {
        displayValue = JSON.stringify(value, null, 2);
      }
      console.log(`     ${key}: ${displayValue}`);
    }
  }
  
  // 사용자 승인 받기 (UI 로직으로 교체)
  const approved = await getUserApproval();
  
  if (approved) {
    console.log("   ✅ 승인됨\n");
    return {
      behavior: "allow",
      updatedInput: input
    };
  } else {
    console.log("   ❌ 거부됨\n");
    return {
      behavior: "deny",
      message: "사용자가 이 도구에 대한 권한을 거부했습니다"
    };
  }
}

// 권한 콜백 사용
const result = await query({
  prompt: "이 코드베이스를 분석하는 데 도움을 주세요",
  options: {
    canUseTool: async (toolName, input) => {
      return promptForToolApproval(toolName, input);
    }
  }
});

관련 리소스

• 훅 가이드 - 도구 실행에 대한 세밀한 제어를 위한 훅 구현 방법 학습
• 설정: 권한 규칙 - bash 명령 파싱을 포함한 선언적 허용/거부 규칙 구성