Agent SDK 참고 자료 - TypeScript

npm install @anthropic-ai/claude-agent-sdk

function query({
  prompt,
  options
}: {
  prompt: string | AsyncIterable<SDKUserMessage>;
  options?: Options;
}): Query

function tool<Schema extends ZodRawShape>(
  name: string,
  description: string,
  inputSchema: Schema,
  handler: (args: z.infer<ZodObject<Schema>>, extra: unknown) => Promise<CallToolResult>
): SdkMcpToolDefinition<Schema>

function createSdkMcpServer(options: {
  name: string;
  version?: string;
  tools?: Array<SdkMcpToolDefinition<any>>;
}): McpSdkServerConfigWithInstance

interface Query extends AsyncGenerator<SDKMessage, void> {
  interrupt(): Promise<void>;
  rewindFiles(userMessageUuid: string): Promise<void>;
  setPermissionMode(mode: PermissionMode): Promise<void>;
  setModel(model?: string): Promise<void>;
  setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;
  supportedCommands(): Promise<SlashCommand[]>;
  supportedModels(): Promise<ModelInfo[]>;
  mcpServerStatus(): Promise<McpServerStatus[]>;
  accountInfo(): Promise<AccountInfo>;
}

type AgentDefinition = {
  description: string;
  tools?: string[];
  prompt: string;
  model?: 'sonnet' | 'opus' | 'haiku' | 'inherit';
}

type SettingSource = 'user' | 'project' | 'local';

// SDK v0.0.x처럼 모든 설정 로드
const result = query({
  prompt: "이 코드를 분석하세요",
  options: {
    settingSources: ['user', 'project', 'local']  // 모든 설정 로드
  }
});

// 프로젝트 설정만 로드, 사용자 및 로컬 무시
const result = query({
  prompt: "CI 검사 실행",
  options: {
    settingSources: ['project']  // .claude/settings.json만
  }
});

// 로컬 설정을 제외하여 CI에서 일관된 동작 보장
const result = query({
  prompt: "테스트 실행",
  options: {
    settingSources: ['project'],  // 팀 공유 설정만
    permissionMode: 'bypassPermissions'
  }
});

// 모든 것을 프로그래밍 방식으로 정의 (기본 동작)
// 파일 시스템 종속성 없음 - settingSources는 기본값이 []
const result = query({
  prompt: "이 PR을 검토하세요",
  options: {
    // settingSources: []는 기본값이므로 지정할 필요 없음
    agents: { /* ... */ },
    mcpServers: { /* ... */ },
    allowedTools: ['Read', 'Grep', 'Glob']
  }
});

// 프로젝트 설정을 로드하여 CLAUDE.md 파일 포함
const result = query({
  prompt: "프로젝트 규칙에 따라 새 기능 추가",
  options: {
    systemPrompt: {
      type: 'preset',
      preset: 'claude_code'  // CLAUDE.md를 사용하려면 필수
    },
    settingSources: ['project'],  // 프로젝트 디렉토리에서 CLAUDE.md 로드
    allowedTools: ['Read', 'Write', 'Edit']
  }
});

type PermissionMode =
  | 'default'           // 표준 권한 동작
  | 'acceptEdits'       // 파일 편집 자동 수락
  | 'bypassPermissions' // 모든 권한 검사 우회
  | 'plan'              // 계획 모드 - 실행 없음

type CanUseTool = (
  toolName: string,
  input: ToolInput,
  options: {
    signal: AbortSignal;
    suggestions?: PermissionUpdate[];
  }
) => Promise<PermissionResult>;

type PermissionResult = 
  | {
      behavior: 'allow';
      updatedInput: ToolInput;
      updatedPermissions?: PermissionUpdate[];
    }
  | {
      behavior: 'deny';
      message: string;
      interrupt?: boolean;
    }

type McpServerConfig = 
  | McpStdioServerConfig
  | McpSSEServerConfig
  | McpHttpServerConfig
  | McpSdkServerConfigWithInstance;

type McpStdioServerConfig = {
  type?: 'stdio';
  command: string;
  args?: string[];
  env?: Record<string, string>;
}

type McpSSEServerConfig = {
  type: 'sse';
  url: string;
  headers?: Record<string, string>;
}

