Documentation 2026-05-08 22:00 UTC to 2026-05-09 04:57 UTC

309 </Tab>309 </Tab>

310</Tabs>310</Tabs>

311 311 

312HTTP(비스트리밍)의 경우 `"type": "http"` 대신 사용합니다.312스트리밍 가능한 HTTP 전송의 경우 `"type": "http"` 대신 사용합니다. `.mcp.json` 및 기타 JSON 구성 파일에서 `"streamable-http"`는 `"http"`의 별칭으로 허용됩니다. 프로그래밍 방식의 `mcpServers` 옵션은 `"http"`만 허용합니다.

313 313 

314### SDK MCP 서버314### SDK MCP 서버

315 315 

2294 2294 

2295```python theme={null}2295```python theme={null}

2296{2296{

2297 "description": str, # A short (3-5 word) description of the task2297 "description": str, # 작업의 짧은 설명 (3-5단어)

2298 "prompt": str, # The task for the agent to perform2298 "prompt": str, # 에이전트가 수행할 작업

2299 "subagent_type": str, # The type of specialized agent to use2299 "subagent_type": str, # 사용할 특화된 에이전트의 유형

2300}2300}

2301```2301```

2302 2302 

2304 2304 

2305```python theme={null}2305```python theme={null}

2306{2306{

2307 "result": str, # Final result from the subagent2307 "result": str, # 서브에이전트의 최종 결과

2308 "usage": dict | None, # Token usage statistics2308 "usage": dict | None, # 토큰 사용 통계

2309 "total_cost_usd": float | None, # Estimated total cost in USD2309 "total_cost_usd": float | None, # USD로 예상되는 총 비용

2310 "duration_ms": int | None, # Execution duration in milliseconds2310 "duration_ms": int | None, # 실행 시간(밀리초)

2311}2311}

2312```2312```

2313 2313 

2321 2321 

2322```python theme={null}2322```python theme={null}

2323{2323{

2324 "questions": [ # Questions to ask the user (1-4 questions)2324 "questions": [ # 사용자에게 물어볼 질문 (1-4개 질문)

2325 {2325 {

2326 "question": str, # The complete question to ask the user2326 "question": str, # 사용자에게 물어볼 완전한 질문

2327 "header": str, # Very short label displayed as a chip/tag (max 12 chars)2327 "header": str, # 칩/태그로 표시되는 매우 짧은 레이블 (최대 12자)

2328 "options": [ # The available choices (2-4 options)2328 "options": [ # 사용 가능한 선택 (2-4개 옵션)

2329 {2329 {

2330 "label": str, # Display text for this option (1-5 words)2330 "label": str, # 이 옵션의 표시 텍스트 (1-5단어)

2331 "description": str, # Explanation of what this option means2331 "description": str, # 이 옵션이 의미하는 바에 대한 설명

2332 }2332 }

2333 ],2333 ],

2334 "multiSelect": bool, # Set to true to allow multiple selections2334 "multiSelect": bool, # 여러 선택을 허용하려면 true로 설정

2335 }2335 }

2336 ],2336 ],

2337 "answers": dict | None, # User answers populated by the permission system2337 "answers": dict[str, str | list[str]] | None,

2338 # 권한 시스템에 의해 채워진 사용자 답변. 다중 선택

2339 # 답변은 레이블 목록 또는 쉼표로 연결된 문자열일 수 있습니다

2338}2340}

2339```2341```

2340 2342 

2342 2344 

2343```python theme={null}2345```python theme={null}

2344{2346{

2345 "questions": [ # The questions that were asked2347 "questions": [ # 물어본 질문

2346 {2348 {

2347 "question": str,2349 "question": str,

2348 "header": str,2350 "header": str,

2350 "multiSelect": bool,2352 "multiSelect": bool,

2351 }2353 }

2352 ],2354 ],

2353 "answers": dict[str, str], # Maps question text to answer string2355 "answers": dict[str, str], # 질문 텍스트를 답변 문자열에 매핑

2354 # Multi-select answers are comma-separated2356 # 다중 선택 답변은 쉼표로 구분됨

2355}2357}

2356```2358```

2357 2359 

2363 2365 

2364```python theme={null}2366```python theme={null}

2365{2367{

2366 "command": str, # The command to execute2368 "command": str, # 실행할 명령

2367 "timeout": int | None, # Optional timeout in milliseconds (max 600000)2369 "timeout": int | None, # 선택적 시간 초과(밀리초 단위, 최대 600000)

2368 "description": str | None, # Clear, concise description (5-10 words)2370 "description": str | None, # 명확하고 간결한 설명 (5-10단어)

2369 "run_in_background": bool | None, # Set to true to run in background2371 "run_in_background": bool | None, # 백그라운드에서 실행하려면 true로 설정

2370}2372}

2371```2373```

2372 2374 

2374 2376 

2375```python theme={null}2377```python theme={null}

2376{2378{

2377 "output": str, # Combined stdout and stderr output2379 "output": str, # 결합된 stdout 및 stderr 출력

2378 "exitCode": int, # Exit code of the command2380 "exitCode": int, # 명령의 종료 코드

2379 "killed": bool | None, # Whether command was killed due to timeout2381 "killed": bool | None, # 시간 초과로 인해 명령이 종료되었는지 여부

2380 "shellId": str | None, # Shell ID for background processes2382 "shellId": str | None, # 백그라운드 프로세스의 셸 ID

2381}2383}

2382```2384```

2383 2385 

2391 2393 

2392```python theme={null}2394```python theme={null}

2393{2395{

2394 "command": str, # Shell script; each stdout line is an event, exit ends the watch2396 "command": str, # 셸 스크립트; 각 stdout 줄은 이벤트이고, 종료는 감시를 끝냅니다

2395 "description": str, # Short description shown in notifications2397 "description": str, # 알림에 표시되는 짧은 설명

2396 "timeout_ms": int | None, # Kill after this deadline (default 300000, max 3600000)2398 "timeout_ms": int | None, # 이 기한 후 종료 (기본값 300000, 최대 3600000)

2397 "persistent": bool | None, # Run for the lifetime of the session; stop with TaskStop2399 "persistent": bool | None, # 세션의 수명 동안 실행; TaskStop으로 중지

2398}2400}

2399```2401```

2400 2402 

2402 2404 

2403```python theme={null}2405```python theme={null}

2404{2406{

2405 "taskId": str, # ID of the background monitor task2407 "taskId": str, # 백그라운드 모니터 작업의 ID

2406 "timeoutMs": int, # Timeout deadline in milliseconds (0 when persistent)2408 "timeoutMs": int, # 밀리초 단위의 시간 초과 기한 (지속적일 때 0)

2407 "persistent": bool | None, # True when running until TaskStop or session end2409 "persistent": bool | None, # TaskStop 또는 세션 종료까지 실행 중일 때 True

2408}2410}

2409```2411```

2410 2412 

2416 2418 

2417```python theme={null}2419```python theme={null}

2418{2420{

2419 "file_path": str, # The absolute path to the file to modify2421 "file_path": str, # 수정할 파일의 절대 경로

2420 "old_string": str, # The text to replace2422 "old_string": str, # 바꿀 텍스트

2421 "new_string": str, # The text to replace it with2423 "new_string": str, # 바꿀 텍스트

2422 "replace_all": bool | None, # Replace all occurrences (default False)2424 "replace_all": bool | None, # 모든 항목 바꾸기 (기본값 False)

2423}2425}

2424```2426```

2425 2427 

2427 2429 

2428```python theme={null}2430```python theme={null}

2429{2431{

2430 "message": str, # Confirmation message2432 "message": str, # 확인 메시지

2431 "replacements": int, # Number of replacements made2433 "replacements": int, # 수행된 바꾸기 수

2432 "file_path": str, # File path that was edited2434 "file_path": str, # 편집된 파일 경로

2433}2435}

2434```2436```

2435 2437 

2441 2443 

2442```python theme={null}2444```python theme={null}

2443{2445{

2444 "file_path": str, # The absolute path to the file to read2446 "file_path": str, # 읽을 파일의 절대 경로

2445 "offset": int | None, # The line number to start reading from2447 "offset": int | None, # 읽기를 시작할 줄 번호

2446 "limit": int | None, # The number of lines to read2448 "limit": int | None, # 읽을 줄 수

2447}2449}

2448```2450```

2449 2451 

2451 2453 

2452```python theme={null}2454```python theme={null}

2453{2455{

2454 "content": str, # File contents with line numbers2456 "content": str, # 줄 번호가 있는 파일 내용

2455 "total_lines": int, # Total number of lines in file2457 "total_lines": int, # 파일의 총 줄 수

2456 "lines_returned": int, # Lines actually returned2458 "lines_returned": int, # 실제로 반환된 줄

2457}2459}

2458```2460```

2459 2461 

2461 2463 

2462```python theme={null}2464```python theme={null}

2463{2465{

2464 "image": str, # Base64 encoded image data2466 "image": str, # Base64로 인코딩된 이미지 데이터

2465 "mime_type": str, # Image MIME type2467 "mime_type": str, # 이미지 MIME 타입

2466 "file_size": int, # File size in bytes2468 "file_size": int, # 파일 크기(바이트)

2467}2469}

2468```2470```

2469 2471 

2475 2477 

2476```python theme={null}2478```python theme={null}

2477{2479{

2478 "file_path": str, # The absolute path to the file to write2480 "file_path": str, # 쓸 파일의 절대 경로

2479 "content": str, # The content to write to the file2481 "content": str, # 파일에 쓸 내용

2480}2482}

2481```2483```

2482 2484 

2484 2486 

2485```python theme={null}2487```python theme={null}

2486{2488{

2487 "message": str, # Success message2489 "message": str, # 성공 메시지

2488 "bytes_written": int, # Number of bytes written2490 "bytes_written": int, # 쓴 바이트 수

2489 "file_path": str, # File path that was written2491 "file_path": str, # 쓴 파일 경로

2490}2492}

2491```2493```

2492 2494 

2498 2500 

2499```python theme={null}2501```python theme={null}

2500{2502{

2501 "pattern": str, # The glob pattern to match files against2503 "pattern": str, # 파일과 일치시킬 glob 패턴

2502 "path": str | None, # The directory to search in (defaults to cwd)2504 "path": str | None, # 검색할 디렉토리 (기본값은 cwd)

2503}2505}

2504```2506```

2505 2507 

2507 2509 

2508```python theme={null}2510```python theme={null}

2509{2511{

2510 "matches": list[str], # Array of matching file paths2512 "matches": list[str], # 일치하는 파일 경로 배열

2511 "count": int, # Number of matches found2513 "count": int, # 찾은 일치 수

2512 "search_path": str, # Search directory used2514 "search_path": str, # 사용된 검색 디렉토리

2513}2515}

2514```2516```

2515 2517 

2521 2523 

2522```python theme={null}2524```python theme={null}

2523{2525{

2524 "pattern": str, # The regular expression pattern2526 "pattern": str, # 정규 표현식 패턴

2525 "path": str | None, # File or directory to search in2527 "path": str | None, # 검색할 파일 또는 디렉토리

2526 "glob": str | None, # Glob pattern to filter files2528 "glob": str | None, # 파일을 필터링할 glob 패턴

2527 "type": str | None, # File type to search2529 "type": str | None, # 검색할 파일 타입

2528 "output_mode": str | None, # "content", "files_with_matches", or "count"2530 "output_mode": str | None, # "content", "files_with_matches" 또는 "count"

2529 "-i": bool | None, # Case insensitive search2531 "-i": bool | None, # 대소문자 구분 없는 검색

2530 "-n": bool | None, # Show line numbers2532 "-n": bool | None, # 줄 번호 표시

2531 "-B": int | None, # Lines to show before each match2533 "-B": int | None, # 각 일치 전에 표시할 줄

2532 "-A": int | None, # Lines to show after each match2534 "-A": int | None, # 각 일치 후에 표시할 줄

2533 "-C": int | None, # Lines to show before and after2535 "-C": int | None, # 전후에 표시할 줄

2534 "head_limit": int | None, # Limit output to first N lines/entries2536 "head_limit": int | None, # 출력을 처음 N개 줄/항목으로 제한

2535 "multiline": bool | None, # Enable multiline mode2537 "multiline": bool | None, # 다중 줄 모드 활성화

2536}2538}

