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

309 </Tab>309 </Tab>

310</Tabs>310</Tabs>

311 311 

312Para HTTP (não-streaming), use `"type": "http"` em vez disso.312Para o transporte HTTP em fluxo contínuo, use `"type": "http"` em vez disso. Em `.mcp.json` e outros arquivos de configuração JSON, `"streamable-http"` é aceito como um alias para `"http"`. A opção programática `mcpServers` aceita apenas `"http"`.

313 313 

314### Servidores MCP SDK314### Servidores MCP SDK

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, # Uma descrição breve (3-5 palavras) da tarefa

2298 "prompt": str, # The task for the agent to perform2298 "prompt": str, # A tarefa para o agente executar

2299 "subagent_type": str, # The type of specialized agent to use2299 "subagent_type": str, # O tipo de agente especializado a usar

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, # Resultado final do subagente

2308 "usage": dict | None, # Token usage statistics2308 "usage": dict | None, # Estatísticas de uso de tokens

2309 "total_cost_usd": float | None, # Estimated total cost in USD2309 "total_cost_usd": float | None, # Custo total estimado em USD

2310 "duration_ms": int | None, # Execution duration in milliseconds2310 "duration_ms": int | None, # Duração da execução em milissegundos

2311}2311}

2312```2312```

2313 2313 

2315 2315 

2316**Nome da ferramenta:** `AskUserQuestion`2316**Nome da ferramenta:** `AskUserQuestion`

2317 2317 

2318Faz perguntas de esclarecimento ao usuário durante a execução. Veja [Handle approvals and user input](/pt/agent-sdk/user-input#handle-clarifying-questions) para detalhes de uso.2318Faz perguntas de esclarecimento ao usuário durante a execução. Veja [Lidar com aprovações e entrada do usuário](/pt/agent-sdk/user-input#handle-clarifying-questions) para detalhes de uso.

2319 2319 

2320**Entrada:**2320**Entrada:**

2321 2321 

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

2323{2323{

2324 "questions": [ # Questions to ask the user (1-4 questions)2324 "questions": [ # Perguntas a fazer ao usuário (1-4 perguntas)

2325 {2325 {

2326 "question": str, # The complete question to ask the user2326 "question": str, # A pergunta completa a fazer ao usuário

2327 "header": str, # Very short label displayed as a chip/tag (max 12 chars)2327 "header": str, # Rótulo muito breve exibido como chip/tag (máx 12 caracteres)

2328 "options": [ # The available choices (2-4 options)2328 "options": [ # As escolhas disponíveis (2-4 opções)

2329 {2329 {

2330 "label": str, # Display text for this option (1-5 words)2330 "label": str, # Texto de exibição para esta opção (1-5 palavras)

2331 "description": str, # Explanation of what this option means2331 "description": str, # Explicação do que esta opção significa

2332 }2332 }

2333 ],2333 ],

2334 "multiSelect": bool, # Set to true to allow multiple selections2334 "multiSelect": bool, # Defina como true para permitir múltiplas seleções

2335 }2335 }

2336 ],2336 ],

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

2338 # Respostas do usuário preenchidas pelo sistema de permissões. Respostas

2339 # de múltipla seleção podem ser uma lista de rótulos ou uma string separada por vírgula

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": [ # As perguntas que foram feitas

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], # Mapeia texto da pergunta para string de resposta

2354 # Multi-select answers are comma-separated2356 # Respostas de múltipla seleção são separadas por vírgula

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, # O comando a executar

2367 "timeout": int | None, # Optional timeout in milliseconds (max 600000)2369 "timeout": int | None, # Tempo limite opcional em milissegundos (máx 600000)

2368 "description": str | None, # Clear, concise description (5-10 words)2370 "description": str | None, # Descrição clara e concisa (5-10 palavras)

2369 "run_in_background": bool | None, # Set to true to run in background2371 "run_in_background": bool | None, # Defina como true para executar em segundo plano

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, # Saída combinada de stdout e stderr

2378 "exitCode": int, # Exit code of the command2380 "exitCode": int, # Código de saída do comando

2379 "killed": bool | None, # Whether command was killed due to timeout2381 "killed": bool | None, # Se o comando foi interrompido devido ao tempo limite

2380 "shellId": str | None, # Shell ID for background processes2382 "shellId": str | None, # ID do shell para processos em segundo plano

2381}2383}

2382```2384```

2383 2385 

2385 2387 

2386**Nome da ferramenta:** `Monitor`2388**Nome da ferramenta:** `Monitor`

2387 2389 

2388Executa um script de fundo e entrega cada linha stdout para Claude como um evento para que ele possa reagir sem polling. Monitor segue as mesmas regras de permissão que Bash. Veja a [Monitor tool reference](/pt/tools-reference#monitor-tool) para comportamento e disponibilidade de provedor.2390Executa um script de fundo e entrega cada linha stdout para Claude como um evento para que ele possa reagir sem polling. Monitor segue as mesmas regras de permissão que Bash. Veja a [referência da ferramenta Monitor](/pt/tools-reference#monitor-tool) para comportamento e disponibilidade de provedor.

2389 2391 

2390**Entrada:**2392**Entrada:**

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, # Script de shell; cada linha stdout é um evento, exit encerra a observação

2395 "description": str, # Short description shown in notifications2397 "description": str, # Descrição breve mostrada em notificações

2396 "timeout_ms": int | None, # Kill after this deadline (default 300000, max 3600000)2398 "timeout_ms": int | None, # Interromper após este prazo (padrão 300000, máx 3600000)

2397 "persistent": bool | None, # Run for the lifetime of the session; stop with TaskStop2399 "persistent": bool | None, # Executar pela vida útil da sessão; parar com 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 da tarefa de monitor de fundo

2406 "timeoutMs": int, # Timeout deadline in milliseconds (0 when persistent)2408 "timeoutMs": int, # Prazo de tempo limite em milissegundos (0 quando persistente)

2407 "persistent": bool | None, # True when running until TaskStop or session end2409 "persistent": bool | None, # True quando executando até TaskStop ou fim da sessão

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, # O caminho absoluto do arquivo a modificar

2420 "old_string": str, # The text to replace2422 "old_string": str, # O texto a substituir

2421 "new_string": str, # The text to replace it with2423 "new_string": str, # O texto para substituir por

2422 "replace_all": bool | None, # Replace all occurrences (default False)2424 "replace_all": bool | None, # Substituir todas as ocorrências (padrão 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, # Mensagem de confirmação

2431 "replacements": int, # Number of replacements made2433 "replacements": int, # Número de substituições realizadas

2432 "file_path": str, # File path that was edited2434 "file_path": str, # Caminho do arquivo que foi editado

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, # O caminho absoluto do arquivo a ler

2445 "offset": int | None, # The line number to start reading from2447 "offset": int | None, # O número da linha para começar a ler

2446 "limit": int | None, # The number of lines to read2448 "limit": int | None, # O número de linhas a ler

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, # Conteúdo do arquivo com números de linha

2455 "total_lines": int, # Total number of lines in file2457 "total_lines": int, # Número total de linhas no arquivo

2456 "lines_returned": int, # Lines actually returned2458 "lines_returned": int, # Linhas realmente retornadas

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, # Dados de imagem codificados em Base64

2465 "mime_type": str, # Image MIME type2467 "mime_type": str, # Tipo MIME da imagem

2466 "file_size": int, # File size in bytes2468 "file_size": int, # Tamanho do arquivo em bytes

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, # O caminho absoluto do arquivo a escrever

2479 "content": str, # The content to write to the file2481 "content": str, # O conteúdo a escrever no arquivo

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, # Mensagem de sucesso

2488 "bytes_written": int, # Number of bytes written2490 "bytes_written": int, # Número de bytes escritos

2489 "file_path": str, # File path that was written2491 "file_path": str, # Caminho do arquivo que foi escrito

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, # O padrão glob para corresponder arquivos

2502 "path": str | None, # The directory to search in (defaults to cwd)2504 "path": str | None, # O diretório a pesquisar (padrão 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], # Array de caminhos de arquivo correspondentes

2511 "count": int, # Number of matches found2513 "count": int, # Número de correspondências encontradas

2512 "search_path": str, # Search directory used2514 "search_path": str, # Diretório de pesquisa usado

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, # O padrão de expressão regular

2525 "path": str | None, # File or directory to search in2527 "path": str | None, # Arquivo ou diretório a pesquisar

2526 "glob": str | None, # Glob pattern to filter files2528 "glob": str | None, # Padrão glob para filtrar arquivos

2527 "type": str | None, # File type to search2529 "type": str | None, # Tipo de arquivo a pesquisar

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

2529 "-i": bool | None, # Case insensitive search2531 "-i": bool | None, # Pesquisa insensível a maiúsculas/minúsculas

2530 "-n": bool | None, # Show line numbers2532 "-n": bool | None, # Mostrar números de linha

2531 "-B": int | None, # Lines to show before each match2533 "-B": int | None, # Linhas a mostrar antes de cada correspondência

2532 "-A": int | None, # Lines to show after each match2534 "-A": int | None, # Linhas a mostrar após cada correspondência

2533 "-C": int | None, # Lines to show before and after2535 "-C": int | None, # Linhas a mostrar antes e depois

2534 "head_limit": int | None, # Limit output to first N lines/entries2536 "head_limit": int | None, # Limitar saída às primeiras N linhas/entradas

2535 "multiline": bool | None, # Enable multiline mode2537 "multiline": bool | None, # Ativar modo multilinha

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], # Arquivos contendo correspondências