type McpHttpServerConfig = {
  type: 'http';
  url: string;
  headers?: Record<string, string>;
}

type McpSdkServerConfigWithInstance = {
  type: 'sdk';
  name: string;
  instance: McpServer;
}

type SdkPluginConfig = {
  type: 'local';
  path: string;
}

plugins: [
  { type: 'local', path: './my-plugin' },
  { type: 'local', path: '/absolute/path/to/plugin' }
]

type SDKMessage = 
  | SDKAssistantMessage
  | SDKUserMessage
  | SDKUserMessageReplay
  | SDKResultMessage
  | SDKSystemMessage
  | SDKPartialAssistantMessage
  | SDKCompactBoundaryMessage;

type SDKAssistantMessage = {
  type: 'assistant';
  uuid: UUID;
  session_id: string;
  message: APIAssistantMessage; // Anthropic SDK에서
  parent_tool_use_id: string | null;
}

type SDKUserMessage = {
  type: 'user';
  uuid?: UUID;
  session_id: string;
  message: APIUserMessage; // Anthropic SDK에서
  parent_tool_use_id: string | null;
}

type SDKUserMessageReplay = {
  type: 'user';
  uuid: UUID;
  session_id: string;
  message: APIUserMessage;
  parent_tool_use_id: string | null;
}

type SDKResultMessage =
  | {
      type: 'result';
      subtype: 'success';
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      result: string;
      total_cost_usd: number;
      usage: NonNullableUsage;
      modelUsage: { [modelName: string]: ModelUsage };
      permission_denials: SDKPermissionDenial[];
      structured_output?: unknown;
    }
  | {
      type: 'result';
      subtype:
        | 'error_max_turns'
        | 'error_during_execution'
        | 'error_max_budget_usd'
        | 'error_max_structured_output_retries';
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      total_cost_usd: number;
      usage: NonNullableUsage;
      modelUsage: { [modelName: string]: ModelUsage };
      permission_denials: SDKPermissionDenial[];
      errors: string[];
    }

type SDKSystemMessage = {
  type: 'system';
  subtype: 'init';
  uuid: UUID;
  session_id: string;
  apiKeySource: ApiKeySource;
  cwd: string;
  tools: string[];
  mcp_servers: {
    name: string;
    status: string;
  }[];
  model: string;
  permissionMode: PermissionMode;
  slash_commands: string[];
  output_style: string;
}

type SDKPartialAssistantMessage = {
  type: 'stream_event';
  event: RawMessageStreamEvent; // Anthropic SDK에서
  parent_tool_use_id: string | null;
  uuid: UUID;
  session_id: string;
}

type SDKCompactBoundaryMessage = {
  type: 'system';
  subtype: 'compact_boundary';
  uuid: UUID;
  session_id: string;
  compact_metadata: {
    trigger: 'manual' | 'auto';
    pre_tokens: number;
  };
}

type SDKPermissionDenial = {
  tool_name: string;
  tool_use_id: string;
  tool_input: ToolInput;
}

type HookEvent =
  | 'PreToolUse'
  | 'PostToolUse'
  | 'PostToolUseFailure'
  | 'Notification'
  | 'UserPromptSubmit'
  | 'SessionStart'
  | 'SessionEnd'
  | 'Stop'
  | 'SubagentStart'
  | 'SubagentStop'
  | 'PreCompact'
  | 'PermissionRequest';

type HookCallback = (
  input: HookInput, // 모든 후크 입력 타입의 합집합
  toolUseID: string | undefined,
  options: { signal: AbortSignal }
) => Promise<HookJSONOutput>;

interface HookCallbackMatcher {
  matcher?: string;
  hooks: HookCallback[];
}

type HookInput =
  | PreToolUseHookInput
  | PostToolUseHookInput
  | PostToolUseFailureHookInput
  | NotificationHookInput
  | UserPromptSubmitHookInput
  | SessionStartHookInput
  | SessionEndHookInput
  | StopHookInput
  | SubagentStartHookInput
  | SubagentStopHookInput
  | PreCompactHookInput
  | PermissionRequestHookInput;

type BaseHookInput = {
  session_id: string;
  transcript_path: string;
  cwd: string;
  permission_mode?: string;
}