2537```2539```

2538 2540 

2557 2559 

2558```python theme={null}2560```python theme={null}

2559{2561{

2560 "files": list[str], # Files containing matches2562 "files": list[str], # 일치를 포함하는 파일

2561 "count": int, # Number of files with matches2563 "count": int, # 일치를 포함하는 파일 수

2562}2564}

2563```2565```

2564 2566 

2570 2572 

2571```python theme={null}2573```python theme={null}

2572{2574{

2573 "notebook_path": str, # Absolute path to the Jupyter notebook2575 "notebook_path": str, # Jupyter 노트북의 절대 경로

2574 "cell_id": str | None, # The ID of the cell to edit2576 "cell_id": str | None, # 편집할 셀의 ID

2575 "new_source": str, # The new source for the cell2577 "new_source": str, # 셀의 새로운 소스

2576 "cell_type": "code" | "markdown" | None, # The type of the cell2578 "cell_type": "code" | "markdown" | None, # 셀의 타입

2577 "edit_mode": "replace" | "insert" | "delete" | None, # Edit operation type2579 "edit_mode": "replace" | "insert" | "delete" | None, # 편집 작업 타입

2578}2580}

2579```2581```

2580 2582 

2582 2584 

2583```python theme={null}2585```python theme={null}

2584{2586{

2585 "message": str, # Success message2587 "message": str, # 성공 메시지

2586 "edit_type": "replaced" | "inserted" | "deleted", # Type of edit performed2588 "edit_type": "replaced" | "inserted" | "deleted", # 수행된 편집 타입

2587 "cell_id": str | None, # Cell ID that was affected2589 "cell_id": str | None, # 영향을 받은 셀 ID

2588 "total_cells": int, # Total cells in notebook after edit2590 "total_cells": int, # 편집 후 노트북의 총 셀 수

2589}2591}

2590```2592```

2591 2593 

2597 2599 

2598```python theme={null}2600```python theme={null}

2599{2601{

2600 "url": str, # The URL to fetch content from2602 "url": str, # 콘텐츠를 가져올 URL

2601 "prompt": str, # The prompt to run on the fetched content2603 "prompt": str, # 가져온 콘텐츠에서 실행할 프롬프트

2602}2604}

2603```2605```

2604 2606 

2606 2608 

2607```python theme={null}2609```python theme={null}

2608{2610{

2609 "response": str, # AI model's response to the prompt2611 "response": str, # 프롬프트에 대한 AI 모델의 응답

2610 "url": str, # URL that was fetched2612 "url": str, # 가져온 URL

2611 "final_url": str | None, # Final URL after redirects2613 "final_url": str | None, # 리다이렉트 후 최종 URL

2612 "status_code": int | None, # HTTP status code2614 "status_code": int | None, # HTTP 상태 코드

2613}2615}

2614```2616```

2615 2617 

2621 2623 

2622```python theme={null}2624```python theme={null}

2623{2625{

2624 "query": str, # The search query to use2626 "query": str, # 사용할 검색 쿼리

2625 "allowed_domains": list[str] | None, # Only include results from these domains2627 "allowed_domains": list[str] | None, # 이 도메인의 결과만 포함

2626 "blocked_domains": list[str] | None, # Never include results from these domains2628 "blocked_domains": list[str] | None, # 이 도메인의 결과는 절대 포함하지 않음

2627}2629}

2628```2630```

2629 2631 

2647{2649{

2648 "todos": [2650 "todos": [

2649 {2651 {

2650 "content": str, # The task description2652 "content": str, # 작업 설명

2651 "status": "pending" | "in_progress" | "completed", # Task status2653 "status": "pending" | "in_progress" | "completed", # 작업 상태

2652 "activeForm": str, # Active form of the description2654 "activeForm": str, # 설명의 활성 형식

2653 }2655 }

2654 ]2656 ]

2655}2657}

2659 2661 

2660```python theme={null}2662```python theme={null}

2661{2663{

2662 "message": str, # Success message2664 "message": str, # 성공 메시지

2663 "stats": {"total": int, "pending": int, "in_progress": int, "completed": int},2665 "stats": {"total": int, "pending": int, "in_progress": int, "completed": int},

2664}2666}

2665```2667```

2672 2674 

2673```python theme={null}2675```python theme={null}

2674{2676{

2675 "bash_id": str, # The ID of the background shell2677 "bash_id": str, # 백그라운드 셸의 ID

2676 "filter": str | None, # Optional regex to filter output lines2678 "filter": str | None, # 출력 줄을 필터링할 선택적 정규식

2677}2679}

2678```2680```

2679 2681 

2681 2683 

2682```python theme={null}2684```python theme={null}

2683{2685{

2684 "output": str, # New output since last check2686 "output": str, # 마지막 확인 이후의 새로운 출력

2685 "status": "running" | "completed" | "failed", # Current shell status2687 "status": "running" | "completed" | "failed", # 현재 셸 상태

2686 "exitCode": int | None, # Exit code when completed2688 "exitCode": int | None, # 완료 시 종료 코드

2687}2689}

2688```2690```

2689 2691 

2695 2697 

2696```python theme={null}2698```python theme={null}

2697{2699{

2698 "shell_id": str # The ID of the background shell to kill2700 "shell_id": str # 종료할 백그라운드 셸의 ID

2699}2701}

2700```2702```

2701 2703 

2703 2705 

2704```python theme={null}2706```python theme={null}

2705{2707{

2706 "message": str, # Success message2708 "message": str, # 성공 메시지

2707 "shell_id": str, # ID of the killed shell2709 "shell_id": str, # 종료된 셸의 ID

2708}2710}

2709```2711```

2710 2712 

2716 2718 

2717```python theme={null}2719```python theme={null}

2718{2720{

2719 "plan": str # The plan to run by the user for approval2721 "plan": str # 사용자 승인을 위해 실행할 계획

2720}2722}

2721```2723```

2722 2724 

2724 2726 

2725```python theme={null}2727```python theme={null}

2726{2728{

2727 "message": str, # Confirmation message2729 "message": str, # 확인 메시지

2728 "approved": bool | None, # Whether user approved the plan2730 "approved": bool | None, # 사용자가 계획을 승인했는지 여부

2729}2731}

2730```2732```

2731 2733 

2737 2739 

2738```python theme={null}2740```python theme={null}

2739{2741{

2740 "server": str | None # Optional server name to filter resources by2742 "server": str | None # 리소스를 필터링할 선택적 서버 이름

2741}2743}

2742```2744```

2743 2745 

2766 2768 

2767```python theme={null}2769```python theme={null}

2768{2770{

2769 "server": str, # The MCP server name2771 "server": str, # MCP 서버 이름

2770 "uri": str, # The resource URI to read2772 "uri": str, # 읽을 리소스 URI

2771}2773}

2772```2774```

2773 2775 

308| `tag` | `string \| null` | 필수 | 태그 문자열 또는 지우려면 `null` |308| `tag` | `string \| null` | 필수 | 태그 문자열 또는 지우려면 `null` |

309| `options.dir` | `string` | `undefined` | 프로젝트 디렉토리 경로입니다. 생략하면 모든 프로젝트 디렉토리를 검색합니다 |309| `options.dir` | `string` | `undefined` | 프로젝트 디렉토리 경로입니다. 생략하면 모든 프로젝트 디렉토리를 검색합니다 |

310 310 

311### `resolveSettings()`

312 

313CLI와 동일한 병합 엔진을 사용하여 주어진 디렉토리에 대한 효과적인 Claude Code 설정을 해결하며, Claude CLI를 생성하지 않습니다. `query()` 호출을 호출하기 전에 어떤 구성을 볼 수 있는지 검사하는 데 사용합니다.

314 

315<Note>

316 이 함수는 알파 버전이며 안정화 전에 API가 변경될 수 있습니다. CLI 시작과의 패리티를 위해 macOS plist 및 Windows HKLM/HKCU를 포함한 MDM 소스를 읽지만, 관리자가 구성한 `policyHelper` 서브프로세스를 실행하지 않습니다. `permissions.defaultMode` 필드는 프로젝트 설정을 포함한 모든 계층에서 그대로 반환됩니다. CLI가 권한 상승 모드를 적용하기 전에 적용하는 신뢰 필터는 적용되지 않습니다.

317</Note>

318 

319```typescript theme={null}

320function resolveSettings(

321 options?: ResolveSettingsOptions

322): Promise<ResolvedSettings>;

323```

324 

325#### 매개변수

326 

327`resolveSettings()`는 단일 옵션 객체를 수락합니다. 모든 필드는 선택적입니다.

328 

329| 매개변수 | 타입 | 기본값 | 설명 |

330| :------------------------------ | :------------------------------------ | :-------------- | :----------------------------------------------------------------------------- |

331| `options.cwd` | `string` | `process.cwd()` | 프로젝트 및 로컬 설정을 상대적으로 해결할 디렉토리 |

332| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | 모든 소스 | 로드할 파일 시스템 소스입니다. 사용자, 프로젝트 및 로컬 설정을 건너뛰려면 `[]`를 전달합니다. 관리 정책 설정은 모든 경우에 로드됩니다 |

333| `options.managedSettings` | `Settings` | `undefined` | 관리 정책 우선순위 수준에서 병합된 제한적 정책 계층 설정입니다. `model`과 같은 제한적이지 않은 키는 자동으로 삭제됩니다 |

334| `options.serverManagedSettings` | `Settings` | `undefined` | `/api/claude_code/settings`의 서버 관리 설정 페이로드입니다. 제한적이지 않은 키는 필터링 없이 통과합니다 |

335 

336#### 반환 타입: `ResolvedSettings`

337 

338`resolveSettings()`는 병합된 설정과 각 키에 기여한 소스를 설명하는 객체를 반환합니다.

339 

340| 속성 | 타입 | 설명 |

341| :----------- | :-------------------------------------------------- | :----------------------------------------- |

342| `effective` | `Settings` | 모든 활성화된 소스를 우선순위 순서로 적용한 후 병합된 설정 |

343| `provenance` | `Partial<Record<keyof Settings, ProvenanceEntry>>` | `effective`의 각 최상위 키에 대해 값을 제공한 소스 |

344| `sources` | `Array<{ source, settings, path?, policyOrigin? }>` | 소스별 원본 설정, 가장 낮은 우선순위에서 가장 높은 우선순위 순서로 정렬됨 |

345 

346#### 예제

347 

348아래 예제는 프로젝트 디렉토리에 대한 설정을 해결하고 정리 기간을 제어하는 소스를 인쇄합니다.

349 

350```typescript theme={null}

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

352 

353const { effective, provenance } = await resolveSettings({

354 cwd: "/path/to/project",

355 settingSources: ["user", "project", "local"],

356});

357 

358console.log(`Cleanup period: ${effective.cleanupPeriodDays} days`);

359console.log(`Set by: ${provenance.cleanupPeriodDays?.source}`);

360```

361 

311## 타입362## 타입

312 363 

313### `Options`364### `Options`

864 | SDKFilesPersistedEvent915 | SDKFilesPersistedEvent

865 | SDKToolUseSummaryMessage916 | SDKToolUseSummaryMessage

866 | SDKRateLimitEvent917 | SDKRateLimitEvent

918 | SDKPermissionDeniedMessage

867 | SDKPromptSuggestionMessage;919 | SDKPromptSuggestionMessage;

868```920```

869 921 

1052};1104};

1053```1105```

1054 1106 

1107### `SDKPermissionDeniedMessage`

1108 