2561 "count": int, # Number of files with matches2563 "count": int, # Número de arquivos com correspondências

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, # Caminho absoluto para o notebook Jupyter

2574 "cell_id": str | None, # The ID of the cell to edit2576 "cell_id": str | None, # O ID da célula a editar

2575 "new_source": str, # The new source for the cell2577 "new_source": str, # A nova fonte para a célula

2576 "cell_type": "code" | "markdown" | None, # The type of the cell2578 "cell_type": "code" | "markdown" | None, # O tipo da célula

2577 "edit_mode": "replace" | "insert" | "delete" | None, # Edit operation type2579 "edit_mode": "replace" | "insert" | "delete" | None, # Tipo de operação de edição

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, # Mensagem de sucesso

2586 "edit_type": "replaced" | "inserted" | "deleted", # Type of edit performed2588 "edit_type": "replaced" | "inserted" | "deleted", # Tipo de edição realizada

2587 "cell_id": str | None, # Cell ID that was affected2589 "cell_id": str | None, # ID da célula que foi afetada

2588 "total_cells": int, # Total cells in notebook after edit2590 "total_cells": int, # Total de células no notebook após edição

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, # A URL para buscar conteúdo

2601 "prompt": str, # The prompt to run on the fetched content2603 "prompt": str, # O prompt a executar no conteúdo buscado

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, # Resposta do modelo de IA ao prompt

2610 "url": str, # URL that was fetched2612 "url": str, # URL que foi buscada

2611 "final_url": str | None, # Final URL after redirects2613 "final_url": str | None, # URL final após redirecionamentos

2612 "status_code": int | None, # HTTP status code2614 "status_code": int | None, # Código de status 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, # A consulta de pesquisa a usar

2625 "allowed_domains": list[str] | None, # Only include results from these domains2627 "allowed_domains": list[str] | None, # Incluir apenas resultados desses domínios

2626 "blocked_domains": list[str] | None, # Never include results from these domains2628 "blocked_domains": list[str] | None, # Nunca incluir resultados desses domínios

2627}2629}

2628```2630```

2629 2631 