type PreToolUseHookInput = BaseHookInput & {
  hook_event_name: 'PreToolUse';
  tool_name: string;
  tool_input: unknown;
}

type PostToolUseHookInput = BaseHookInput & {
  hook_event_name: 'PostToolUse';
  tool_name: string;
  tool_input: unknown;
  tool_response: unknown;
}

type PostToolUseFailureHookInput = BaseHookInput & {
  hook_event_name: 'PostToolUseFailure';
  tool_name: string;
  tool_input: unknown;
  error: string;
  is_interrupt?: boolean;
}

type NotificationHookInput = BaseHookInput & {
  hook_event_name: 'Notification';
  message: string;
  title?: string;
}

type UserPromptSubmitHookInput = BaseHookInput & {
  hook_event_name: 'UserPromptSubmit';
  prompt: string;
}

type SessionStartHookInput = BaseHookInput & {
  hook_event_name: 'SessionStart';
  source: 'startup' | 'resume' | 'clear' | 'compact';
}

type SessionEndHookInput = BaseHookInput & {
  hook_event_name: 'SessionEnd';
  reason: ExitReason;  // EXIT_REASONS 배열의 문자열
}

type StopHookInput = BaseHookInput & {
  hook_event_name: 'Stop';
  stop_hook_active: boolean;
}

type SubagentStartHookInput = BaseHookInput & {
  hook_event_name: 'SubagentStart';
  agent_id: string;
  agent_type: string;
}

type SubagentStopHookInput = BaseHookInput & {
  hook_event_name: 'SubagentStop';
  stop_hook_active: boolean;
}

type PreCompactHookInput = BaseHookInput & {
  hook_event_name: 'PreCompact';
  trigger: 'manual' | 'auto';
  custom_instructions: string | null;
}

type PermissionRequestHookInput = BaseHookInput & {
  hook_event_name: 'PermissionRequest';
  tool_name: string;
  tool_input: unknown;
  permission_suggestions?: PermissionUpdate[];
}

type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput;

type AsyncHookJSONOutput = {
  async: true;
  asyncTimeout?: number;
}

type SyncHookJSONOutput = {
  continue?: boolean;
  suppressOutput?: boolean;
  stopReason?: string;
  decision?: 'approve' | 'block';
  systemMessage?: string;
  reason?: string;
  hookSpecificOutput?:
    | {
        hookEventName: 'PreToolUse';
        permissionDecision?: 'allow' | 'deny' | 'ask';
        permissionDecisionReason?: string;
        updatedInput?: Record<string, unknown>;
      }
    | {
        hookEventName: 'UserPromptSubmit';
        additionalContext?: string;
      }
    | {
        hookEventName: 'SessionStart';
        additionalContext?: string;
      }
    | {
        hookEventName: 'PostToolUse';
        additionalContext?: string;
      };
}

type ToolInput =
  | AgentInput
  | AskUserQuestionInput
  | BashInput
  | BashOutputInput
  | FileEditInput
  | FileReadInput
  | FileWriteInput
  | GlobInput
  | GrepInput
  | KillShellInput
  | NotebookEditInput
  | WebFetchInput
  | WebSearchInput
  | TodoWriteInput
  | ExitPlanModeInput
  | ListMcpResourcesInput
  | ReadMcpResourceInput;

interface AgentInput {
  /**
   * 작업의 짧은 설명 (3-5 단어)
   */
  description: string;
  /**
   * 에이전트가 수행할 작업
   */
  prompt: string;
  /**
   * 이 작업에 사용할 특화된 에이전트의 유형
   */
  subagent_type: string;
}