1109권한 시스템이 대화형 프롬프트 없이 도구 호출을 자동으로 거부할 때 내보내지는 스트림 이벤트입니다. 이를 사용하여 거부를 UI에 렌더링할 수 있으며, 뒤따르는 `is_error` 도구 결과만 관찰하는 것이 아닙니다. 대화형 요청 경로는 [`canUseTool`](#canusetool) 콜백을 통해 애플리케이션에 별도로 도달합니다. `PreToolUse` 훅에서 발급된 거부는 이 이벤트를 통해 보고되지 않습니다.

1110 

1111이 이벤트는 Claude Code v2.1.136 이상이 필요합니다.

1112 

1113```typescript theme={null}

1114type SDKPermissionDeniedMessage = {

1115 type: "system";

1116 subtype: "permission_denied";

1117 tool_name: string;

1118 tool_use_id: string;

1119 agent_id?: string;

1120 decision_reason_type?: string;

1121 decision_reason?: string;

1122 message: string;

1123 uuid: UUID;

1124 session_id: string;

1125};

1126```

1127 

1128| 필드 | 타입 | 설명 |

1129| ---------------------- | -------- | --------------------------------------------------------------------------------- |

1130| `tool_name` | `string` | 거부된 도구의 이름 |

1131| `tool_use_id` | `string` | 이 거부가 답하는 `tool_use` 블록의 ID |

1132| `agent_id` | `string` | 거부된 호출이 서브에이전트 내부에서 발생한 경우 서브에이전트 ID입니다. 호스트 측 라우팅을 위해 `can_use_tool`의 필드를 미러링합니다 |

1133| `decision_reason_type` | `string` | `"rule"`, `"mode"`, `"classifier"` 또는 `"asyncAgent"`와 같이 결정한 구성 요소의 판별자 |

1134| `decision_reason` | `string` | 사용 가능할 때 결정 구성 요소의 인간이 읽을 수 있는 이유 |

1135| `message` | `string` | `tool_result`에서 모델에 반환된 거부 메시지 |

1136 

1055### `SDKPermissionDenial`1137### `SDKPermissionDenial`

1056 1138 

1057거부된 도구 사용에 대한 정보입니다.1139거부된 도구 사용에 대한 정보입니다.

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# 승인 및 사용자 입력 처리

6 

7> Claude의 승인 요청 및 명확화 질문을 사용자에게 표시한 후 SDK에 사용자의 결정을 반환합니다.

8 

9작업을 진행하는 동안 Claude는 때때로 사용자와 확인해야 합니다. 파일을 삭제하기 전에 권한이 필요할 수도 있고, 새 프로젝트를 위해 어떤 데이터베이스를 사용할지 물어봐야 할 수도 있습니다. 애플리케이션은 이러한 요청을 사용자에게 표시하여 Claude가 사용자의 입력으로 계속 진행할 수 있도록 해야 합니다.

10 

11Claude는 두 가지 상황에서 사용자 입력을 요청합니다. **도구 사용 권한**이 필요할 때(파일 삭제 또는 명령 실행 등)와 **명확화 질문**이 있을 때(`AskUserQuestion` 도구를 통해)입니다. 둘 다 `canUseTool` 콜백을 트리거하며, 이는 응답을 반환할 때까지 실행을 일시 중지합니다. 이는 Claude가 완료되고 다음 메시지를 기다리는 일반적인 대화 턴과는 다릅니다.

12 

13명확화 질문의 경우 Claude가 질문과 옵션을 생성합니다. 사용자의 역할은 이를 사용자에게 제시하고 선택 사항을 반환하는 것입니다. 이 흐름에 자신의 질문을 추가할 수 없습니다. 사용자에게 직접 물어봐야 할 사항이 있으면 애플리케이션 로직에서 별도로 수행하십시오.

14 

15콜백은 무기한 대기 상태로 유지될 수 있습니다. 콜백이 반환될 때까지 실행이 일시 중지되며, SDK는 쿼리 자체가 취소될 때만 대기를 취소합니다. 사용자가 프로세스가 합리적으로 실행 상태를 유지할 수 있는 것보다 더 오래 응답하는 데 시간이 걸릴 수 있다면, TypeScript SDK는 [`defer` 훅 결정](/ko/hooks#defer-a-tool-call-for-later)을 지원하므로 프로세스를 종료하고 나중에 지속된 세션에서 재개할 수 있습니다. 이 옵션은 Python SDK에서는 사용할 수 없습니다.

16 

17이 가이드는 각 유형의 요청을 감지하고 적절하게 응답하는 방법을 보여줍니다.

18 

19## Claude가 입력이 필요한 시점 감지

20 

21쿼리 옵션에 `canUseTool` 콜백을 전달합니다. 콜백은 Claude가 사용자 입력이 필요할 때마다 실행되며, 도구 이름과 입력을 인수로 받습니다.

22 

23<CodeGroup>

24 ```python Python theme={null}

25 async def handle_tool_request(tool_name, input_data, context):

26 # 사용자에게 프롬프트하고 허용 또는 거부 반환

27 ...

28 

29 

30 options = ClaudeAgentOptions(can_use_tool=handle_tool_request)

31 ```

32 

33 ```typescript TypeScript theme={null}

34 async function handleToolRequest(toolName, input, options) {

35 // options includes { signal: AbortSignal, suggestions?: PermissionUpdate[] }

36 // 사용자에게 프롬프트하고 허용 또는 거부 반환

37 }

38 

39 const options = { canUseTool: handleToolRequest };

40 ```

41</CodeGroup>

42 

43콜백은 두 가지 경우에 실행됩니다.

44 

451. **도구가 승인 필요**: Claude가 [권한 규칙](/ko/agent-sdk/permissions) 또는 모드에 의해 자동 승인되지 않은 도구를 사용하려고 합니다. 도구에 대해 `tool_name`을 확인합니다(예: `"Bash"`, `"Write"`).

462. **Claude가 질문함**: Claude가 `AskUserQuestion` 도구를 호출합니다. `tool_name == "AskUserQuestion"`을 확인하여 다르게 처리합니다. `tools` 배열을 지정하는 경우 이것이 작동하려면 `AskUserQuestion`을 포함하십시오. 자세한 내용은 [명확화 질문 처리](#명확화-질문-처리)를 참조하십시오.

47 

48<Note>

49 사용자에게 프롬프트하지 않고 도구를 자동으로 허용하거나 거부하려면 [훅](/ko/agent-sdk/hooks)을 대신 사용하십시오. 훅은 `canUseTool` 전에 실행되며 자신의 로직에 따라 요청을 허용, 거부 또는 수정할 수 있습니다. [`PermissionRequest` 훅](/ko/agent-sdk/hooks#available-hooks)을 사용하여 Claude가 승인을 기다리고 있을 때 외부 알림(Slack, 이메일, 푸시)을 보낼 수도 있습니다.

50</Note>

51 

52## 도구 승인 요청 처리

53 

54쿼리 옵션에 `canUseTool` 콜백을 전달하면, Claude가 자동 승인되지 않은 도구를 사용하려고 할 때 실행됩니다. 콜백은 세 가지 인수를 받습니다.

55 

56| 인수 | 설명 |

57| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

58| `toolName` | Claude가 사용하려는 도구의 이름(예: `"Bash"`, `"Write"`, `"Edit"`) |

59| `input` | Claude가 도구에 전달하는 매개변수입니다. 내용은 도구에 따라 다릅니다. |

60| `options` (TS) / `context` (Python) | 선택적 `suggestions`(재프롬프트를 피하기 위한 제안된 `PermissionUpdate` 항목)과 취소 신호를 포함한 추가 컨텍스트입니다. TypeScript에서 `signal`은 `AbortSignal`입니다. Python에서 신호 필드는 향후 사용을 위해 예약되어 있습니다. Python의 경우 [`ToolPermissionContext`](/ko/agent-sdk/python#toolpermissioncontext)를 참조하십시오. |

61 

62`input` 객체에는 도구별 매개변수가 포함됩니다. 일반적인 예:

63 

64| 도구 | 입력 필드 |

65| ------- | --------------------------------------- |

66| `Bash` | `command`, `description`, `timeout` |

67| `Write` | `file_path`, `content` |

68| `Edit` | `file_path`, `old_string`, `new_string` |

69| `Read` | `file_path`, `offset`, `limit` |

70 

71완전한 입력 스키마는 SDK 참조를 참조하십시오. [Python](/ko/agent-sdk/python#tool-input%2Foutput-types) | [TypeScript](/ko/agent-sdk/typescript#tool-input-types).

72 

73이 정보를 사용자에게 표시하여 작업을 허용할지 거부할지 결정한 후 적절한 응답을 반환할 수 있습니다.

74 

75다음 예제는 Claude에게 테스트 파일을 생성하고 삭제하도록 요청합니다. Claude가 각 작업을 시도할 때 콜백은 도구 요청을 터미널에 인쇄하고 y/n 승인을 요청합니다.

76 

77<CodeGroup>

78 ```python Python theme={null}

79 import asyncio

80 

81 from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query

82 from claude_agent_sdk.types import (

83 HookMatcher,

84 PermissionResultAllow,

85 PermissionResultDeny,

86 ToolPermissionContext,

87 )

88 

89 

90 async def can_use_tool(

91 tool_name: str, input_data: dict, context: ToolPermissionContext

92 ) -> PermissionResultAllow | PermissionResultDeny:

93 # 도구 요청 표시

94 print(f"\nTool: {tool_name}")

95 if tool_name == "Bash":

96 print(f"Command: {input_data.get('command')}")

97 if input_data.get("description"):

98 print(f"Description: {input_data.get('description')}")

99 else:

100 print(f"Input: {input_data}")

101 

102 # 사용자 승인 받기

103 response = input("Allow this action? (y/n): ")

104 

105 # 사용자의 응답에 따라 허용 또는 거부 반환

106 if response.lower() == "y":

107 # 허용: 도구가 원본(또는 수정된) 입력으로 실행됨

108 return PermissionResultAllow(updated_input=input_data)

109 else:

110 # 거부: 도구가 실행되지 않음, Claude가 메시지를 봄

111 return PermissionResultDeny(message="User denied this action")

112 

113 

114 # 필수 해결 방법: 더미 훅이 can_use_tool을 위해 스트림을 열어 둠

115 async def dummy_hook(input_data, tool_use_id, context):

116 return {"continue_": True}

117 

118 

119 async def prompt_stream():

120 yield {

121 "type": "user",

122 "message": {

123 "role": "user",

124 "content": "Create a test file in /tmp and then delete it",

125 },

126 }

127 

128 

129 async def main():

130 async for message in query(

131 prompt=prompt_stream(),

132 options=ClaudeAgentOptions(

133 can_use_tool=can_use_tool,

134 hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]},

135 ),

136 ):

137 if isinstance(message, ResultMessage) and message.subtype == "success":

138 print(message.result)

139 

140 

141 asyncio.run(main())

142 ```

143 

144 ```typescript TypeScript theme={null}

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

146 import * as readline from "readline";

147 

148 // 터미널에서 사용자 입력을 프롬프트하는 헬퍼

149 function prompt(question: string): Promise<string> {

150 const rl = readline.createInterface({

151 input: process.stdin,

152 output: process.stdout

153 });

154 return new Promise((resolve) =>

155 rl.question(question, (answer) => {

156 rl.close();

157 resolve(answer);

158 })

159 );

160 }

161 

162 for await (const message of query({

163 prompt: "Create a test file in /tmp and then delete it",

164 options: {

165 canUseTool: async (toolName, input) => {

166 // 도구 요청 표시

167 console.log(`\nTool: ${toolName}`);

168 if (toolName === "Bash") {

169 console.log(`Command: ${input.command}`);

170 if (input.description) console.log(`Description: ${input.description}`);

171 } else {

172 console.log(`Input: ${JSON.stringify(input, null, 2)}`);

173 }

174 

175 // 사용자 승인 받기

176 const response = await prompt("Allow this action? (y/n): ");

177 

178 // 사용자의 응답에 따라 허용 또는 거부 반환

179 if (response.toLowerCase() === "y") {

180 // 허용: 도구가 원본(또는 수정된) 입력으로 실행됨

181 return { behavior: "allow", updatedInput: input };

182 } else {

183 // 거부: 도구가 실행되지 않음, Claude가 메시지를 봄

184 return { behavior: "deny", message: "User denied this action" };

185 }

186 }

187 }

188 })) {

189 if ("result" in message) console.log(message.result);

190 }

191 ```

192</CodeGroup>

193 

194<Note>

195 Python에서 `can_use_tool`은 [스트리밍 모드](/ko/agent-sdk/streaming-vs-single-mode)와 스트림을 열어 두기 위해 `{"continue_": True}`를 반환하는 `PreToolUse` 훅이 필요합니다. 이 훅이 없으면 권한 콜백이 호출되기 전에 스트림이 닫힙니다.

196</Note>

197 

198이 예제는 `y` 이외의 모든 입력이 거부로 처리되는 y/n 흐름을 사용합니다. 실제로는 사용자가 요청을 수정하거나, 피드백을 제공하거나, Claude를 완전히 리디렉션할 수 있는 더 풍부한 UI를 구축할 수 있습니다. 응답할 수 있는 모든 방법은 [도구 요청에 응답](#도구-요청에-응답)을 참조하십시오.

199 

200### 도구 요청에 응답

201 

202콜백은 두 가지 응답 유형 중 하나를 반환합니다.

203 

204| 응답 | Python | TypeScript |

205| ------ | ------------------------------------------ | ------------------------------------- |

206| **허용** | `PermissionResultAllow(updated_input=...)` | `{ behavior: "allow", updatedInput }` |

207| **거부** | `PermissionResultDeny(message=...)` | `{ behavior: "deny", message }` |

208 

209허용할 때 도구 입력(원본 또는 수정됨)을 전달합니다. 거부할 때 이유를 설명하는 메시지를 제공합니다. Claude는 이 메시지를 보고 접근 방식을 조정할 수 있습니다.

210 

211<CodeGroup>

212 ```python Python theme={null}

213 from claude_agent_sdk.types import PermissionResultAllow, PermissionResultDeny

214 

215 # 도구가 실행되도록 허용

216 return PermissionResultAllow(updated_input=input_data)

217 

218 # 도구 차단

219 return PermissionResultDeny(message="User rejected this action")

220 ```

221 

222 ```typescript TypeScript theme={null}

223 // 도구가 실행되도록 허용

224 return { behavior: "allow", updatedInput: input };

225 

226 // 도구 차단

227 return { behavior: "deny", message: "User rejected this action" };

228 ```

229</CodeGroup>

230 

231허용하거나 거부하는 것 외에도 도구의 입력을 수정하거나 Claude가 접근 방식을 조정하는 데 도움이 되는 컨텍스트를 제공할 수 있습니다.

232 

233* **승인**: 도구가 Claude가 요청한 대로 실행되도록 허용

234* **변경 사항과 함께 승인**: 실행 전에 입력 수정(예: 경로 정제, 제약 조건 추가)

235* **거부**: 도구를 차단하고 이유를 Claude에 알림

236* **대안 제안**: 차단하지만 사용자가 원하는 것으로 Claude를 안내

237* **완전히 리디렉션**: [스트리밍 입력](/ko/agent-sdk/streaming-vs-single-mode)을 사용하여 Claude에 완전히 새로운 지시를 보냄

238 

239<Tabs>

240 <Tab title="승인">

241 사용자가 작업을 그대로 승인합니다. 콜백에서 `input`을 변경하지 않고 전달하면 도구가 Claude가 요청한 대로 정확히 실행됩니다.

242 

243 <CodeGroup>

244 ```python Python theme={null}

245 async def can_use_tool(tool_name, input_data, context):

246 print(f"Claude wants to use {tool_name}")

247 approved = await ask_user("Allow this action?")

248 

249 if approved:

250 return PermissionResultAllow(updated_input=input_data)

251 return PermissionResultDeny(message="User declined")

252 ```

253 

254 ```typescript TypeScript theme={null}

255 canUseTool: async (toolName, input) => {

256 console.log(`Claude wants to use ${toolName}`);

257 const approved = await askUser("Allow this action?");

258 

259 if (approved) {

260 return { behavior: "allow", updatedInput: input };

261 }

262 return { behavior: "deny", message: "User declined" };

263 };

264 ```

265 </CodeGroup>

266 </Tab>

267 

268 <Tab title="변경 사항과 함께 승인">

269 사용자가 승인하지만 먼저 요청을 수정하려고 합니다. 도구가 실행되기 전에 입력을 변경할 수 있습니다. Claude는 결과를 보지만 변경 사항을 알려주지 않습니다. 매개변수 정제, 제약 조건 추가 또는 액세스 범위 지정에 유용합니다.

270 

271 <CodeGroup>

272 ```python Python theme={null}

273 async def can_use_tool(tool_name, input_data, context):

274 if tool_name == "Bash":

275 # 사용자가 승인했지만 모든 명령을 샌드박스로 범위 지정

276 sandboxed_input = {**input_data}

277 sandboxed_input["command"] = input_data["command"].replace(

278 "/tmp", "/tmp/sandbox"

279 )

280 return PermissionResultAllow(updated_input=sandboxed_input)

281 return PermissionResultAllow(updated_input=input_data)

282 ```

283 

284 ```typescript TypeScript theme={null}

285 canUseTool: async (toolName, input) => {

286 if (toolName === "Bash") {

287 // 사용자가 승인했지만 모든 명령을 샌드박스로 범위 지정

288 const sandboxedInput = {

289 ...input,

290 command: input.command.replace("/tmp", "/tmp/sandbox")

291 };

292 return { behavior: "allow", updatedInput: sandboxedInput };

293 }

294 return { behavior: "allow", updatedInput: input };

295 };

296 ```

297 </CodeGroup>

298 </Tab>

299 

300 <Tab title="거부">

301 사용자가 이 작업이 발생하기를 원하지 않습니다. 도구를 차단하고 이유를 설명하는 메시지를 제공합니다. Claude는 이 메시지를 보고 다른 접근 방식을 시도할 수 있습니다.

302 

303 <CodeGroup>

304 ```python Python theme={null}

305 async def can_use_tool(tool_name, input_data, context):

306 approved = await ask_user(f"Allow {tool_name}?")

307 

308 if not approved:

309 return PermissionResultDeny(message="User rejected this action")

310 return PermissionResultAllow(updated_input=input_data)

311 ```

312 

313 ```typescript TypeScript theme={null}

314 canUseTool: async (toolName, input) => {

315 const approved = await askUser(`Allow ${toolName}?`);

316 

317 if (!approved) {

318 return {

319 behavior: "deny",

320 message: "User rejected this action"

321 };

322 }

323 return { behavior: "allow", updatedInput: input };

324 };

325 ```

326 </CodeGroup>

327 </Tab>

328 

329 <Tab title="대안 제안">

330 사용자가 이 특정 작업을 원하지 않지만 다른 아이디어가 있습니다. 도구를 차단하고 메시지에 지침을 포함합니다. Claude는 이를 읽고 피드백에 따라 진행 방법을 결정합니다.

331 

332 <CodeGroup>

333 ```python Python theme={null}

334 async def can_use_tool(tool_name, input_data, context):

335 if tool_name == "Bash" and "rm" in input_data.get("command", ""):

336 # 사용자가 삭제를 원하지 않음, 대신 보관을 제안

337 return PermissionResultDeny(

338 message="User doesn't want to delete files. They asked if you could compress them into an archive instead."

339 )

340 return PermissionResultAllow(updated_input=input_data)

341 ```

342 

343 ```typescript TypeScript theme={null}

344 canUseTool: async (toolName, input) => {

345 if (toolName === "Bash" && input.command.includes("rm")) {

346 // 사용자가 삭제를 원하지 않음, 대신 보관을 제안

347 return {

348 behavior: "deny",

349 message:

350 "User doesn't want to delete files. They asked if you could compress them into an archive instead."

351 };

352 }

353 return { behavior: "allow", updatedInput: input };

354 };

355 ```

356 </CodeGroup>

357 </Tab>

358 

359 <Tab title="완전히 리디렉션">

360 방향의 완전한 변경(단순한 밀어붙이기가 아닌)의 경우 [스트리밍 입력](/ko/agent-sdk/streaming-vs-single-mode)을 사용하여 Claude에 새로운 지시를 직접 보냅니다. 이는 현재 도구 요청을 우회하고 Claude에 완전히 새로운 지시를 따르도록 합니다.

361 </Tab>

362</Tabs>

363 

364## 명확화 질문 처리

365 

366Claude가 여러 유효한 접근 방식이 있는 작업에 대해 더 많은 방향이 필요할 때 `AskUserQuestion` 도구를 호출합니다. 이는 `toolName`이 `AskUserQuestion`으로 설정된 `canUseTool` 콜백을 트리거합니다. 입력에는 Claude의 질문이 객관식 옵션으로 포함되어 있으며, 이를 사용자에게 표시하고 선택 사항을 반환합니다.

367 

368<Tip>

369 명확화 질문은 특히 [`plan` 모드](/ko/agent-sdk/permissions#plan-mode-plan)에서 흔하며, Claude가 코드베이스를 탐색하고 계획을 제안하기 전에 질문합니다. 이는 계획 모드를 Claude가 변경하기 전에 요구 사항을 수집하기를 원하는 대화형 워크플로우에 이상적으로 만듭니다.

370</Tip>

371 

372다음 단계는 명확화 질문을 처리하는 방법을 보여줍니다.

373 

374<Steps>

375 <Step title="canUseTool 콜백 전달">

376 쿼리 옵션에 `canUseTool` 콜백을 전달합니다. 기본적으로 `AskUserQuestion`을 사용할 수 있습니다. Claude의 기능을 제한하기 위해 `tools` 배열을 지정하는 경우(예: `Read`, `Glob` 및 `Grep`만 있는 읽기 전용 에이전트), 그 배열에 `AskUserQuestion`을 포함하십시오. 그렇지 않으면 Claude가 명확화 질문을 할 수 없습니다.

377 

378 <CodeGroup>

379 ```python Python theme={null}

380 async for message in query(

381 prompt="Analyze this codebase",

382 options=ClaudeAgentOptions(

383 # 도구 목록에 AskUserQuestion 포함

384 tools=["Read", "Glob", "Grep", "AskUserQuestion"],

385 can_use_tool=can_use_tool,

386 ),

387 ):

388 print(message)

389 ```

390 

391 ```typescript TypeScript theme={null}

392 for await (const message of query({

393 prompt: "Analyze this codebase",

394 options: {

395 // 도구 목록에 AskUserQuestion 포함

396 tools: ["Read", "Glob", "Grep", "AskUserQuestion"],

397 canUseTool: async (toolName, input) => {

398 // 명확화 질문을 여기서 처리

399 }

400 }

401 })) {

402 console.log(message);

403 }

404 ```

405 </CodeGroup>

406 </Step>

407 

408 <Step title="AskUserQuestion 감지">

409 콜백에서 `toolName`이 `AskUserQuestion`과 같은지 확인하여 다른 도구와 다르게 처리합니다.

410 

411 <CodeGroup>

412 ```python Python theme={null}

413 async def can_use_tool(tool_name: str, input_data: dict, context):

414 if tool_name == "AskUserQuestion":

415 # 사용자로부터 답변을 수집하는 구현

416 return await handle_clarifying_questions(input_data)

417 # 다른 도구를 정상적으로 처리

418 return await prompt_for_approval(tool_name, input_data)

419 ```

420 

421 ```typescript TypeScript theme={null}

422 canUseTool: async (toolName, input) => {

423 if (toolName === "AskUserQuestion") {

424 // 사용자로부터 답변을 수집하는 구현

425 return handleClarifyingQuestions(input);

426 }

427 // 다른 도구를 정상적으로 처리

428 return promptForApproval(toolName, input);

429 };

430 ```

431 </CodeGroup>

432 </Step>

433 

434 <Step title="질문 입력 구문 분석">

435 입력에는 `questions` 배열의 Claude 질문이 포함됩니다. 각 질문에는 `question`(표시할 텍스트), `options`(선택 사항) 및 `multiSelect`(여러 선택이 허용되는지 여부)가 있습니다.

436 

437 ```json theme={null}

438 {

439 "questions": [

440 {

441 "question": "How should I format the output?",

442 "header": "Format",

443 "options": [

444 { "label": "Summary", "description": "Brief overview" },

445 { "label": "Detailed", "description": "Full explanation" }

446 ],

447 "multiSelect": false

448 },

449 {

450 "question": "Which sections should I include?",

451 "header": "Sections",

452 "options": [

453 { "label": "Introduction", "description": "Opening context" },

454 { "label": "Conclusion", "description": "Final summary" }

455 ],

456 "multiSelect": true

457 }

458 ]

459 }

460 ```

461 

462 전체 필드 설명은 [질문 형식](#질문-형식)을 참조하십시오.

463 </Step>

464 

465 <Step title="사용자로부터 답변 수집">

466 사용자에게 질문을 제시하고 선택 사항을 수집합니다. 이를 수행하는 방법은 애플리케이션에 따라 다릅니다. 터미널 프롬프트, 웹 양식, 모바일 대화 상자 등입니다.

467 </Step>

468 

469 <Step title="Claude에 답변 반환">

470 `answers` 객체를 레코드로 구성합니다. 여기서 각 키는 `question` 텍스트이고 각 값은 선택된 옵션의 `label`입니다.

471 

472 | 질문 객체에서 | 다음으로 사용 |

473 | ----------------------------------------------------- | ------- |

474 | `question` 필드(예: `"How should I format the output?"`) | 키 |

475 | 선택된 옵션의 `label` 필드(예: `"Summary"`) | 값 |

476 

477 다중 선택 질문의 경우 레이블 배열을 전달하거나 `", "`로 조인합니다. [자유 텍스트 입력을 지원](#자유-텍스트-입력-지원)하는 경우 사용자의 사용자 정의 텍스트를 값으로 사용합니다.

478 

479 <CodeGroup>

480 ```python Python theme={null}

481 return PermissionResultAllow(

482 updated_input={

483 "questions": input_data.get("questions", []),

484 "answers": {

485 "How should I format the output?": "Summary",

486 "Which sections should I include?": ["Introduction", "Conclusion"],

487 },

488 }

489 )

490 ```

491 

492 ```typescript TypeScript theme={null}

493 return {

494 behavior: "allow",

495 updatedInput: {

496 questions: input.questions,

497 answers: {

498 "How should I format the output?": "Summary",

499 "Which sections should I include?": "Introduction, Conclusion"

500 }

501 }

502 };

503 ```

504 </CodeGroup>

505 </Step>

506</Steps>

507 

508### 질문 형식

509 

510입력에는 `questions` 배열의 Claude 생성 질문이 포함됩니다. 각 질문에는 다음 필드가 있습니다.

511 

512| 필드 | 설명 |

513| ------------- | -------------------------------------------------------------------------------------------------------------------- |

514| `question` | 표시할 전체 질문 텍스트 |

515| `header` | 질문의 짧은 레이블(최대 12자) |

516| `options` | 각각 `label` 및 `description`이 있는 2-4개 선택 사항의 배열입니다. TypeScript: 선택적으로 `preview`([아래](#option-previews-type-script) 참조) |

517| `multiSelect` | `true`인 경우 사용자가 여러 옵션을 선택할 수 있습니다. |

518 

519콜백이 받는 구조:

520 

521```json theme={null}

522{

523 "questions": [

524 {

525 "question": "How should I format the output?",

526 "header": "Format",

527 "options": [

528 { "label": "Summary", "description": "Brief overview of key points" },

529 { "label": "Detailed", "description": "Full explanation with examples" }

530 ],

531 "multiSelect": false

532 }

533 ]

534}

535```

536 

537#### 옵션 미리보기(TypeScript)

538 

539`toolConfig.askUserQuestion.previewFormat`은 각 옵션에 `preview` 필드를 추가하므로 앱이 레이블 옆에 시각적 목업을 표시할 수 있습니다. 이 설정이 없으면 Claude는 미리보기를 생성하지 않으며 필드가 없습니다.

540 

541| `previewFormat` | `preview` 포함 |

542| :-------------- | :--------------------------------------------------------------------------------- |

543| 설정되지 않음(기본값) | 필드가 없습니다. Claude는 미리보기를 생성하지 않습니다. |

544| `"markdown"` | ASCII 아트 및 펜스 코드 블록 |

545| `"html"` | 스타일이 지정된 `<div>` 조각(SDK는 콜백이 실행되기 전에 `<script>`, `<style>` 및 `<!DOCTYPE>`을 거부합니다.) |

546 

547형식은 세션의 모든 질문에 적용됩니다. Claude는 시각적 비교가 도움이 되는 옵션(레이아웃 선택, 색 구성표)에 `preview`를 포함하고 도움이 되지 않는 옵션(예/아니오 확인, 텍스트 전용 선택)에서 생략합니다. 렌더링하기 전에 `undefined`를 확인하십시오.

548 

549```typescript theme={null}

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

551 

552for await (const message of query({

553 prompt: "Help me choose a card layout",

554 options: {

555 toolConfig: {

556 askUserQuestion: { previewFormat: "html" }

557 },

558 canUseTool: async (toolName, input) => {

559 // input.questions[].options[].preview는 HTML 문자열 또는 undefined입니다.

560 return { behavior: "allow", updatedInput: input };

561 }

562 }

563})) {

564 // ...

565}

566```

567 

568HTML 미리보기가 있는 옵션:

569 

570```json theme={null}

571{

572 "label": "Compact",

573 "description": "Title and metric value only",

574 "preview": "<div style=\"padding:12px;border:1px solid #ddd;border-radius:8px\"><div style=\"font-size:12px;color:#666\">Active users</div><div style=\"font-size:28px;font-weight:600\">1,284</div></div>"

575}

576```

577 

578### 응답 형식

579 

580각 질문의 `question` 필드를 선택된 옵션의 `label`에 매핑하는 `answers` 객체를 반환합니다.

581 

582| 필드 | 설명 |

583| ----------- | ------------------------------ |

584| `questions` | 원본 질문 배열을 전달합니다(도구 처리에 필수). |

585| `answers` | 키가 질문 텍스트이고 값이 선택된 레이블인 객체입니다. |

586 

587다중 선택 질문의 경우 레이블 배열을 전달하거나 `", "`로 조인합니다. 자유 텍스트 입력의 경우 사용자의 사용자 정의 텍스트를 직접 사용합니다.

588 

589```json theme={null}

590{

591 "questions": [

592 // ...

593 ],

594 "answers": {

595 "How should I format the output?": "Summary",

596 "Which sections should I include?": ["Introduction", "Conclusion"]

597 }

598}

599```

600 

601#### 자유 텍스트 입력 지원

602 

603Claude의 사전 정의된 옵션이 항상 사용자가 원하는 것을 다루지는 않습니다. 사용자가 자신의 답변을 입력하도록 허용하려면:

604 

605* Claude의 옵션 후에 추가 "Other" 선택을 표시하여 텍스트 입력을 허용합니다.

606* 사용자의 사용자 정의 텍스트를 답변 값으로 사용합니다("Other"라는 단어가 아님).

607 

608전체 구현은 아래의 [완전한 예제](#완전한-예제)를 참조하십시오.

609 

610### 완전한 예제

611 

612Claude는 진행하기 위해 사용자 입력이 필요할 때 명확화 질문을 합니다. 예를 들어 모바일 앱의 기술 스택을 결정하는 데 도움을 달라는 요청을 받으면 Claude는 크로스 플랫폼 대 네이티브, 백엔드 선호도 또는 대상 플랫폼에 대해 물어볼 수 있습니다. 이러한 질문은 Claude가 추측하기보다는 사용자의 선호도와 일치하는 결정을 내리는 데 도움이 됩니다.

613 

614이 예제는 터미널 애플리케이션에서 이러한 질문을 처리합니다. 각 단계에서 발생하는 일은 다음과 같습니다.

615 

6161. **요청 라우팅**: `canUseTool` 콜백은 도구 이름이 `"AskUserQuestion"`인지 확인하고 전용 핸들러로 라우팅합니다.

6172. **질문 표시**: 핸들러는 `questions` 배열을 반복하고 각 질문을 번호가 매겨진 옵션과 함께 인쇄합니다.

6183. **입력 수집**: 사용자는 숫자를 입력하여 옵션을 선택하거나 자유 텍스트를 직접 입력할 수 있습니다(예: "jquery", "i don't know").

6194. **답변 매핑**: 코드는 입력이 숫자(옵션의 레이블 사용)인지 자유 텍스트(텍스트 직접 사용)인지 확인합니다.

6205. **Claude에 반환**: 응답에는 원본 `questions` 배열과 `answers` 매핑이 모두 포함됩니다.

621 

622<CodeGroup>

623 ```python Python theme={null}

624 import asyncio

625 

626 from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query

627 from claude_agent_sdk.types import HookMatcher, PermissionResultAllow

628 

629 

630 def parse_response(response: str, options: list) -> str:

631 """사용자 입력을 옵션 번호 또는 자유 텍스트로 구문 분석합니다."""

632 try:

633 indices = [int(s.strip()) - 1 for s in response.split(",")]

634 labels = [options[i]["label"] for i in indices if 0 <= i < len(options)]

635 return ", ".join(labels) if labels else response

636 except ValueError:

637 return response

638 

639 

640 async def handle_ask_user_question(input_data: dict) -> PermissionResultAllow:

641 """Claude의 질문을 표시하고 사용자 답변을 수집합니다."""

642 answers = {}

643 

644 for q in input_data.get("questions", []):

645 print(f"\n{q['header']}: {q['question']}")

646 

647 options = q["options"]

648 for i, opt in enumerate(options):

649 print(f" {i + 1}. {opt['label']} - {opt['description']}")

650 if q.get("multiSelect"):

651 print(" (Enter numbers separated by commas, or type your own answer)")

652 else:

653 print(" (Enter a number, or type your own answer)")

654 

655 response = input("Your choice: ").strip()

656 answers[q["question"]] = parse_response(response, options)

657 

658 return PermissionResultAllow(

659 updated_input={

660 "questions": input_data.get("questions", []),

661 "answers": answers,

662 }

663 )

664 

665 

666 async def can_use_tool(

667 tool_name: str, input_data: dict, context

668 ) -> PermissionResultAllow:

669 # AskUserQuestion을 질문 핸들러로 라우팅

670 if tool_name == "AskUserQuestion":

671 return await handle_ask_user_question(input_data)

672 # 이 예제에서는 다른 도구를 자동 승인

673 return PermissionResultAllow(updated_input=input_data)

674 

675 

676 async def prompt_stream():

677 yield {

678 "type": "user",

679 "message": {

680 "role": "user",

681 "content": "Help me decide on the tech stack for a new mobile app",

682 },

683 }

684 

685 

686 # 필수 해결 방법: 더미 훅이 can_use_tool을 위해 스트림을 열어 둠

687 async def dummy_hook(input_data, tool_use_id, context):

688 return {"continue_": True}

689 

690 

691 async def main():

692 async for message in query(

693 prompt=prompt_stream(),

694 options=ClaudeAgentOptions(

695 can_use_tool=can_use_tool,

696 hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]},

697 ),

698 ):

699 if isinstance(message, ResultMessage) and message.subtype == "success":

700 print(message.result)

701 

702 

703 asyncio.run(main())

704 ```

705 

706 ```typescript TypeScript theme={null}

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

708 import * as readline from "readline/promises";

709 

710 // 터미널에서 사용자 입력을 프롬프트하는 헬퍼

711 async function prompt(question: string): Promise<string> {

712 const rl = readline.createInterface({ input: process.stdin, output: process.stdout });

713 const answer = await rl.question(question);

714 rl.close();

715 return answer;

716 }

717 

718 // 사용자 입력을 옵션 번호 또는 자유 텍스트로 구문 분석

719 function parseResponse(response: string, options: any[]): string {

720 const indices = response.split(",").map((s) => parseInt(s.trim()) - 1);

721 const labels = indices

722 .filter((i) => !isNaN(i) && i >= 0 && i < options.length)

723 .map((i) => options[i].label);

724 return labels.length > 0 ? labels.join(", ") : response;

725 }

726 

727 // Claude의 질문을 표시하고 사용자 답변을 수집

728 async function handleAskUserQuestion(input: any) {

729 const answers: Record<string, string> = {};

730 

731 for (const q of input.questions) {

732 console.log(`\n${q.header}: ${q.question}`);

733 

734 const options = q.options;

735 options.forEach((opt: any, i: number) => {

736 console.log(` ${i + 1}. ${opt.label} - ${opt.description}`);

737 });

738 if (q.multiSelect) {

739 console.log(" (Enter numbers separated by commas, or type your own answer)");

740 } else {

741 console.log(" (Enter a number, or type your own answer)");

742 }

743 

744 const response = (await prompt("Your choice: ")).trim();

745 answers[q.question] = parseResponse(response, options);

746 }

747 

748 // Claude에 답변 반환(원본 질문 배열 포함 필수)

749 return {

750 behavior: "allow",

751 updatedInput: { questions: input.questions, answers }

752 };

753 }

754 

755 async function main() {

756 for await (const message of query({

757 prompt: "Help me decide on the tech stack for a new mobile app",

758 options: {

759 canUseTool: async (toolName, input) => {

760 // AskUserQuestion을 질문 핸들러로 라우팅

761 if (toolName === "AskUserQuestion") {

762 return handleAskUserQuestion(input);

763 }

764 // 이 예제에서는 다른 도구를 자동 승인

765 return { behavior: "allow", updatedInput: input };

766 }

767 }

768 })) {

769 if ("result" in message) console.log(message.result);

770 }

771 }

772 

773 main();

774 ```

775</CodeGroup>

776 

777## 제한 사항

778 

779* **서브에이전트**: `AskUserQuestion`은 현재 Agent 도구를 통해 생성된 서브에이전트에서 사용할 수 없습니다.

780* **질문 제한**: 각 `AskUserQuestion` 호출은 각각 2-4개 옵션이 있는 1-4개 질문을 지원합니다.

781 

782## 사용자 입력을 얻는 다른 방법

783 

784`canUseTool` 콜백과 `AskUserQuestion` 도구는 대부분의 승인 및 명확화 시나리오를 다루지만, SDK는 사용자로부터 입력을 얻는 다른 방법을 제공합니다.

785 

786### 스트리밍 입력

787 

788다음이 필요할 때 [스트리밍 입력](/ko/agent-sdk/streaming-vs-single-mode)을 사용하십시오.

789 

790* **에이전트 중간에 중단**: Claude가 작업 중일 때 취소 신호를 보내거나 방향을 변경합니다.

791* **추가 컨텍스트 제공**: Claude가 물어볼 때까지 기다리지 않고 필요한 정보를 추가합니다.

792* **채팅 인터페이스 구축**: 장시간 실행되는 작업 중에 사용자가 후속 메시지를 보낼 수 있습니다.

793 

794스트리밍 입력은 사용자가 승인 체크포인트에서만이 아니라 실행 전체에서 에이전트와 상호 작용하는 대화형 UI에 이상적입니다.

795 

796### 사용자 정의 도구

797 

798다음이 필요할 때 [사용자 정의 도구](/ko/agent-sdk/custom-tools)를 사용하십시오.

799 

800* **구조화된 입력 수집**: `AskUserQuestion`의 객관식 형식을 넘어서는 양식, 마법사 또는 다단계 워크플로우를 구축합니다.

801* **외부 승인 시스템 통합**: 기존 티켓팅, 워크플로우 또는 승인 플랫폼에 연결합니다.

802* **도메인별 상호 작용 구현**: 코드 검토 인터페이스 또는 배포 체크리스트와 같이 애플리케이션의 필요에 맞는 도구를 만듭니다.

803 

804사용자 정의 도구는 상호 작용을 완전히 제어할 수 있지만 기본 제공 `canUseTool` 콜백을 사용하는 것보다 더 많은 구현 작업이 필요합니다.

805 

806## 관련 리소스

807 

808* [권한 구성](/ko/agent-sdk/permissions): 권한 모드 및 규칙 설정

809* [훅으로 실행 제어](/ko/agent-sdk/hooks): 에이전트 수명 주기의 주요 지점에서 사용자 정의 코드 실행

810* [TypeScript SDK 참조](/ko/agent-sdk/typescript#canusetool): 전체 canUseTool API 문서

39 39 

40분류기는 `.claude/settings.json`의 공유 프로젝트 설정에서 `autoMode`를 읽지 않으므로, 체크인된 저장소는 자체 허용 규칙을 주입할 수 없습니다.40분류기는 `.claude/settings.json`의 공유 프로젝트 설정에서 `autoMode`를 읽지 않으므로, 체크인된 저장소는 자체 허용 규칙을 주입할 수 없습니다.

41 41 

42각 범위의 항목이 결합됩니다. 개발자는 개인 항목으로 `environment`, `allow` 및 `soft_deny`를 확장할 수 있지만 관리 설정이 제공하는 항목을 제거할 수 없습니다. 허용 규칙이 분류기 내의 차단 규칙에 대한 예외로 작동하기 때문에, 개발자가 추가한 `allow` 항목은 조직의 `soft_deny` 항목을 재정의할 수 있습니다. 조합은 가산적이며, 하드 정책 경계가 아닙니다.42각 범위의 항목이 결합됩니다. 개발자는 개인 항목으로 `environment`, `allow`, `soft_deny`, `hard_deny`를 확장할 수 있지만 관리 설정이 제공하는 항목을 제거할 수 없습니다. 허용 규칙이 분류기 내의 차단 규칙에 대한 예외로 작동하기 때문에, 개발자가 추가한 `allow` 항목은 조직의 `soft_deny` 항목을 재정의할 수 있습니다. 조합은 가산적이며, 하드 정책 경계가 아닙니다.

43 43 

44<Note>44<Note>

45 분류기는 [권한 시스템](/ko/permissions) 이후에 실행되는 두 번째 게이트입니다. 사용자 의도나 분류기 구성에 관계없이 절대 실행되어서는 안 되는 작업의 경우, 관리 설정에서 `permissions.deny`를 사용하세요. 이는 분류기가 참조되기 전에 작업을 차단하며 재정의될 수 없습니다.45 분류기는 [권한 시스템](/ko/permissions) 이후에 실행되는 두 번째 게이트입니다. 사용자 의도나 분류기 구성에 관계없이 절대 실행되어서는 안 되는 작업의 경우, 관리 설정에서 `permissions.deny`를 사용하세요. 이는 분류기가 참조되기 전에 작업을 차단하며 재정의될 수 없습니다.

99 99 

100## 차단 및 허용 규칙 재정의100## 차단 및 허용 규칙 재정의

101 101 

102두 개의 추가 필드를 사용하여 분류기의 기본 제공 규칙 목록을 바꿀 수 있습니다: `autoMode.soft_deny`는 차단되는 항목을 제어하고, `autoMode.allow`는 적용되는 예외를 제어합니다. 각각은 자연어 규칙으로 읽히는 산문 설명의 배열입니다. `autoMode.deny` 필드는 없습니다. 의도에 관계없이 작업을 하드 블록하려면 분류기 이전에 실행되는 [`permissions.deny`](/ko/permissions)를 사용하세요.102세 개의 추가 필드를 사용하여 분류기의 기본 제공 규칙 목록을 바꿀 수 있습니다: `autoMode.hard_deny`는 무조건적인 보안 경계를 위한 것이고, `autoMode.soft_deny`는 사용자 의도로 해제할 수 있는 파괴적인 작업을 위한 것이며, `autoMode.allow`는 예외를 위한 것입니다. 각각은 자연어 규칙으로 읽히는 산문 설명의 배열입니다. 분류기 이전에 실행되는 도구 패턴 기반의 하드 블록의 경우 [`permissions.deny`](/ko/permissions)를 사용하세요.

103 103 

104분류기 내에서 우선순위는 세 가지 계층으로 작동합니다:104분류기 내에서 우선순위는 네 가지 계층으로 작동합니다:

105 105 

106* `soft_deny` 규칙이 먼저 차단합니다106* `hard_deny` 규칙은 무조건적으로 차단합니다. 사용자 의도와 `allow` 예외는 적용되지 않습니다.

107* `allow` 규칙이 일치하는 차단을 예외로 재정의합니다107* `soft_deny` 규칙이 다음으로 차단합니다. 사용자 의도와 `allow` 예외가 이를 재정의할 수 있습니다.

108* 명시적 사용자 의도가 둘 다 재정의합니다: 사용자의 메시지가 Claude가 수행하려는 정확한 작업을 직접적이고 구체적으로 설명하면, `soft_deny` 규칙이 일치하더라도 분류기가 이를 허용합니다108* `allow` 규칙이 일치하는 `soft_deny` 규칙을 예외로 재정의합니다.

109* 명시적 사용자 의도가 나머지 소프트 블록을 재정의합니다: 사용자의 메시지가 Claude가 수행하려는 정확한 작업을 직접적이고 구체적으로 설명하면, `soft_deny` 규칙이 일치하더라도 분류기가 이를 허용합니다.

109 110 

110일반적인 요청은 명시적 의도로 계산되지 않습니다. Claude에게 "저장소를 정리해 달라"고 요청하는 것은 강제 푸시를 승인하지 않지만, "이 브랜치를 강제 푸시해 달라"고 요청하는 것은 승인합니다.111일반적인 요청은 명시적 의도로 계산되지 않습니다. Claude에게 "저장소를 정리해 달라"고 요청하는 것은 강제 푸시를 승인하지 않지만, "이 브랜치를 강제 푸시해 달라"고 요청하는 것은 승인합니다.

111 112 

112기본 규칙을 유지하면서 자신의 규칙을 추가하려면 배열에 리터럴 문자열 `"$defaults"`를 포함하세요. 기본 규칙이 해당 위치에 삽입되므로, 사용자 정의 규칙이 앞이나 뒤에 올 수 있으며, 릴리스 전반에 걸쳐 기본 제공 목록이 변경되면서 업데이트를 계속 상속받습니다.113느슨하게 하려면, 분류기가 기본 예외가 다루지 않는 일상적인 패턴을 반복적으로 플래그할 때 `allow`에 추가하세요. 더 엄격하게 하려면, 기본값이 놓친 환경에 특정한 파괴적 위험에 대해 `soft_deny`에 추가하거나, 절대 넘어서는 안 되는 보안 경계에 대해 `hard_deny`에 추가하세요. 기본 제공 규칙을 유지하면서 자신의 규칙을 추가하려면 배열에 리터럴 문자열 `"$defaults"`를 포함하세요. 기본 규칙이 해당 위치에 삽입되므로, 사용자 정의 규칙이 앞이나 뒤에 올 수 있으며, 릴리스 전반에 걸쳐 기본 제공 목록이 변경되면서 업데이트를 계속 상속받습니다.

113 114 

114```json theme={null}115```json theme={null}

115{116{

127 "$defaults",128 "$defaults",

128 "Never run database migrations outside the migrations CLI, even against dev databases",129 "Never run database migrations outside the migrations CLI, even against dev databases",

129 "Never modify files under infra/terraform/prod/: production infrastructure changes go through the review workflow"130 "Never modify files under infra/terraform/prod/: production infrastructure changes go through the review workflow"

131 ],

132 "hard_deny": [

133 "$defaults",

134 "Never send repository contents to third-party code-review APIs"

130 ]135 ]

131 }136 }

132}137}

133```138```

134 139 

135<Danger>140<Danger>

136 `environment`, `allow` 또는 `soft_deny` 중 하나를 `"$defaults"` 없이 설정하면 해당 섹션의 전체 기본 목록이 바뀝니다. 단일 항목으로 `soft_deny`를 설정하고 `"$defaults"`를 생략하면 모든 기본 제공 차단 규칙이 버려집니다: 강제 푸시, 데이터 유출, `curl | bash`, 프로덕션 배포 및 기타 모든 기본 차단 규칙이 허용됩니다. `"$defaults"`를 생략하는 것은 목록의 전체 소유권을 가질 의도가 있을 때만 하세요. 이 경우 `claude auto-mode defaults`를 실행하여 기본 제공 규칙을 인쇄하고, 설정 파일에 복사한 다음, 각 규칙을 자신의 파이프라인 및 위험 허용도와 비교하여 검토하세요.141 `environment`, `allow`, `soft_deny` 또는 `hard_deny` 중 하나를 `"$defaults"` 없이 설정하면 해당 섹션의 전체 기본 목록이 바뀝니다. `"$defaults"`가 없는 `soft_deny` 배열은 강제 푸시, `curl | bash`, 프로덕션 배포를 포함한 모든 기본 제공 소프트 블록 규칙을 버립니다. `"$defaults"`가 없는 `hard_deny` 배열은 기본 제공 데이터 유출 및 안전 검사 우회 규칙을 버립니다.

137</Danger>142</Danger>

138 143 

139각 섹션은 독립적으로 평가되므로, `environment`만 설정하면 기본 `allow` 및 `soft_deny` 목록은 그대로 유지됩니다.144각 섹션은 독립적으로 평가되므로, `environment`만 설정하면 기본 `allow`, `soft_deny` 및 `hard_deny` 목록은 그대로 유지됩니다. `"$defaults"`를 생략하는 것은 목록의 전체 소유권을 가질 의도가 있을 때만 하세요. 이 경우 `claude auto-mode defaults`를 실행하여 기본 제공 규칙을 인쇄하고, 설정 파일에 복사한 다음, 각 규칙을 자신의 파이프라인 및 위험 허용도와 비교하여 검토하세요.

140 145 

141## 기본값 및 유효한 구성 검사146## 기본값 및 유효한 구성 검사

142 147 

143세 가지 CLI 하위 명령이 구성을 검사하고 유효성을 검사하는 데 도움이 됩니다.148세 가지 CLI 하위 명령이 구성을 검사하고 유효성을 검사하는 데 도움이 됩니다.

144 149 

145기본 제공 `environment`, `allow` 및 `soft_deny` 규칙을 JSON으로 인쇄합니다:150기본 제공 `environment`, `allow`, `soft_deny` 및 `hard_deny` 규칙을 JSON으로 인쇄합니다:

146 151 

147```bash theme={null}152```bash theme={null}

148claude auto-mode defaults153claude auto-mode defaults

154claude auto-mode config159claude auto-mode config

155```160```

156 161 

157사용자 정의 `allow` 및 `soft_deny` 규칙에 대한 AI 피드백을 받습니다:162사용자 정의 `allow`, `soft_deny` 및 `hard_deny` 규칙에 대한 AI 피드백을 받습니다:

158 163 

159```bash theme={null}164```bash theme={null}

160claude auto-mode critique165claude auto-mode critique

46| `/btw <question>` | 대화에 추가하지 않고 빠른 [side question](/ko/interactive-mode#side-questions-with-%2Fbtw)을 합니다 |46| `/btw <question>` | 대화에 추가하지 않고 빠른 [side question](/ko/interactive-mode#side-questions-with-%2Fbtw)을 합니다 |

47| `/chrome` | [Claude in Chrome](/ko/chrome) 설정을 구성합니다 |47| `/chrome` | [Claude in Chrome](/ko/chrome) 설정을 구성합니다 |

48| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/ko/skills#bundled-skills).** 프로젝트의 언어(Python, TypeScript, Java, Go, Ruby, C#, PHP 또는 cURL) 및 Managed Agents 참조에 대한 Claude API 참조 자료를 로드합니다. 도구 사용, 스트리밍, 배치, 구조화된 출력 및 일반적인 함정을 다룹니다. 또한 코드가 `anthropic` 또는 `@anthropic-ai/sdk`를 가져올 때 자동으로 활성화됩니다. `/claude-api migrate`를 실행하여 기존 Claude API 코드를 최신 모델로 업그레이드합니다. Claude는 스캔할 파일과 대상 모델을 묻고, 모델 ID, thinking 구성 및 버전 간에 변경된 기타 매개변수를 업데이트합니다. `/claude-api managed-agents-onboard`를 실행하여 처음부터 새로운 Managed Agent를 만드는 대화형 안내를 받습니다 |48| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/ko/skills#bundled-skills).** 프로젝트의 언어(Python, TypeScript, Java, Go, Ruby, C#, PHP 또는 cURL) 및 Managed Agents 참조에 대한 Claude API 참조 자료를 로드합니다. 도구 사용, 스트리밍, 배치, 구조화된 출력 및 일반적인 함정을 다룹니다. 또한 코드가 `anthropic` 또는 `@anthropic-ai/sdk`를 가져올 때 자동으로 활성화됩니다. `/claude-api migrate`를 실행하여 기존 Claude API 코드를 최신 모델로 업그레이드합니다. Claude는 스캔할 파일과 대상 모델을 묻고, 모델 ID, thinking 구성 및 버전 간에 변경된 기타 매개변수를 업데이트합니다. `/claude-api managed-agents-onboard`를 실행하여 처음부터 새로운 Managed Agent를 만드는 대화형 안내를 받습니다 |

49| `/clear` | 빈 컨텍스트로 새 대화를 시작합니다. 이전 대화는 `/resume`에서 사용 가능하게 유지됩니다. 같은 대화를 계속하면서 컨텍스트를 확보하려면 `/compact`를 대신 사용하세요. 별칭: `/reset`, `/new` |49| `/clear [name]` | 빈 컨텍스트로 새 대화를 시작합니다. 이전 대화는 `/resume`에서 사용 가능하게 유지됩니다. 이름을 전달하여 `/resume` 선택기에서 이전 대화에 레이블을 지정합니다. 같은 대화를 계속하면서 컨텍스트를 확보하려면 `/compact`를 대신 사용하세요. 별칭: `/reset`, `/new` |

50| `/color [color\|default]` | 현재 세션의 프롬프트 바 색상을 설정합니다. 사용 가능한 색상: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. 초기화하려면 `default`를 사용합니다. 인수 없이 실행하면 무작위 색상을 선택합니다. [Remote Control](/ko/remote-control)이 연결되면 색상이 claude.ai/code와 동기화됩니다 |50| `/color [color\|default]` | 현재 세션의 프롬프트 바 색상을 설정합니다. 사용 가능한 색상: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. 초기화하려면 `default`를 사용합니다. 인수 없이 실행하면 무작위 색상을 선택합니다. [Remote Control](/ko/remote-control)이 연결되면 색상이 claude.ai/code와 동기화됩니다 |

51| `/compact [instructions]` | 지금까지의 대화를 요약하여 컨텍스트를 확보합니다. 선택적으로 요약에 대한 포커스 지침을 전달합니다. [compaction이 규칙, skills 및 메모리 파일을 처리하는 방법](/ko/context-window#what-survives-compaction)을 참조하세요 |51| `/compact [instructions]` | 지금까지의 대화를 요약하여 컨텍스트를 확보합니다. 선택적으로 요약에 대한 포커스 지침을 전달합니다. [compaction이 규칙, skills 및 메모리 파일을 처리하는 방법](/ko/context-window#what-survives-compaction)을 참조하세요 |

52| `/config` | [Settings](/ko/settings) 인터페이스를 열어 테마, 모델, [output style](/ko/output-styles) 및 기타 기본 설정을 조정합니다. 별칭: `/settings` |52| `/config` | [Settings](/ko/settings) 인터페이스를 열어 테마, 모델, [output style](/ko/output-styles) 및 기타 기본 설정을 조정합니다. 별칭: `/settings` |

53| `/context` | 현재 컨텍스트 사용량을 색상 그리드로 시각화합니다. 컨텍스트 집약적 도구, 메모리 부풀림 및 용량 경고에 대한 최적화 제안을 표시합니다 |53| `/context [all]` | 현재 컨텍스트 사용량을 색상 그리드로 시각화합니다. 컨텍스트 집약적 도구, 메모리 부풀림 및 용량 경고에 대한 최적화 제안을 표시합니다. [fullscreen mode](/ko/fullscreen)에서는 항목별 분석이 그리드를 표시하기 위해 축소됩니다. `all`을 전달하여 확장합니다 |

54| `/copy [N]` | 마지막 어시스턴트 응답을 클립보드에 복사합니다. 숫자 `N`을 전달하여 N번째 최신 응답을 복사합니다: `/copy 2`는 두 번째 마지막 응답을 복사합니다. 코드 블록이 있을 때는 개별 블록 또는 전체 응답을 선택할 수 있는 대화형 선택기를 표시합니다. 선택기에서 `w`를 누르면 클립보드 대신 파일에 선택 항목을 작성하며, 이는 SSH를 통해 유용합니다 |54| `/copy [N]` | 마지막 어시스턴트 응답을 클립보드에 복사합니다. 숫자 `N`을 전달하여 N번째 최신 응답을 복사합니다: `/copy 2`는 두 번째 마지막 응답을 복사합니다. 코드 블록이 있을 때는 개별 블록 또는 전체 응답을 선택할 수 있는 대화형 선택기를 표시합니다. 선택기에서 `w`를 누르면 클립보드 대신 파일에 선택 항목을 작성하며, 이는 SSH를 통해 유용합니다 |

55| `/cost` | `/usage`의 별칭입니다 |55| `/cost` | `/usage`의 별칭입니다 |

56| `/debug [description]` | **[Skill](/ko/skills#bundled-skills).** 현재 세션에 대해 디버그 로깅을 활성화하고 세션 디버그 로그를 읽어 문제를 해결합니다. 디버그 로깅은 `claude --debug`로 시작하지 않는 한 기본적으로 꺼져 있으므로, 세션 중간에 `/debug`를 실행하면 그 시점부터 로그 캡처를 시작합니다. 선택적으로 분석에 초점을 맞추기 위해 문제를 설명합니다 |56| `/debug [description]` | **[Skill](/ko/skills#bundled-skills).** 현재 세션에 대해 디버그 로깅을 활성화하고 세션 디버그 로그를 읽어 문제를 해결합니다. 디버그 로깅은 `claude --debug`로 시작하지 않는 한 기본적으로 꺼져 있으므로, 세션 중간에 `/debug`를 실행하면 그 시점부터 로그 캡처를 시작합니다. 선택적으로 분석에 초점을 맞추기 위해 문제를 설명합니다 |

88| `/powerup` | 애니메이션 데모가 포함된 빠른 대화형 레슨을 통해 Claude Code 기능을 발견합니다 |88| `/powerup` | 애니메이션 데모가 포함된 빠른 대화형 레슨을 통해 Claude Code 기능을 발견합니다 |

89| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}v2.1.91에서 제거됨. 대신 Claude에 직접 pull request 댓글을 보도록 요청하세요. 이전 버전에서는 GitHub pull request의 댓글을 가져와 표시합니다. 현재 브랜치의 PR을 자동으로 감지하거나 PR URL 또는 번호를 전달합니다. `gh` CLI가 필요합니다 |89| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}v2.1.91에서 제거됨. 대신 Claude에 직접 pull request 댓글을 보도록 요청하세요. 이전 버전에서는 GitHub pull request의 댓글을 가져와 표시합니다. 현재 브랜치의 PR을 자동으로 감지하거나 PR URL 또는 번호를 전달합니다. `gh` CLI가 필요합니다 |

90| `/privacy-settings` | 개인정보 보호 설정을 보고 업데이트합니다. Pro 및 Max 요금제 구독자만 사용 가능합니다 |90| `/privacy-settings` | 개인정보 보호 설정을 보고 업데이트합니다. Pro 및 Max 요금제 구독자만 사용 가능합니다 |

91| `/radio` | Claude FM lo-fi 라디오를 브라우저에서 엽니다. 브라우저를 사용할 수 없을 때 스트림 URL을 인쇄합니다. Bedrock, Vertex 또는 Foundry에서는 사용할 수 없습니다 |

91| `/recap` | 현재 세션의 한 줄 요약을 요청 시 생성합니다. 자동으로 나타나는 [Session recap](/ko/interactive-mode#session-recap)을 참조하세요. 이는 떠난 후 표시됩니다 |92| `/recap` | 현재 세션의 한 줄 요약을 요청 시 생성합니다. 자동으로 나타나는 [Session recap](/ko/interactive-mode#session-recap)을 참조하세요. 이는 떠난 후 표시됩니다 |

92| `/release-notes` | 대화형 버전 선택기에서 변경 로그를 봅니다. 특정 버전을 선택하여 해당 릴리스 노트를 보거나, 모든 버전을 표시하도록 선택합니다 |93| `/release-notes` | 대화형 버전 선택기에서 변경 로그를 봅니다. 특정 버전을 선택하여 해당 릴리스 노트를 보거나, 모든 버전을 표시하도록 선택합니다 |

93| `/reload-plugins` | 모든 활성 [plugins](/ko/plugins)를 다시 로드하여 재시작하지 않고 보류 중인 변경 사항을 적용합니다. 각 다시 로드된 구성 요소의 개수를 보고하고 로드 오류를 표시합니다 |94| `/reload-plugins` | 모든 활성 [plugins](/ko/plugins)를 다시 로드하여 재시작하지 않고 보류 중인 변경 사항을 적용합니다. 각 다시 로드된 구성 요소의 개수를 보고하고 로드 오류를 표시합니다 |

116| `CLAUDE_CODE_MAX_RETRIES` | 실패한 API 요청을 재시도할 횟수를 재정의합니다(기본값: 10) |116| `CLAUDE_CODE_MAX_RETRIES` | 실패한 API 요청을 재시도할 횟수를 재정의합니다(기본값: 10) |

117| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | 병렬로 실행할 수 있는 읽기 전용 도구 및 subagent의 최대 수(기본값: 10). 더 높은 값은 병렬 처리를 증가시키지만 더 많은 리소스를 소비합니다. |117| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | 병렬로 실행할 수 있는 읽기 전용 도구 및 subagent의 최대 수(기본값: 10). 더 높은 값은 병렬 처리를 증가시키지만 더 많은 리소스를 소비합니다. |

118| `CLAUDE_CODE_MCP_ALLOWLIST_ENV` | stdio MCP 서버를 안전한 기본 환경과 서버의 구성된 `env`만으로 생성하려면 `1`로 설정합니다. 셸 환경을 상속하지 않습니다. |118| `CLAUDE_CODE_MCP_ALLOWLIST_ENV` | stdio MCP 서버를 안전한 기본 환경과 서버의 구성된 `env`만으로 생성하려면 `1`로 설정합니다. 셸 환경을 상속하지 않습니다. |

119| `CLAUDE_CODE_NATIVE_CURSOR` | 터미널의 자체 커서를 입력 캐럿에서 그려진 블록 대신 표시하려면 `1`로 설정합니다. 커서는 터미널의 깜박임, 모양, 포커스 설정을 존중합니다. |

119| `CLAUDE_CODE_NEW_INIT` | `/init`이 대화형 설정 흐름을 실행하도록 하려면 `1`로 설정합니다. 흐름은 코드베이스를 탐색하고 작성하기 전에 CLAUDE.md, skill 및 훅을 포함하여 생성할 파일을 묻습니다. 이 변수가 없으면 `/init`은 프롬프트 없이 자동으로 CLAUDE.md를 생성합니다. |120| `CLAUDE_CODE_NEW_INIT` | `/init`이 대화형 설정 흐름을 실행하도록 하려면 `1`로 설정합니다. 흐름은 코드베이스를 탐색하고 작성하기 전에 CLAUDE.md, skill 및 훅을 포함하여 생성할 파일을 묻습니다. 이 변수가 없으면 `/init`은 프롬프트 없이 자동으로 CLAUDE.md를 생성합니다. |

120| `CLAUDE_CODE_NO_FLICKER` | [전체 화면 렌더링](/ko/fullscreen)을 활성화하려면 `1`로 설정합니다. 이는 깜박임을 줄이고 긴 대화에서 메모리를 평탄하게 유지하는 연구 미리보기입니다. [`tui`](/ko/settings#available-settings) 설정과 동일합니다. `/tui fullscreen`으로도 전환할 수 있습니다. |121| `CLAUDE_CODE_NO_FLICKER` | [전체 화면 렌더링](/ko/fullscreen)을 활성화하려면 `1`로 설정합니다. 이는 깜박임을 줄이고 긴 대화에서 메모리를 평탄하게 유지하는 연구 미리보기입니다. [`tui`](/ko/settings#available-settings) 설정과 동일합니다. `/tui fullscreen`으로도 전환할 수 있습니다. |

121| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 인증용 OAuth 새로 고침 토큰입니다. 설정하면 `claude auth login`이 브라우저를 열지 않고 이 토큰을 직접 교환합니다. `CLAUDE_CODE_OAUTH_SCOPES`가 필요합니다. 자동화된 환경에서 인증을 프로비저닝하는 데 유용합니다. |122| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 인증용 OAuth 새로 고침 토큰입니다. 설정하면 `claude auth login`이 브라우저를 열지 않고 이 토큰을 직접 교환합니다. `CLAUDE_CODE_OAUTH_SCOPES`가 필요합니다. 자동화된 환경에서 인증을 프로비저닝하는 데 유용합니다. |

191| `DISABLE_TELEMETRY` | 원격 분석을 거부하려면 `1`로 설정합니다. 원격 분석 이벤트에는 코드, 파일 경로 또는 bash 명령과 같은 사용자 데이터가 포함되지 않습니다. |192| `DISABLE_TELEMETRY` | 원격 분석을 거부하려면 `1`로 설정합니다. 원격 분석 이벤트에는 코드, 파일 경로 또는 bash 명령과 같은 사용자 데이터가 포함되지 않습니다. |

192| `DISABLE_UPDATES` | 수동 `claude update` 및 `claude install`을 포함한 모든 업데이트를 차단하려면 `1`로 설정합니다. `DISABLE_AUTOUPDATER`보다 더 엄격합니다. 자신의 채널을 통해 Claude Code를 배포하고 사용자가 자체 업데이트하지 않아야 할 때 사용합니다. |193| `DISABLE_UPDATES` | 수동 `claude update` 및 `claude install`을 포함한 모든 업데이트를 차단하려면 `1`로 설정합니다. `DISABLE_AUTOUPDATER`보다 더 엄격합니다. 자신의 채널을 통해 Claude Code를 배포하고 사용자가 자체 업데이트하지 않아야 할 때 사용합니다. |

193| `DISABLE_UPGRADE_COMMAND` | `/upgrade` 명령을 숨기려면 `1`로 설정합니다. |194| `DISABLE_UPGRADE_COMMAND` | `/upgrade` 명령을 숨기려면 `1`로 설정합니다. |

195| `DO_NOT_TRACK` | 원격 분석을 거부하려면 `1`로 설정합니다. `DISABLE_TELEMETRY` 설정과 동일합니다. [표준 교차 도구 규칙](https://consoledonottrack.com/)로 인정됩니다. |

194| `ENABLE_CLAUDEAI_MCP_SERVERS` | Claude Code에서 [claude.ai MCP 서버](/ko/mcp#use-mcp-servers-from-claude-ai)를 비활성화하려면 `false`로 설정합니다. 로그인한 사용자의 경우 기본적으로 활성화됩니다. |196| `ENABLE_CLAUDEAI_MCP_SERVERS` | Claude Code에서 [claude.ai MCP 서버](/ko/mcp#use-mcp-servers-from-claude-ai)를 비활성화하려면 `false`로 설정합니다. 로그인한 사용자의 경우 기본적으로 활성화됩니다. |

195| `ENABLE_PROMPT_CACHING_1H` | API 키, [Bedrock](/ko/amazon-bedrock), [Vertex](/ko/google-vertex-ai), [Foundry](/ko/microsoft-foundry) 사용자를 위해 기본 5분 대신 1시간 프롬프트 캐시 TTL을 요청하려면 `1`로 설정합니다. 구독 사용자는 자동으로 1시간 TTL을 받습니다. 1시간 캐시 쓰기는 더 높은 요금으로 청구됩니다. |197| `ENABLE_PROMPT_CACHING_1H` | API 키, [Bedrock](/ko/amazon-bedrock), [Vertex](/ko/google-vertex-ai), [Foundry](/ko/microsoft-foundry) 사용자를 위해 기본 5분 대신 1시간 프롬프트 캐시 TTL을 요청하려면 `1`로 설정합니다. 구독 사용자는 자동으로 1시간 TTL을 받습니다. 1시간 캐시 쓰기는 더 높은 요금으로 청구됩니다. |

196| `ENABLE_PROMPT_CACHING_1H_BEDROCK` | 더 이상 사용되지 않음. 대신 `ENABLE_PROMPT_CACHING_1H` 사용 |198| `ENABLE_PROMPT_CACHING_1H_BEDROCK` | 더 이상 사용되지 않음. 대신 `ENABLE_PROMPT_CACHING_1H` 사용 |

31| `Not logged in · Please run /login` | [인증](#not-logged-in) |31| `Not logged in · Please run /login` | [인증](#not-logged-in) |

32| `Invalid API key` | [인증](#invalid-api-key) |32| `Invalid API key` | [인증](#invalid-api-key) |

33| `This organization has been disabled` | [인증](#this-organization-has-been-disabled) |33| `This organization has been disabled` | [인증](#this-organization-has-been-disabled) |

34| `Routines are disabled by your organization's policy` | [인증](#routines-are-disabled-by-your-organizations-policy) |

34| `OAuth token revoked` / `OAuth token has expired` | [인증](#oauth-token-revoked-or-expired) |35| `OAuth token revoked` / `OAuth token has expired` | [인증](#oauth-token-revoked-or-expired) |

35| `does not meet scope requirement user:profile` | [인증](#oauth-scope-requirement) |36| `does not meet scope requirement user:profile` | [인증](#oauth-scope-requirement) |

36| `Unable to connect to API` | [네트워크](#unable-to-connect-to-api) |37| `Unable to connect to API` | [네트워크](#unable-to-connect-to-api) |

252* 그 후 `/status`를 실행하여 활성 자격 증명이 구독인지 확인합니다.253* 그 후 `/status`를 실행하여 활성 자격 증명이 구독인지 확인합니다.

253* 환경 변수가 설정되지 않았는데도 오류가 지속되면 비활성화된 조직이 `/login`에 연결된 것입니다. 지원팀에 문의하거나 다른 계정으로 로그인합니다.254* 환경 변수가 설정되지 않았는데도 오류가 지속되면 비활성화된 조직이 `/login`에 연결된 것입니다. 지원팀에 문의하거나 다른 계정으로 로그인합니다.

254 255 

256### Routines are disabled by your organization's policy

257 

258팀 또는 엔터프라이즈 관리자가 조직 수준에서 루틴을 비활성화했습니다. 오류는 `/schedule` 및 claude.ai/code의 [Routines](/ko/routines) UI에서 루틴을 생성하거나 실행하려고 할 때 나타납니다.

259 

260```text theme={null}

261Routines are disabled by your organization's policy.

262```

263 

264이는 서버 측 설정이므로 로컬 설정, 환경 변수 또는 CLI 플래그에서 재정의할 수 없습니다.

265 

266**할 일:**

267 

268* 관리자에게 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)에서 **Routines** 토글을 활성화하도록 요청합니다.

269* 조직 수준의 루틴이 필요하지 않은 일회성 예약 작업의 경우 [예약된 작업](/ko/scheduled-tasks)을 참조하십시오.

270 

255### OAuth token revoked or expired271### OAuth token revoked or expired

256 272 

257저장된 로그인이 더 이상 유효하지 않습니다. 취소된 토큰은 어디서나 로그아웃했거나 관리자가 액세스를 제거했음을 의미합니다. 만료된 토큰은 자동 새로 고침이 세션 중에 실패했음을 의미합니다.273저장된 로그인이 더 이상 유효하지 않습니다. 취소된 토큰은 어디서나 로그아웃했거나 관리자가 액세스를 제거했음을 의미합니다. 만료된 토큰은 자동 새로 고침이 세션 중에 실패했음을 의미합니다.

289 289 

290Claude가 응답한 후 다중 부분 요청의 후속 단계 또는 워크플로우의 자연스러운 계속과 같은 대화 기록을 기반으로 제안이 계속 나타납니다.290Claude가 응답한 후 다중 부분 요청의 후속 단계 또는 워크플로우의 자연스러운 계속과 같은 대화 기록을 기반으로 제안이 계속 나타납니다.

291 291 

292* **Tab** 또는 **Right 화살표**를 눌러 제안을 수락하거나 **Enter**를 눌러 수락하고 제출292* **Tab** 또는 **Right 화살표**를 눌러 제안을 프롬프트 입력에 배치한 후 **Enter**를 눌러 제출합니다

293* 입력을 시작하여 제안 해제293* 입력을 시작하여 제안을 해제합니다

294 294 

295제안은 부모 대화의 프롬프트 캐시를 재사용하는 백그라운드 요청으로 실행되므로 추가 비용은 최소입니다. Claude Code는 불필요한 비용을 피하기 위해 캐시가 콜드일 때 제안 생성을 건너뜁니다.295제안은 부모 대화의 프롬프트 캐시를 재사용하는 백그라운드 요청으로 실행되므로 추가 비용은 최소입니다. Claude Code는 불필요한 비용을 피하기 위해 캐시가 콜드일 때 제안 생성을 건너뜁니다.

296 296 

263 --header "Authorization: Bearer your-token"263 --header "Authorization: Bearer your-token"

264```264```

265 265 

266`.mcp.json`, `~/.claude.json` 또는 `claude mcp add-json`을 통해 JSON으로 MCP 서버를 구성할 때, `type` 필드는 `http`의 별칭으로 `streamable-http`를 허용합니다. MCP 사양은 이 전송에 대해 `streamable-http`라는 이름을 사용하므로 서버 설명서에서 복사한 구성이 수정 없이 작동합니다.

267 

266### 옵션 2: 원격 SSE 서버 추가268### 옵션 2: 원격 SSE 서버 추가

267 269 

268<Warning>270<Warning>