2647{2649{

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

2649 {2651 {

2650 "content": str, # The task description2652 "content": str, # A descrição da tarefa

2651 "status": "pending" | "in_progress" | "completed", # Task status2653 "status": "pending" | "in_progress" | "completed", # Status da tarefa

2652 "activeForm": str, # Active form of the description2654 "activeForm": str, # Forma ativa da descrição

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, # Mensagem de sucesso

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, # O ID do shell de fundo

2676 "filter": str | None, # Optional regex to filter output lines2678 "filter": str | None, # Regex opcional para filtrar linhas de saída

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, # Nova saída desde a última verificação

2685 "status": "running" | "completed" | "failed", # Current shell status2687 "status": "running" | "completed" | "failed", # Status atual do shell

2686 "exitCode": int | None, # Exit code when completed2688 "exitCode": int | None, # Código de saída quando concluído

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 # O ID do shell de fundo a interromper

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, # Mensagem de sucesso

2707 "shell_id": str, # ID of the killed shell2709 "shell_id": str, # ID do shell interrompido

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 # O plano a executar pelo usuário para aprovação

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, # Mensagem de confirmação

2728 "approved": bool | None, # Whether user approved the plan2730 "approved": bool | None, # Se o usuário aprovou o plano

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 # Nome de servidor opcional para filtrar recursos por

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, # O nome do servidor MCP

2770 "uri": str, # The resource URI to read2772 "uri": str, # A URI do recurso a ler

2771}2773}

2772```2774```

2773 2775 

308| `tag` | `string \| null` | obrigatório | String de tag, ou `null` para limpar |308| `tag` | `string \| null` | obrigatório | String de tag, ou `null` para limpar |

309| `options.dir` | `string` | `undefined` | Caminho do diretório do projeto. Quando omitido, pesquisa todos os diretórios de projeto |309| `options.dir` | `string` | `undefined` | Caminho do diretório do projeto. Quando omitido, pesquisa todos os diretórios de projeto |

310 310 

311### `resolveSettings()`

312 

313Resolve as configurações efetivas do Claude Code para um determinado diretório usando o mesmo mecanismo de mesclagem que o CLI, sem gerar o Claude CLI. Use-o para inspecionar qual configuração uma chamada `query()` veria antes de invocar uma.

314 

315<Note>

316 Esta função é alfa e sua API pode mudar antes da estabilização. Ela lê fontes MDM, incluindo plist do macOS e HKLM/HKCU do Windows, para paridade com inicialização do CLI, mas não executa o subprocesso `policyHelper` configurado pelo administrador. O campo `permissions.defaultMode` é retornado como está de todos os níveis, incluindo configurações de projeto. O filtro de confiança que o CLI aplica antes de honrar modos de permissão crescentes não é aplicado.

317</Note>

318 

319```typescript theme={null}

320function resolveSettings(

321 options?: ResolveSettingsOptions

322): Promise<ResolvedSettings>;

323```

324 

325#### Parâmetros

326 

327`resolveSettings()` aceita um único objeto de opções. Todos os campos são opcionais.

328 

329| Parâmetro | Tipo | Padrão | Descrição |

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

331| `options.cwd` | `string` | `process.cwd()` | Diretório para resolver configurações de projeto e local relativas a |

332| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | Todas as fontes | Quais fontes do sistema de arquivos carregar. Passe `[]` para pular configurações de usuário, projeto e local. Configurações de política gerenciada carregam em todos os casos |

333| `options.managedSettings` | `Settings` | `undefined` | Configurações de política restritiva mescladas no nível de precedência de política gerenciada. Chaves não restritivas como `model` são silenciosamente descartadas |

334| `options.serverManagedSettings` | `Settings` | `undefined` | Payload de configurações gerenciadas pelo servidor de `/api/claude_code/settings`. Chaves não restritivas passam sem filtro |

335 

336#### Tipo de retorno: `ResolvedSettings`

337 

338`resolveSettings()` retorna um objeto descrevendo as configurações mescladas e a fonte que contribuiu para cada chave.

339 

340| Propriedade | Tipo | Descrição |

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

342| `effective` | `Settings` | Configurações mescladas após aplicar todas as fontes habilitadas em ordem de precedência |

343| `provenance` | `Partial<Record<keyof Settings, ProvenanceEntry>>` | Para cada chave de nível superior em `effective`, qual fonte forneceu o valor |

344| `sources` | `Array<{ source, settings, path?, policyOrigin? }>` | Configurações brutas por fonte, ordenadas de precedência mais baixa para mais alta |

345 

346#### Exemplo

347 

348O exemplo abaixo resolve configurações para um diretório de projeto e imprime a fonte que controla o período de limpeza.

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## Tipos362## Tipos

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 

1109Evento de fluxo emitido quando o sistema de permissão nega automaticamente uma chamada de ferramenta sem um prompt interativo. Use-o para renderizar a negação em sua interface do usuário conforme ela acontece, em vez de apenas observar o resultado da ferramenta `is_error` que se segue. O caminho de solicitação interativa chega à sua aplicação separadamente através do callback [`canUseTool`](#canusetool). As negações emitidas por um hook `PreToolUse` não são relatadas através deste evento.

1110 

1111Este evento requer Claude Code v2.1.136 ou posterior.

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| Campo | Tipo | Descrição |

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

1130| `tool_name` | `string` | Nome da ferramenta que foi negada |

1131| `tool_use_id` | `string` | ID do bloco `tool_use` que esta negação responde |

1132| `agent_id` | `string` | ID do subagente quando a chamada negada originou-se dentro de um subagente. Espelha o campo em `can_use_tool` para roteamento do lado do host |

1133| `decision_reason_type` | `string` | Discriminador para o componente que decidiu, como `"rule"`, `"mode"`, `"classifier"`, ou `"asyncAgent"` |

1134| `decision_reason` | `string` | Razão legível por humanos do componente que decidiu, quando disponível |

1135| `message` | `string` | Mensagem de rejeição retornada ao modelo no `tool_result` |

1136 

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

1056 1138 

1057Informações sobre um uso de ferramenta negado.1139Informações sobre um uso de ferramenta negado.

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# Lidar com aprovações e entrada do usuário

6 

7> Apresente as solicitações de aprovação e perguntas de esclarecimento do Claude aos usuários e retorne suas decisões ao SDK.

8 

9Ao trabalhar em uma tarefa, Claude às vezes precisa verificar com os usuários. Pode precisar de permissão antes de excluir arquivos ou precisar perguntar qual banco de dados usar para um novo projeto. Seu aplicativo precisa apresentar essas solicitações aos usuários para que Claude possa continuar com sua entrada.

10 

11Claude solicita entrada do usuário em duas situações: quando precisa de **permissão para usar uma ferramenta** (como excluir arquivos ou executar comandos) e quando tem **perguntas de esclarecimento** (por meio da ferramenta `AskUserQuestion`). Ambas acionam seu callback `canUseTool`, que pausa a execução até que você retorne uma resposta. Isso é diferente dos turnos de conversa normais, onde Claude termina e aguarda sua próxima mensagem.

12 

13Para perguntas de esclarecimento, Claude gera as perguntas e opções. Seu papel é apresentá-las aos usuários e retornar suas seleções. Você não pode adicionar suas próprias perguntas a este fluxo; se precisar perguntar algo aos usuários, faça isso separadamente na lógica do seu aplicativo.

14 

15O callback pode permanecer pendente indefinidamente. A execução permanece pausada até que seu callback retorne, e o SDK apenas cancela a espera quando a própria consulta é cancelada. Se um usuário puder levar mais tempo para responder do que seu processo pode razoavelmente permanecer em execução, o SDK TypeScript suporta o [hook `defer`](/pt/hooks#defer-a-tool-call-for-later), que permite que o processo saia e retome mais tarde a partir da sessão persistida; esta opção não está disponível no SDK Python.

16 

17Este guia mostra como detectar cada tipo de solicitação e responder apropriadamente.

18 

19## Detectar quando Claude precisa de entrada

20 

21Passe um callback `canUseTool` nas opções de sua consulta. O callback é acionado sempre que Claude precisa de entrada do usuário, recebendo o nome da ferramenta e a entrada como argumentos:

22 

23<CodeGroup>

24 ```python Python theme={null}

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

26 # Solicite ao usuário e retorne permitir ou negar

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 inclui { signal: AbortSignal, suggestions?: PermissionUpdate[] }

36 // Solicite ao usuário e retorne permitir ou negar

37 }

38 

39 const options = { canUseTool: handleToolRequest };

40 ```

41</CodeGroup>

42 

43O callback é acionado em dois casos:

44 

451. **Ferramenta precisa de aprovação**: Claude quer usar uma ferramenta que não é aprovada automaticamente por [regras de permissão](/pt/agent-sdk/permissions) ou modos. Verifique `tool_name` para a ferramenta (por exemplo, `"Bash"`, `"Write"`).

462. **Claude faz uma pergunta**: Claude chama a ferramenta `AskUserQuestion`. Verifique se `tool_name == "AskUserQuestion"` para tratá-la diferentemente. Se você especificar um array `tools`, inclua `AskUserQuestion` para que isso funcione. Veja [Lidar com perguntas de esclarecimento](#handle-clarifying-questions) para detalhes.

47 

48<Note>

49 Para permitir ou negar automaticamente ferramentas sem solicitar aos usuários, use [hooks](/pt/agent-sdk/hooks) em vez disso. Os hooks são executados antes de `canUseTool` e podem permitir, negar ou modificar solicitações com base em sua própria lógica. Você também pode usar o [hook `PermissionRequest`](/pt/agent-sdk/hooks#available-hooks) para enviar notificações externas (Slack, email, push) quando Claude está aguardando aprovação.

50</Note>

51 

52## Lidar com solicitações de aprovação de ferramentas

53 

54Depois de passar um callback `canUseTool` nas opções de sua consulta, ele é acionado quando Claude quer usar uma ferramenta que não é aprovada automaticamente. Seu callback recebe três argumentos:

55 

56| Argumento | Descrição |

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

58| `toolName` | O nome da ferramenta que Claude quer usar (por exemplo, `"Bash"`, `"Write"`, `"Edit"`) |

59| `input` | Os parâmetros que Claude está passando para a ferramenta. O conteúdo varia por ferramenta. |

60| `options` (TS) / `context` (Python) | Contexto adicional incluindo `suggestions` opcional (entradas `PermissionUpdate` propostas para evitar re-solicitação) e um sinal de cancelamento. Em TypeScript, `signal` é um `AbortSignal`; em Python, o campo de sinal é reservado para uso futuro. Veja [`ToolPermissionContext`](/pt/agent-sdk/python#toolpermissioncontext) para Python. |

61 

62O objeto `input` contém parâmetros específicos da ferramenta. Exemplos comuns:

63 

64| Ferramenta | Campos de entrada |

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 

71Veja a referência do SDK para esquemas de entrada completos: [Python](/pt/agent-sdk/python#tool-input%2Foutput-types) | [TypeScript](/pt/agent-sdk/typescript#tool-input-types).

72 

73Você pode exibir essas informações ao usuário para que ele possa decidir se permite ou rejeita a ação, e então retornar a resposta apropriada.

74 

75O exemplo a seguir pede ao Claude para criar e excluir um arquivo de teste. Quando Claude tenta cada operação, o callback imprime a solicitação de ferramenta no terminal e solicita aprovação s/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 # Exiba a solicitação de ferramenta

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 # Obtenha aprovação do usuário

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

104 

105 # Retorne permitir ou negar com base na resposta do usuário

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

107 # Permitir: ferramenta executa com a entrada original (ou modificada)

108 return PermissionResultAllow(updated_input=input_data)

109 else:

110 # Negar: ferramenta não executa, Claude vê a mensagem

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

112 

113 

114 # Solução alternativa necessária: hook fictício mantém o fluxo aberto para 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 // Auxiliar para solicitar entrada do usuário no terminal

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 // Exiba a solicitação de ferramenta

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 // Obtenha aprovação do usuário

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

177 

178 // Retorne permitir ou negar com base na resposta do usuário

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

180 // Permitir: ferramenta executa com a entrada original (ou modificada)

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

182 } else {

183 // Negar: ferramenta não executa, Claude vê a mensagem

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 Em Python, `can_use_tool` requer [modo de streaming](/pt/agent-sdk/streaming-vs-single-mode) e um hook `PreToolUse` que retorna `{"continue_": True}` para manter o fluxo aberto. Sem este hook, o fluxo fecha antes que o callback de permissão possa ser invocado.

196</Note>

197 

198Este exemplo usa um fluxo s/n onde qualquer entrada diferente de `s` é tratada como uma negação. Na prática, você pode construir uma interface de usuário mais rica que permite aos usuários modificar a solicitação, fornecer feedback ou redirecionar Claude completamente. Veja [Responder a solicitações de ferramentas](#respond-to-tool-requests) para todas as maneiras que você pode responder.

199 

200### Responder a solicitações de ferramentas

201 

202Seu callback retorna um de dois tipos de resposta:

203 

204| Resposta | Python | TypeScript |

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

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

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

208 

209Ao permitir, passe a entrada da ferramenta (original ou modificada). Ao negar, forneça uma mensagem explicando por quê. Claude vê esta mensagem e pode ajustar sua abordagem.

210 

211<CodeGroup>

212 ```python Python theme={null}

213 from claude_agent_sdk.types import PermissionResultAllow, PermissionResultDeny

214 

215 # Permita que a ferramenta execute

216 return PermissionResultAllow(updated_input=input_data)

217 

218 # Bloqueie a ferramenta

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

220 ```

221 

222 ```typescript TypeScript theme={null}

223 // Permita que a ferramenta execute

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

225 

226 // Bloqueie a ferramenta

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

228 ```

229</CodeGroup>

230 

231Além de permitir ou negar, você pode modificar a entrada da ferramenta ou fornecer contexto que ajude Claude a ajustar sua abordagem:

232 

233* **Aprovar**: deixe a ferramenta executar conforme Claude solicitou

234* **Aprovar com alterações**: modifique a entrada antes da execução (por exemplo, sanitize caminhos, adicione restrições)

235* **Rejeitar**: bloqueie a ferramenta e diga ao Claude por quê

236* **Sugerir alternativa**: bloqueie mas guie Claude para o que o usuário quer em vez disso

237* **Redirecionar completamente**: use [entrada de streaming](/pt/agent-sdk/streaming-vs-single-mode) para enviar ao Claude uma instrução completamente nova

238 

239<Tabs>

240 <Tab title="Aprovar">

241 O usuário aprova a ação como está. Passe a `input` do seu callback inalterada e a ferramenta executa exatamente como Claude solicitou.

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="Aprovar com alterações">

269 O usuário aprova mas quer modificar a solicitação primeiro. Você pode alterar a entrada antes da ferramenta executar. Claude vê o resultado mas não é informado de que você alterou nada. Útil para sanitizar parâmetros, adicionar restrições ou escopar acesso.

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 # Usuário aprovou, mas escope todos os comandos para sandbox

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 // Usuário aprovou, mas escope todos os comandos para sandbox

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="Rejeitar">

301 O usuário não quer que esta ação aconteça. Bloqueie a ferramenta e forneça uma mensagem explicando por quê. Claude vê esta mensagem e pode tentar uma abordagem diferente.

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="Sugerir alternativa">

330 O usuário não quer esta ação específica, mas tem uma ideia diferente. Bloqueie a ferramenta e inclua orientação em sua mensagem. Claude lerá isso e decidirá como proceder com base em seu feedback.

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 # Usuário não quer deletar, sugira arquivar em vez disso

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 // Usuário não quer deletar, sugira arquivar em vez disso

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="Redirecionar completamente">

360 Para uma mudança completa de direção (não apenas um empurrão), use [entrada de streaming](/pt/agent-sdk/streaming-vs-single-mode) para enviar ao Claude uma nova instrução diretamente. Isso ignora a solicitação de ferramenta atual e dá ao Claude instruções completamente novas para seguir.

361 </Tab>

362</Tabs>

363 

364## Lidar com perguntas de esclarecimento

365 

366Quando Claude precisa de mais direção em uma tarefa com múltiplas abordagens válidas, ele chama a ferramenta `AskUserQuestion`. Isso aciona seu callback `canUseTool` com `toolName` definido como `AskUserQuestion`. A entrada contém as perguntas do Claude como opções de múltipla escolha, que você exibe ao usuário e retorna suas seleções.

367 

368<Tip>

369 Perguntas de esclarecimento são especialmente comuns no [modo `plan`](/pt/agent-sdk/permissions#plan-mode-plan), onde Claude explora a base de código e faz perguntas antes de propor um plano. Isso torna o modo plan ideal para fluxos de trabalho interativos onde você quer que Claude reúna requisitos antes de fazer alterações.

370</Tip>

371 

372Os passos a seguir mostram como lidar com perguntas de esclarecimento:

373 

374<Steps>

375 <Step title="Passe um callback canUseTool">

376 Passe um callback `canUseTool` nas opções de sua consulta. Por padrão, `AskUserQuestion` está disponível. Se você especificar um array `tools` para restringir as capacidades do Claude (por exemplo, um agente somente leitura com apenas `Read`, `Glob` e `Grep`), inclua `AskUserQuestion` nesse array. Caso contrário, Claude não será capaz de fazer perguntas de esclarecimento:

377 

378 <CodeGroup>

379 ```python Python theme={null}

380 async for message in query(

381 prompt="Analyze this codebase",

382 options=ClaudeAgentOptions(

383 # Inclua AskUserQuestion em sua lista de ferramentas

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 // Inclua AskUserQuestion em sua lista de ferramentas

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

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

398 // Lidar com perguntas de esclarecimento aqui

399 }

400 }

401 })) {

402 console.log(message);

403 }

404 ```

405 </CodeGroup>

406 </Step>

407 

408 <Step title="Detecte AskUserQuestion">

409 Em seu callback, verifique se `toolName` é igual a `AskUserQuestion` para tratá-lo diferentemente de outras ferramentas:

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 # Sua implementação para coletar respostas do usuário

416 return await handle_clarifying_questions(input_data)

417 # Lidar com outras ferramentas normalmente

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 // Sua implementação para coletar respostas do usuário

425 return handleClarifyingQuestions(input);

426 }

427 // Lidar com outras ferramentas normalmente

428 return promptForApproval(toolName, input);

429 };

430 ```

431 </CodeGroup>

432 </Step>

433 

434 <Step title="Analise a entrada da pergunta">

435 A entrada contém as perguntas do Claude em um array `questions`. Cada pergunta tem uma `question` (o texto a exibir), `options` (as escolhas) e `multiSelect` (se múltiplas seleções são permitidas):

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 Veja [Formato de pergunta](#question-format) para descrições completas de campos.

463 </Step>

464 

465 <Step title="Colete respostas do usuário">

466 Apresente as perguntas ao usuário e colete suas seleções. Como você faz isso depende de seu aplicativo: um prompt de terminal, um formulário web, um diálogo móvel, etc.

467 </Step>

468 

469 <Step title="Retorne respostas ao Claude">

470 Construa o objeto `answers` como um registro onde cada chave é o texto `question` e cada valor é o `label` da opção selecionada:

471 

472 | Do objeto de pergunta | Use como |

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

474 | Campo `question` (por exemplo, `"How should I format the output?"`) | Chave |

475 | Campo `label` da opção selecionada (por exemplo, `"Summary"`) | Valor |

476 

477 Para perguntas de seleção múltipla, passe um array de labels ou junte-os com `", "`. Se você [suportar entrada de texto livre](#support-free-text-input), use o texto personalizado do usuário como o valor.

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### Formato de pergunta

509 

510A entrada contém as perguntas geradas pelo Claude em um array `questions`. Cada pergunta tem estes campos:

511 

512| Campo | Descrição |

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

514| `question` | O texto completo da pergunta a exibir |

515| `header` | Rótulo curto para a pergunta (máximo 12 caracteres) |

516| `options` | Array de 2-4 escolhas, cada uma com `label` e `description`. TypeScript: opcionalmente `preview` (veja [abaixo](#option-previews-type-script)) |

517| `multiSelect` | Se `true`, os usuários podem selecionar múltiplas opções |

518 

519A estrutura que seu callback recebe:

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#### Visualizações de opção (TypeScript)

538 

539`toolConfig.askUserQuestion.previewFormat` adiciona um campo `preview` a cada opção para que seu aplicativo possa mostrar uma simulação visual ao lado do rótulo. Sem esta configuração, Claude não gera visualizações e o campo está ausente.

540 

541| `previewFormat` | `preview` contém |

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

543| não definido (padrão) | Campo está ausente. Claude não gera visualizações. |

544| `"markdown"` | Arte ASCII e blocos de código cercados |

545| `"html"` | Um fragmento `<div>` estilizado (o SDK rejeita `<script>`, `<style>` e `<!DOCTYPE>` antes que seu callback seja executado) |

546 

547O formato se aplica a todas as perguntas na sessão. Claude inclui `preview` em opções onde uma comparação visual ajuda (escolhas de layout, esquemas de cores) e a omite onde não ajudaria (confirmações sim/não, escolhas apenas de texto). Verifique se há `undefined` antes de renderizar.

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 é uma string HTML ou undefined

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

561 }

562 }

563})) {

564 // ...

565}

566```

567 

568Uma opção com uma visualização HTML:

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### Formato de resposta

579 

580Retorne um objeto `answers` mapeando cada campo `question` da pergunta para o `label` da opção selecionada:

581 

582| Campo | Descrição |

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

584| `questions` | Passe o array de perguntas original (obrigatório para processamento de ferramentas) |

585| `answers` | Objeto onde as chaves são texto de pergunta e os valores são labels selecionados |

586 

587Para perguntas de seleção múltipla, passe um array de labels ou junte-os com `", "`. Para entrada de texto livre, use o texto personalizado do usuário diretamente.

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#### Suporte para entrada de texto livre

602 

603As opções predefinidas do Claude nem sempre cobrirão o que os usuários querem. Para permitir que os usuários digitem sua própria resposta:

604 

605* Exiba uma escolha "Outro" adicional após as opções do Claude que aceita entrada de texto

606* Use o texto personalizado do usuário como o valor da resposta (não a palavra "Outro")

607 

608Veja o [exemplo completo](#complete-example) abaixo para uma implementação completa.

609 

610### Exemplo completo

611 

612Claude faz perguntas de esclarecimento quando precisa de entrada do usuário para prosseguir. Por exemplo, quando solicitado a ajudar a decidir sobre uma pilha de tecnologia para um aplicativo móvel, Claude pode perguntar sobre cross-platform vs nativo, preferências de backend ou plataformas alvo. Essas perguntas ajudam Claude a tomar decisões que correspondem às preferências do usuário em vez de adivinhar.

613 

614Este exemplo lida com essas perguntas em um aplicativo de terminal. Aqui está o que acontece em cada etapa:

615 

6161. **Rotear a solicitação**: O callback `canUseTool` verifica se o nome da ferramenta é `"AskUserQuestion"` e roteia para um manipulador dedicado

6172. **Exibir perguntas**: O manipulador percorre o array `questions` e imprime cada pergunta com opções numeradas

6183. **Coletar entrada**: O usuário pode inserir um número para selecionar uma opção ou digitar texto livre diretamente (por exemplo, "jquery", "não sei")

6194. **Mapear respostas**: O código verifica se a entrada é numérica (usa o label da opção) ou texto livre (usa o texto diretamente)

6205. **Retornar ao Claude**: A resposta inclui tanto o array `questions` original quanto o mapeamento `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 """Analise a entrada do usuário como número(s) de opção ou texto livre."""

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 """Exiba as perguntas do Claude e colete respostas do usuário."""

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 # Rotear AskUserQuestion para nosso manipulador de perguntas

670 if tool_name == "AskUserQuestion":

671 return await handle_ask_user_question(input_data)

672 # Auto-aprovar outras ferramentas para este exemplo

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 # Solução alternativa necessária: hook fictício mantém o fluxo aberto para 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 // Auxiliar para solicitar entrada do usuário no terminal

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 // Analise a entrada do usuário como número(s) de opção ou texto livre

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 // Exiba as perguntas do Claude e colete respostas do usuário

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 // Retorne as respostas ao Claude (deve incluir perguntas originais)

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 // Rotear AskUserQuestion para nosso manipulador de perguntas

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

762 return handleAskUserQuestion(input);

763 }

764 // Auto-aprovar outras ferramentas para este exemplo

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## Limitações

778 

779* **Subagentes**: `AskUserQuestion` não está disponível em subagentes gerados por meio da ferramenta Agent

780* **Limites de perguntas**: cada chamada `AskUserQuestion` suporta 1-4 perguntas com 2-4 opções cada

781 

782## Outras maneiras de obter entrada do usuário

783 

784O callback `canUseTool` e a ferramenta `AskUserQuestion` cobrem a maioria dos cenários de aprovação e esclarecimento, mas o SDK oferece outras maneiras de obter entrada dos usuários:

785 

786### Entrada de streaming

787 

788Use [entrada de streaming](/pt/agent-sdk/streaming-vs-single-mode) quando você precisar:

789 

790* **Interromper o agente no meio da tarefa**: enviar um sinal de cancelamento ou mudar de direção enquanto Claude está trabalhando

791* **Fornecer contexto adicional**: adicionar informações que Claude precisa sem esperar que ele pergunte

792* **Construir interfaces de chat**: permitir que os usuários enviem mensagens de acompanhamento durante operações de longa duração

793 

794A entrada de streaming é ideal para interfaces conversacionais onde os usuários interagem com o agente durante toda a execução, não apenas em pontos de aprovação.

795 

796### Ferramentas personalizadas

797 

798Use [ferramentas personalizadas](/pt/agent-sdk/custom-tools) quando você precisar:

799 

800* **Coletar entrada estruturada**: construir formulários, assistentes ou fluxos de trabalho de várias etapas que vão além do formato de múltipla escolha do `AskUserQuestion`

801* **Integrar sistemas de aprovação externos**: conectar a plataformas de ticketing, fluxo de trabalho ou aprovação existentes

802* **Implementar interações específicas do domínio**: criar ferramentas adaptadas às necessidades do seu aplicativo, como interfaces de revisão de código ou listas de verificação de implantação

803 

804As ferramentas personalizadas lhe dão controle total sobre a interação, mas requerem mais trabalho de implementação do que usar o callback `canUseTool` integrado.

805 

806## Recursos relacionados

807 

808* [Configurar permissões](/pt/agent-sdk/permissions): configurar modos e regras de permissão

809* [Controlar execução com hooks](/pt/agent-sdk/hooks): executar código personalizado em pontos-chave do ciclo de vida do agente

810* [Referência do SDK TypeScript](/pt/agent-sdk/typescript#canusetool): documentação completa da API canUseTool

24* [Inspecionar sua configuração efetiva](#inspect-the-defaults-and-your-effective-config) com os subcomandos `claude auto-mode`24* [Inspecionar sua configuração efetiva](#inspect-the-defaults-and-your-effective-config) com os subcomandos `claude auto-mode`

25* [Revisar negações](#review-denials) para saber o que adicionar a seguir25* [Revisar negações](#review-denials) para saber o que adicionar a seguir

26 26 

27## Where the classifier reads configuration27## Onde o classificador lê a configuração

28 28 

29O classificador lê o mesmo conteúdo [CLAUDE.md](/pt/memory) que o próprio Claude carrega, portanto uma instrução como "nunca force push" no CLAUDE.md do seu projeto orienta tanto Claude quanto o classificador ao mesmo tempo. Comece ali para convenções de projeto e regras de comportamento.29O classificador lê o mesmo conteúdo [CLAUDE.md](/pt/memory) que o próprio Claude carrega, portanto uma instrução como "nunca force push" no CLAUDE.md do seu projeto orienta tanto Claude quanto o classificador ao mesmo tempo. Comece ali para convenções de projeto e regras de comportamento.

30 30 

39 39 

40O classificador não lê `autoMode` de configurações de projeto compartilhadas em `.claude/settings.json`, portanto um repositório verificado não pode injetar suas próprias regras de permissão.40O classificador não lê `autoMode` de configurações de projeto compartilhadas em `.claude/settings.json`, portanto um repositório verificado não pode injetar suas próprias regras de permissão.

41 41 

42As entradas de cada escopo são combinadas. Um desenvolvedor pode estender `environment`, `allow` e `soft_deny` com entradas pessoais, mas não pode remover entradas que as configurações gerenciadas fornecem. Como as regras de permissão atuam como exceções às regras de bloqueio dentro do classificador, uma entrada `allow` adicionada por um desenvolvedor pode substituir uma entrada `soft_deny` da organização: a combinação é aditiva, não um limite de política rígida.42As entradas de cada escopo são combinadas. Um desenvolvedor pode estender `environment`, `allow`, `soft_deny` e `hard_deny` com entradas pessoais, mas não pode remover entradas que as configurações gerenciadas fornecem. Como as regras de permissão atuam como exceções às regras de bloqueio suave dentro do classificador, uma entrada `allow` adicionada por um desenvolvedor pode substituir uma entrada `soft_deny` da organização: a combinação é aditiva, não um limite de política rígida.

43 43 

44<Note>44<Note>

45 O classificador é um segundo portão que é executado após o [sistema de permissões](/pt/permissions). Para ações que nunca devem ser executadas, independentemente da intenção do usuário ou da configuração do classificador, use `permissions.deny` em configurações gerenciadas, que bloqueia a ação antes do classificador ser consultado e não pode ser substituída.45 O classificador é um segundo portão que é executado após o [sistema de permissões](/pt/permissions). Para ações que nunca devem ser executadas, independentemente da intenção do usuário ou da configuração do classificador, use `permissions.deny` em configurações gerenciadas, que bloqueia a ação antes do classificador ser consultado e não pode ser substituída.

99 99 

100## Substituir as regras de bloqueio e permissão100## Substituir as regras de bloqueio e permissão

101 101 

102Dois campos adicionais permitem que você substitua as listas de regras integradas do classificador: `autoMode.soft_deny` controla o que é bloqueado e `autoMode.allow` controla quais exceções se aplicam. Cada um é uma matriz de descrições em prosa, lidas como regras em linguagem natural. Não há campo `autoMode.deny`; para bloquear uma ação de forma rígida, independentemente da intenção, use [`permissions.deny`](/pt/permissions), que é executado antes do classificador.102Três campos adicionais permitem que você substitua as listas de regras integradas do classificador: `autoMode.hard_deny` para limites de segurança incondicionais, `autoMode.soft_deny` para ações destrutivas que a intenção do usuário pode contornar, e `autoMode.allow` para exceções. Cada um é uma matriz de descrições em prosa, lidas como regras em linguagem natural. Para bloqueios baseados em padrões de ferramentas que são executados antes do classificador, use [`permissions.deny`](/pt/permissions).

103 103 

104Dentro do classificador, a precedência funciona em três camadas:104Dentro do classificador, a precedência funciona em quatro camadas:

105 105 

106* Regras `soft_deny` bloqueiam primeiro106* Regras `hard_deny` bloqueiam incondicionalmente. A intenção do usuário e exceções `allow` não se aplicam.

107* Regras `allow` então substituem bloqueios correspondentes como exceções107* Regras `soft_deny` bloqueiam em seguida. A intenção do usuário e exceções `allow` podem substituir estas.

108* A intenção explícita do usuário substitui ambas: se a mensagem do usuário descreve direta e especificamente a ação exata que Claude está prestes a executar, o classificador a permite mesmo quando uma regra `soft_deny` corresponde108* Regras `allow` então substituem regras `soft_deny` correspondentes como exceções.

109* A intenção explícita do usuário substitui os bloqueios soft restantes: se a mensagem do usuário descreve direta e especificamente a ação exata que Claude está prestes a executar, o classificador a permite mesmo quando uma regra `soft_deny` corresponde.

109 110 

110Solicitações gerais não contam como intenção explícita. Pedir ao Claude para "limpar o repositório" não autoriza force-push, mas pedir ao Claude para "force-push este branch" autoriza.111Solicitações gerais não contam como intenção explícita. Pedir ao Claude para "limpar o repositório" não autoriza force-push, mas pedir ao Claude para "force-push este branch" autoriza.

111 112 

112Para afrouxar, adicione a `allow` quando o classificador sinalizar repetidamente um padrão rotineiro que as exceções padrão não cobrem. Para apertar, adicione a `soft_deny` para riscos específicos do seu ambiente que os padrões perdem. Para manter as regras integradas enquanto adiciona as suas próprias, inclua a string literal `"$defaults"` na matriz. As regras padrão são inseridas nessa posição, portanto suas regras personalizadas podem vir antes ou depois delas, e você continua a herdar atualizações conforme a lista integrada muda entre versões.113Para afrouxar, adicione a `allow` quando o classificador sinalizar repetidamente um padrão rotineiro que as exceções padrão não cobrem. Para apertar, adicione a `soft_deny` para riscos destrutivos específicos do seu ambiente que os padrões perdem, ou a `hard_deny` para limites de segurança que nunca devem ser ultrapassados. Para manter as regras integradas enquanto adiciona as suas próprias, inclua a string literal `"$defaults"` na matriz. As regras padrão são inseridas nessa posição, portanto suas regras personalizadas podem vir antes ou depois delas, e você continua a herdar atualizações conforme a lista integrada muda entre versões.

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 Definir qualquer um de `environment`, `allow` ou `soft_deny` sem `"$defaults"` substitui a lista padrão inteira para essa seção. Se você definir `soft_deny` com uma única entrada e omitir `"$defaults"`, todas as regras de bloqueio integradas serão descartadas: force push, exfiltração de dados, `curl | bash`, implantações em produção e todas as outras regras de bloqueio padrão se tornam permitidas. Omita `"$defaults"` apenas quando você pretender assumir a propriedade total da lista. Nesse caso, execute `claude auto-mode defaults` para imprimir as regras integradas, copie-as para seu arquivo de configurações e depois revise cada regra em relação ao seu próprio pipeline e tolerância ao risco.141 Definir qualquer um de `environment`, `allow`, `soft_deny` ou `hard_deny` sem `"$defaults"` substitui a lista padrão inteira para essa seção. Uma matriz `soft_deny` sem `"$defaults"` descarta todas as regras de bloqueio integradas, incluindo force push, `curl | bash` e implantações em produção. Uma matriz `hard_deny` sem `"$defaults"` descarta as regras integradas de exfiltração de dados e bypass de verificação de segurança.

137</Danger>142</Danger>

138 143 

139Cada seção é avaliada independentemente, portanto definir `environment` sozinho deixa as listas padrão `allow` e `soft_deny` intactas.144Cada seção é avaliada independentemente, portanto definir `environment` sozinho deixa as listas padrão `allow`, `soft_deny` e `hard_deny` intactas. Omita `"$defaults"` apenas quando você pretender assumir a propriedade total da lista. Para fazer isso com segurança, execute `claude auto-mode defaults` para imprimir as regras integradas, copie-as para seu arquivo de configurações e depois revise cada regra em relação ao seu próprio pipeline e tolerância ao risco.

140 145 

141## Inspecione os padrões e sua configuração efetiva146## Inspecione os padrões e sua configuração efetiva

142 147 

143Três subcomandos CLI ajudam você a inspecionar e validar sua configuração.148Três subcomandos CLI ajudam você a inspecionar e validar sua configuração.

144 149 

145Imprima as regras `environment`, `allow` e `soft_deny` integradas como JSON:150Imprima as regras `environment`, `allow`, `soft_deny` e `hard_deny` integradas como 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 

157Obtenha feedback de IA sobre suas regras `allow` e `soft_deny` personalizadas:162Obtenha feedback de IA sobre suas regras `allow`, `soft_deny` e `hard_deny` personalizadas:

158 163 

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

160claude auto-mode critique165claude auto-mode critique

46| `/btw <question>` | Fazer uma [pergunta rápida](/pt/interactive-mode#side-questions-with-%2Fbtw) sem adicionar à conversa |46| `/btw <question>` | Fazer uma [pergunta rápida](/pt/interactive-mode#side-questions-with-%2Fbtw) sem adicionar à conversa |

47| `/chrome` | Configurar configurações do [Claude no Chrome](/pt/chrome) |47| `/chrome` | Configurar configurações do [Claude no Chrome](/pt/chrome) |

48| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/pt/skills#bundled-skills).** Carregar material de referência da API Claude para a linguagem do seu projeto (Python, TypeScript, Java, Go, Ruby, C#, PHP ou cURL) e referência de Managed Agents. Cobre uso de ferramentas, streaming, lotes, saídas estruturadas e armadilhas comuns. Também ativa automaticamente quando seu código importa `anthropic` ou `@anthropic-ai/sdk`. Execute `/claude-api migrate` para atualizar o código existente da API Claude para um modelo mais recente: Claude pergunta quais arquivos verificar e qual modelo direcionar, depois atualiza IDs de modelo, configuração de thinking e outros parâmetros que mudaram entre versões. Execute `/claude-api managed-agents-onboard` para um passo a passo interativo que cria um novo Managed Agent do zero |48| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/pt/skills#bundled-skills).** Carregar material de referência da API Claude para a linguagem do seu projeto (Python, TypeScript, Java, Go, Ruby, C#, PHP ou cURL) e referência de Managed Agents. Cobre uso de ferramentas, streaming, lotes, saídas estruturadas e armadilhas comuns. Também ativa automaticamente quando seu código importa `anthropic` ou `@anthropic-ai/sdk`. Execute `/claude-api migrate` para atualizar o código existente da API Claude para um modelo mais recente: Claude pergunta quais arquivos verificar e qual modelo direcionar, depois atualiza IDs de modelo, configuração de thinking e outros parâmetros que mudaram entre versões. Execute `/claude-api managed-agents-onboard` para um passo a passo interativo que cria um novo Managed Agent do zero |

49| `/clear` | Iniciar uma nova conversa com contexto vazio. A conversa anterior permanece disponível em `/resume`. Para liberar contexto enquanto continua a mesma conversa, use `/compact` em vez disso. Aliases: `/reset`, `/new` |49| `/clear [name]` | Iniciar uma nova conversa com contexto vazio. A conversa anterior permanece disponível em `/resume`. Passe um nome para rotular a conversa anterior no seletor `/resume`. Para liberar contexto enquanto continua a mesma conversa, use `/compact` em vez disso. Aliases: `/reset`, `/new` |

50| `/color [color\|default]` | Definir a cor da barra de prompt para a sessão atual. Cores disponíveis: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. Use `default` para redefinir, ou execute sem argumento para escolher uma cor aleatória. Quando [Remote Control](/pt/remote-control) está conectado, a cor sincroniza com claude.ai/code |50| `/color [color\|default]` | Definir a cor da barra de prompt para a sessão atual. Cores disponíveis: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. Use `default` para redefinir, ou execute sem argumento para escolher uma cor aleatória. Quando [Remote Control](/pt/remote-control) está conectado, a cor sincroniza com claude.ai/code |

51| `/compact [instructions]` | Liberar contexto resumindo a conversa até agora. Opcionalmente, passe instruções de foco para o resumo. Consulte [como a compactação lida com regras, skills e arquivos de memória](/pt/context-window#what-survives-compaction) |51| `/compact [instructions]` | Liberar contexto resumindo a conversa até agora. Opcionalmente, passe instruções de foco para o resumo. Consulte [como a compactação lida com regras, skills e arquivos de memória](/pt/context-window#what-survives-compaction) |

52| `/config` | Abrir a interface de [Configurações](/pt/settings) para ajustar tema, modelo, [estilo de saída](/pt/output-styles) e outras preferências. Alias: `/settings` |52| `/config` | Abrir a interface de [Configurações](/pt/settings) para ajustar tema, modelo, [estilo de saída](/pt/output-styles) e outras preferências. Alias: `/settings` |

53| `/context` | Visualizar o uso atual de contexto como uma grade colorida. Mostra sugestões de otimização para ferramentas pesadas em contexto, inchaço de memória e avisos de capacidade |53| `/context [all]` | Visualizar o uso atual de contexto como uma grade colorida. Mostra sugestões de otimização para ferramentas pesadas em contexto, inchaço de memória e avisos de capacidade. No [modo tela cheia](/pt/fullscreen), o detalhamento por item é recolhido para manter a grade visível. Passe `all` para expandi-lo |

54| `/copy [N]` | Copiar a última resposta do assistente para a área de transferência. Passe um número `N` para copiar a N-ésima resposta mais recente: `/copy 2` copia a segunda mais recente. Quando há blocos de código, mostra um seletor interativo para selecionar blocos individuais ou a resposta completa. Pressione `w` no seletor para escrever a seleção em um arquivo em vez da área de transferência, o que é útil via SSH |54| `/copy [N]` | Copiar a última resposta do assistente para a área de transferência. Passe um número `N` para copiar a N-ésima resposta mais recente: `/copy 2` copia a segunda mais recente. Quando há blocos de código, mostra um seletor interativo para selecionar blocos individuais ou a resposta completa. Pressione `w` no seletor para escrever a seleção em um arquivo em vez da área de transferência, o que é útil via SSH |

55| `/cost` | Alias para `/usage` |55| `/cost` | Alias para `/usage` |

56| `/debug [description]` | **[Skill](/pt/skills#bundled-skills).** Ativar registro de depuração para a sessão atual e solucionar problemas lendo o log de depuração da sessão. O registro de depuração está desativado por padrão, a menos que você tenha iniciado com `claude --debug`, então executar `/debug` no meio da sessão começa a capturar logs a partir desse ponto. Opcionalmente, descreva o problema para focar a análise |56| `/debug [description]` | **[Skill](/pt/skills#bundled-skills).** Ativar registro de depuração para a sessão atual e solucionar problemas lendo o log de depuração da sessão. O registro de depuração está desativado por padrão, a menos que você tenha iniciado com `claude --debug`, então executar `/debug` no meio da sessão começa a capturar logs a partir desse ponto. Opcionalmente, descreva o problema para focar a análise |

88| `/powerup` | Descobrir recursos do Claude Code através de lições interativas rápidas com demos animadas |88| `/powerup` | Descobrir recursos do Claude Code através de lições interativas rápidas com demos animadas |

89| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}Removido na v2.1.91. Peça ao Claude diretamente para visualizar comentários de solicitação de pull. Em versões anteriores, busca e exibe comentários de uma solicitação de pull do GitHub; detecta automaticamente o PR para o branch atual, ou passe uma URL ou número de PR. Requer a CLI `gh` |89| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}Removido na v2.1.91. Peça ao Claude diretamente para visualizar comentários de solicitação de pull. Em versões anteriores, busca e exibe comentários de uma solicitação de pull do GitHub; detecta automaticamente o PR para o branch atual, ou passe uma URL ou número de PR. Requer a CLI `gh` |

90| `/privacy-settings` | Visualizar e atualizar suas configurações de privacidade. Disponível apenas para assinantes dos planos Pro e Max |90| `/privacy-settings` | Visualizar e atualizar suas configurações de privacidade. Disponível apenas para assinantes dos planos Pro e Max |

91| `/radio` | Abrir Claude FM lo-fi radio em seu navegador. Imprime a URL do stream quando nenhum navegador está disponível. Não disponível no Bedrock, Vertex ou Foundry |

91| `/recap` | Gerar um resumo de uma linha da sessão atual sob demanda. Consulte [Session recap](/pt/interactive-mode#session-recap) para o recap automático que aparece depois que você esteve ausente |92| `/recap` | Gerar um resumo de uma linha da sessão atual sob demanda. Consulte [Session recap](/pt/interactive-mode#session-recap) para o recap automático que aparece depois que você esteve ausente |

92| `/release-notes` | Visualizar o changelog em um seletor de versão interativo. Selecione uma versão específica para ver suas notas de lançamento, ou escolha mostrar todas as versões |93| `/release-notes` | Visualizar o changelog em um seletor de versão interativo. Selecione uma versão específica para ver suas notas de lançamento, ou escolha mostrar todas as versões |

93| `/reload-plugins` | Recarregar todos os [plugins](/pt/plugins) ativos para aplicar alterações pendentes sem reiniciar. Relata contagens para cada componente recarregado e sinaliza quaisquer erros de carregamento |94| `/reload-plugins` | Recarregar todos os [plugins](/pt/plugins) ativos para aplicar alterações pendentes sem reiniciar. Relata contagens para cada componente recarregado e sinaliza quaisquer erros de carregamento |

116| `CLAUDE_CODE_MAX_RETRIES` | Substitua o número de vezes para tentar novamente solicitações de API falhadas (padrão: 10) |116| `CLAUDE_CODE_MAX_RETRIES` | Substitua o número de vezes para tentar novamente solicitações de API falhadas (padrão: 10) |

117| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | Número máximo de ferramentas somente leitura e subagentes que podem executar em paralelo (padrão: 10). Valores mais altos aumentam o paralelismo mas consomem mais recursos |117| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | Número máximo de ferramentas somente leitura e subagentes que podem executar em paralelo (padrão: 10). Valores mais altos aumentam o paralelismo mas consomem mais recursos |