interface AskUserQuestionInput {
  /**
   * 사용자에게 물어볼 질문 (1-4개 질문)
   */
  questions: Array<{
    /**
     * 사용자에게 물어볼 완전한 질문입니다. 명확하고 구체적이어야 하며
     * 물음표로 끝나야 합니다.
     */
    question: string;
    /**
     * 칩/태그로 표시되는 매우 짧은 레이블 (최대 12자).
     * 예: "Auth method", "Library", "Approach"
     */
    header: string;
    /**
     * 사용 가능한 선택 (2-4개 옵션). "Other" 옵션은
     * 자동으로 제공됩니다.
     */
    options: Array<{
      /**
       * 이 옵션의 표시 텍스트 (1-5 단어)
       */
      label: string;
      /**
       * 이 옵션이 의미하는 것에 대한 설명
       */
      description: string;
    }>;
    /**
     * 여러 선택을 허용하려면 true로 설정
     */
    multiSelect: boolean;
  }>;
  /**
   * 권한 시스템에서 채워진 사용자 답변입니다.
   * 질문 텍스트를 선택된 옵션 레이블에 매핑합니다.
   * 다중 선택 답변은 쉼표로 구분됩니다.
   */
  answers?: Record<string, string>;
}

interface BashInput {
  /**
   * 실행할 명령
   */
  command: string;
  /**
   * 선택적 시간 제한 (밀리초, 최대 600000)
   */
  timeout?: number;
  /**
   * 이 명령이 5-10 단어로 수행하는 작업에 대한 명확하고 간결한 설명
   */
  description?: string;
  /**
   * 이 명령을 백그라운드에서 실행하려면 true로 설정
   */
  run_in_background?: boolean;
}

interface BashOutputInput {
  /**
   * 출력을 검색할 백그라운드 셸의 ID
   */
  bash_id: string;
  /**
   * 출력 라인을 필터링하기 위한 선택적 정규식
   */
  filter?: string;
}

interface FileEditInput {
  /**
   * 수정할 파일의 절대 경로
   */
  file_path: string;
  /**
   * 바꿀 텍스트
   */
  old_string: string;
  /**
   * 바꿀 텍스트 (old_string과 달라야 함)
   */
  new_string: string;
  /**
   * old_string의 모든 발생을 바꿈 (기본값 false)
   */
  replace_all?: boolean;
}

interface FileReadInput {
  /**
   * 읽을 파일의 절대 경로
   */
  file_path: string;
  /**
   * 읽기를 시작할 라인 번호
   */
  offset?: number;
  /**
   * 읽을 라인 수
   */
  limit?: number;
}

interface FileWriteInput {
  /**
   * 쓸 파일의 절대 경로
   */
  file_path: string;
  /**
   * 파일에 쓸 내용
   */
  content: string;
}

interface GlobInput {
  /**
   * 파일과 일치시킬 glob 패턴
   */
  pattern: string;
  /**
   * 검색할 디렉토리 (기본값 cwd)
   */
  path?: string;
}

interface GrepInput {
  /**
   * 검색할 정규식 패턴
   */
  pattern: string;
  /**
   * 검색할 파일 또는 디렉토리 (기본값 cwd)
   */
  path?: string;
  /**
   * 파일을 필터링할 glob 패턴 (예: "*.js")
   */
  glob?: string;
  /**
   * 검색할 파일 타입 (예: "js", "py", "rust")
   */
  type?: string;
  /**
   * 출력 모드: "content", "files_with_matches" 또는 "count"
   */
  output_mode?: 'content' | 'files_with_matches' | 'count';
  /**
   * 대소문자 구분 없는 검색
   */
  '-i'?: boolean;
  /**
   * 라인 번호 표시 (콘텐츠 모드의 경우)
   */
  '-n'?: boolean;
  /**
   * 각 일치 항목 앞에 표시할 라인
   */
  '-B'?: number;
  /**
   * 각 일치 항목 뒤에 표시할 라인
   */
  '-A'?: number;
  /**
   * 각 일치 항목 앞뒤에 표시할 라인
   */
  '-C'?: number;
  /**
   * 출력을 처음 N개 라인/항목으로 제한
   */
  head_limit?: number;
  /**
   * 다중 라인 모드 활성화
   */
  multiline?: boolean;
}

interface KillShellInput {
  /**
   * 종료할 백그라운드 셸의 ID
   */
  shell_id: string;
}

interface NotebookEditInput {
  /**
   * 편집할 Jupyter 노트북 파일의 절대 경로
   */
  notebook_path: string;
  /**
   * 편집할 셀의 ID
   */
  cell_id?: string;
  /**
   * 셀의 새로운 소스
   */
  new_source: string;
  /**
   * 셀의 타입 (code 또는 markdown)
   */
  cell_type?: 'code' | 'markdown';
  /**
   * 편집 타입 (replace, insert, delete)
   */
  edit_mode?: 'replace' | 'insert' | 'delete';
}

interface WebFetchInput {
  /**
   * 콘텐츠를 가져올 URL
   */
  url: string;
  /**
   * 가져온 콘텐츠에서 실행할 프롬프트
   */
  prompt: string;
}

interface WebSearchInput {
  /**
   * 사용할 검색 쿼리
   */
  query: string;
  /**
   * 이 도메인의 결과만 포함
   */
  allowed_domains?: string[];
  /**
   * 이 도메인의 결과는 절대 포함하지 않음
   */
  blocked_domains?: string[];
}

interface TodoWriteInput {
  /**
   * 업데이트된 할 일 목록
   */
  todos: Array<{
    /**
     * 작업 설명
     */
    content: string;
    /**
     * 작업 상태
     */
    status: 'pending' | 'in_progress' | 'completed';
    /**
     * 작업 설명의 능동형
     */
    activeForm: string;
  }>;
}

interface ExitPlanModeInput {
  /**
   * 사용자 승인을 위해 실행할 계획
   */
  plan: string;
}

interface ListMcpResourcesInput {
  /**
   * 리소스를 필터링할 선택적 서버 이름
   */
  server?: string;
}

interface ReadMcpResourceInput {
  /**
   * MCP 서버 이름
   */
  server: string;
  /**
   * 읽을 리소스 URI
   */
  uri: string;
}

type ToolOutput =
  | TaskOutput
  | AskUserQuestionOutput
  | BashOutput
  | BashOutputToolOutput
  | EditOutput
  | ReadOutput
  | WriteOutput
  | GlobOutput
  | GrepOutput
  | KillBashOutput
  | NotebookEditOutput
  | WebFetchOutput
  | WebSearchOutput
  | TodoWriteOutput
  | ExitPlanModeOutput
  | ListMcpResourcesOutput
  | ReadMcpResourceOutput;

interface TaskOutput {
  /**
   * 서브에이전트의 최종 결과 메시지
   */
  result: string;
  /**
   * 토큰 사용 통계
   */
  usage?: {
    input_tokens: number;
    output_tokens: number;
    cache_creation_input_tokens?: number;
    cache_read_input_tokens?: number;
  };
  /**
   * USD 단위의 총 비용
   */
  total_cost_usd?: number;
  /**
   * 실행 기간 (밀리초)
   */
  duration_ms?: number;
}

interface AskUserQuestionOutput {
  /**
   * 물어본 질문
   */
  questions: Array<{
    question: string;
    header: string;
    options: Array<{
      label: string;
      description: string;
    }>;
    multiSelect: boolean;
  }>;
  /**
   * 사용자가 제공한 답변입니다.
   * 질문 텍스트를 답변 문자열에 매핑합니다.
   * 다중 선택 답변은 쉼표로 구분됩니다.
   */
  answers: Record<string, string>;
}

interface BashOutput {
  /**
   * 결합된 stdout 및 stderr 출력
   */
  output: string;
  /**
   * 명령의 종료 코드
   */
  exitCode: number;
  /**
   * 시간 제한으로 인해 명령이 종료되었는지 여부
   */
  killed?: boolean;
  /**
   * 백그라운드 프로세스의 셸 ID
   */
  shellId?: string;
}

interface BashOutputToolOutput {
  /**
   * 마지막 확인 이후의 새로운 출력
   */
  output: string;
  /**
   * 현재 셸 상태
   */
  status: 'running' | 'completed' | 'failed';
  /**
   * 종료 코드 (완료되었을 때)
   */
  exitCode?: number;
}

interface EditOutput {
  /**
   * 확인 메시지
   */
  message: string;
  /**
   * 수행된 교체 수
   */
  replacements: number;
  /**
   * 편집된 파일 경로
   */
  file_path: string;
}

type ReadOutput = 
  | TextFileOutput
  | ImageFileOutput
  | PDFFileOutput
  | NotebookFileOutput;

interface TextFileOutput {
  /**
   * 줄 번호가 있는 파일 내용
   */
  content: string;
  /**
   * 파일의 총 줄 수
   */
  total_lines: number;
  /**
   * 실제로 반환된 줄 수
   */
  lines_returned: number;
}

interface ImageFileOutput {
  /**
   * Base64로 인코딩된 이미지 데이터
   */
  image: string;
  /**
   * 이미지 MIME 타입
   */
  mime_type: string;
  /**
   * 파일 크기(바이트)
   */
  file_size: number;
}

interface PDFFileOutput {
  /**
   * 페이지 내용 배열
   */
  pages: Array<{
    page_number: number;
    text?: string;
    images?: Array<{
      image: string;
      mime_type: string;
    }>;
  }>;
  /**
   * 총 페이지 수
   */
  total_pages: number;
}

interface NotebookFileOutput {
  /**
   * Jupyter 노트북 셀
   */
  cells: Array<{
    cell_type: 'code' | 'markdown';
    source: string;
    outputs?: any[];
    execution_count?: number;
  }>;
  /**
   * 노트북 메타데이터
   */
  metadata?: Record<string, any>;
}

interface WriteOutput {
  /**
   * 성공 메시지
   */
  message: string;
  /**
   * 작성된 바이트 수
   */
  bytes_written: number;
  /**
   * 작성된 파일 경로
   */
  file_path: string;
}

interface GlobOutput {
  /**
   * 일치하는 파일 경로 배열
   */
  matches: string[];
  /**
   * 찾은 일치 항목 수
   */
  count: number;
  /**
   * 사용된 검색 디렉토리
   */
  search_path: string;
}

type GrepOutput = 
  | GrepContentOutput
  | GrepFilesOutput
  | GrepCountOutput;

interface GrepContentOutput {
  /**
   * 컨텍스트가 있는 일치하는 줄
   */
  matches: Array<{
    file: string;
    line_number?: number;
    line: string;
    before_context?: string[];
    after_context?: string[];
  }>;
  /**
   * 총 일치 항목 수
   */
  total_matches: number;
}

interface GrepFilesOutput {
  /**
   * 일치 항목을 포함하는 파일
   */
  files: string[];
  /**
   * 일치 항목이 있는 파일 수
   */
  count: number;
}

interface GrepCountOutput {
  /**
   * 파일별 일치 항목 수
   */
  counts: Array<{
    file: string;
    count: number;
  }>;
  /**
   * 모든 파일의 총 일치 항목 수
   */
  total: number;
}

interface KillBashOutput {
  /**
   * 성공 메시지
   */
  message: string;
  /**
   * 종료된 셸의 ID
   */
  shell_id: string;
}

interface NotebookEditOutput {
  /**
   * 성공 메시지
   */
  message: string;
  /**
   * 수행된 편집의 유형
   */
  edit_type: 'replaced' | 'inserted' | 'deleted';
  /**
   * 영향을 받은 셀 ID
   */
  cell_id?: string;
  /**
   * 편집 후 노트북의 총 셀 수
   */
  total_cells: number;
}

interface WebFetchOutput {
  /**
   * 프롬프트에 대한 AI 모델의 응답
   */
  response: string;
  /**
   * 가져온 URL
   */
  url: string;
  /**
   * 리다이렉트 후의 최종 URL
   */
  final_url?: string;
  /**
   * HTTP 상태 코드
   */
  status_code?: number;
}

interface WebSearchOutput {
  /**
   * 검색 결과
   */
  results: Array<{
    title: string;
    url: string;
    snippet: string;
    /**
     * 사용 가능한 경우 추가 메타데이터
     */
    metadata?: Record<string, any>;
  }>;
  /**
   * 총 결과 수
   */
  total_results: number;
  /**
   * 검색된 쿼리
   */
  query: string;
}

interface TodoWriteOutput {
  /**
   * 성공 메시지
   */
  message: string;
  /**
   * 현재 할 일 통계
   */
  stats: {
    total: number;
    pending: number;
    in_progress: number;
    completed: number;
  };
}

interface ExitPlanModeOutput {
  /**
   * 확인 메시지
   */
  message: string;
  /**
   * 사용자가 계획을 승인했는지 여부
   */
  approved?: boolean;
}

interface ListMcpResourcesOutput {
  /**
   * 사용 가능한 리소스
   */
  resources: Array<{
    uri: string;
    name: string;
    description?: string;
    mimeType?: string;
    server: string;
  }>;
  /**
   * 총 리소스 수
   */
  total: number;
}

interface ReadMcpResourceOutput {
  /**
   * 리소스 내용
   */
  contents: Array<{
    uri: string;
    mimeType?: string;
    text?: string;
    blob?: string;
  }>;
  /**
   * 리소스를 제공한 서버
   */
  server: string;
}

type PermissionUpdate = 
  | {
      type: 'addRules';
      rules: PermissionRuleValue[];
      behavior: PermissionBehavior;
      destination: PermissionUpdateDestination;
    }
  | {
      type: 'replaceRules';
      rules: PermissionRuleValue[];
      behavior: PermissionBehavior;
      destination: PermissionUpdateDestination;
    }
  | {
      type: 'removeRules';
      rules: PermissionRuleValue[];
      behavior: PermissionBehavior;
      destination: PermissionUpdateDestination;
    }
  | {
      type: 'setMode';
      mode: PermissionMode;
      destination: PermissionUpdateDestination;
    }
  | {
      type: 'addDirectories';
      directories: string[];
      destination: PermissionUpdateDestination;
    }
  | {
      type: 'removeDirectories';
      directories: string[];
      destination: PermissionUpdateDestination;
    }

type PermissionBehavior = 'allow' | 'deny' | 'ask';

type PermissionUpdateDestination = 
  | 'userSettings'     // 전역 사용자 설정
  | 'projectSettings'  // 디렉토리별 프로젝트 설정
  | 'localSettings'    // Gitignored 로컬 설정
  | 'session'          // 현재 세션만

type PermissionRuleValue = {
  toolName: string;
  ruleContent?: string;
}

type ApiKeySource = 'user' | 'project' | 'org' | 'temporary';

type SdkBeta = 'context-1m-2025-08-07';

type SlashCommand = {
  name: string;
  description: string;
  argumentHint: string;
}

type ModelInfo = {
  value: string;
  displayName: string;
  description: string;
}

type McpServerStatus = {
  name: string;
  status: 'connected' | 'failed' | 'needs-auth' | 'pending';
  serverInfo?: {
    name: string;
    version: string;
  };
}

type AccountInfo = {
  email?: string;
  organization?: string;
  subscriptionType?: string;
  tokenSource?: string;
  apiKeySource?: string;
}

type ModelUsage = {
  inputTokens: number;
  outputTokens: number;
  cacheReadInputTokens: number;
  cacheCreationInputTokens: number;
  webSearchRequests: number;
  costUSD: number;
  contextWindow: number;
}

type ConfigScope = 'local' | 'user' | 'project';

type NonNullableUsage = {
  [K in keyof Usage]: NonNullable<Usage[K]>;
}

type Usage = {
  input_tokens: number | null;
  output_tokens: number | null;
  cache_creation_input_tokens?: number | null;
  cache_read_input_tokens?: number | null;
}

type CallToolResult = {
  content: Array<{
    type: 'text' | 'image' | 'resource';
    // 추가 필드는 타입에 따라 다름
  }>;
  isError?: boolean;
}

class AbortError extends Error {}

type SandboxSettings = {
  enabled?: boolean;
  autoAllowBashIfSandboxed?: boolean;
  excludedCommands?: string[];
  allowUnsandboxedCommands?: boolean;
  network?: NetworkSandboxSettings;
  ignoreViolations?: SandboxIgnoreViolations;
  enableWeakerNestedSandbox?: boolean;
}

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

const result = await query({
  prompt: "Build and test my project",
  options: {
    sandbox: {
      enabled: true,
      autoAllowBashIfSandboxed: true,
      excludedCommands: ["docker"],
      network: {
        allowLocalBinding: true,
        allowUnixSockets: ["/var/run/docker.sock"]
      }
    }
  }
});

type NetworkSandboxSettings = {
  allowLocalBinding?: boolean;
  allowUnixSockets?: string[];
  allowAllUnixSockets?: boolean;
  httpProxyPort?: number;
  socksProxyPort?: number;
}

type SandboxIgnoreViolations = {
  file?: string[];
  network?: string[];
}