Referência do Agent SDK - TypeScript

Experimente a nova interface V2 (prévia): Uma interface simplificada com padrões send() e stream() agora está disponível, facilitando conversas multi-turno. Saiba mais sobre a prévia do TypeScript V2

Instalação

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

O SDK agrupa um binário nativo do Claude Code para sua plataforma como uma dependência opcional, como @anthropic-ai/claude-agent-sdk-darwin-arm64. Você não precisa instalar o Claude Code separadamente. Se seu gerenciador de pacotes pular dependências opcionais, o SDK lança Native CLI binary for <platform> not found; defina pathToClaudeCodeExecutable para um binário claude instalado separadamente.

Funções

`query()`

A função principal para interagir com o Claude Code. Cria um gerador assíncrono que transmite mensagens conforme chegam.

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

Parâmetros

Parâmetro	Tipo	Descrição
`prompt`	`string \| AsyncIterable<SDKUserMessage>`	O prompt de entrada como uma string ou iterável assíncrono para modo de transmissão
`options`	`Options`	Objeto de configuração opcional (veja o tipo Options abaixo)

Retorna

Retorna um objeto Query que estende AsyncGenerator<SDKMessage, void> com métodos adicionais.

`startup()`

Pré-aquece o subprocesso CLI gerando-o e completando o handshake de inicialização antes de um prompt estar disponível. O handle WarmQuery retornado aceita um prompt depois e o escreve em um processo já pronto, então a primeira chamada query() é resolvida sem pagar o custo de geração e inicialização do subprocesso inline.

function startup(params?: {
  options?: Options;
  initializeTimeoutMs?: number;
}): Promise<WarmQuery>;

Parâmetros

Parâmetro	Tipo	Descrição
`options`	`Options`	Objeto de configuração opcional. Igual ao parâmetro `options` para `query()`
`initializeTimeoutMs`	`number`	Tempo máximo em milissegundos para aguardar a inicialização do subprocesso. Padrão é `60000`. Se a inicialização não for concluída no tempo, a promise é rejeitada com um erro de timeout

Retorna

Retorna uma Promise<WarmQuery> que é resolvida assim que o subprocesso é gerado e completa seu handshake de inicialização.

Exemplo

Chame startup() cedo, por exemplo no boot da aplicação, depois chame .query() no handle retornado assim que um prompt estiver pronto. Isso move a geração do subprocesso e inicialização para fora do caminho crítico.

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

// Pague o custo de inicialização antecipadamente
const warm = await startup({ options: { maxTurns: 3 } });

// Depois, quando um prompt estiver pronto, isso é imediato
for await (const message of warm.query("What files are here?")) {
  console.log(message);
}

`tool()`

Cria uma definição de ferramenta MCP type-safe para uso com servidores MCP do SDK.

function tool<Schema extends AnyZodRawShape>(
  name: string,
  description: string,
  inputSchema: Schema,
  handler: (args: InferShape<Schema>, extra: unknown) => Promise<CallToolResult>,
  extras?: { annotations?: ToolAnnotations }
): SdkMcpToolDefinition<Schema>;

Parâmetros

Parâmetro	Tipo	Descrição
`name`	`string`	O nome da ferramenta
`description`	`string`	Uma descrição do que a ferramenta faz
`inputSchema`	`Schema extends AnyZodRawShape`	Schema Zod definindo os parâmetros de entrada da ferramenta (suporta Zod 3 e Zod 4)
`handler`	`(args, extra) => Promise<CallToolResult>`	Função assíncrona que executa a lógica da ferramenta
`extras`	`{ annotations?:` `ToolAnnotations` `}`	Anotações MCP opcionais da ferramenta fornecendo dicas comportamentais aos clientes

`ToolAnnotations`

Re-exportado de @modelcontextprotocol/sdk/types.js. Todos os campos são dicas opcionais; os clientes não devem confiar neles para decisões de segurança.

Campo	Tipo	Padrão	Descrição
`title`	`string`	`undefined`	Título legível para a ferramenta
`readOnlyHint`	`boolean`	`false`	Se `true`, a ferramenta não modifica seu ambiente
`destructiveHint`	`boolean`	`true`	Se `true`, a ferramenta pode realizar atualizações destrutivas (apenas significativo quando `readOnlyHint` é `false`)
`idempotentHint`	`boolean`	`false`	Se `true`, chamadas repetidas com os mesmos argumentos não têm efeito adicional (apenas significativo quando `readOnlyHint` é `false`)
`openWorldHint`	`boolean`	`true`	Se `true`, a ferramenta interage com entidades externas (por exemplo, busca na web). Se `false`, o domínio da ferramenta é fechado (por exemplo, uma ferramenta de memória)

import { tool } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const searchTool = tool(
  "search",
  "Search the web",
  { query: z.string() },
  async ({ query }) => {
    return { content: [{ type: "text", text: `Results for: ${query}` }] };
  },
  { annotations: { readOnlyHint: true, openWorldHint: true } }
);

`createSdkMcpServer()`

Cria uma instância de servidor MCP que é executada no mesmo processo que sua aplicação.

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

Parâmetros

Parâmetro	Tipo	Descrição
`options.name`	`string`	O nome do servidor MCP
`options.version`	`string`	String de versão opcional
`options.tools`	`Array<SdkMcpToolDefinition>`	Array de definições de ferramentas criadas com `tool()`

`listSessions()`

Descobre e lista sessões passadas com metadados leves. Filtre por diretório de projeto ou liste sessões em todos os projetos.

function listSessions(options?: ListSessionsOptions): Promise<SDKSessionInfo[]>;

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`options.dir`	`string`	`undefined`	Diretório para listar sessões. Quando omitido, retorna sessões em todos os projetos
`options.limit`	`number`	`undefined`	Número máximo de sessões a retornar
`options.includeWorktrees`	`boolean`	`true`	Quando `dir` está dentro de um repositório git, inclua sessões de todos os caminhos de worktree

Tipo de retorno: `SDKSessionInfo`

Propriedade	Tipo	Descrição
`sessionId`	`string`	Identificador único de sessão (UUID)
`summary`	`string`	Título de exibição: título personalizado, resumo gerado automaticamente ou primeiro prompt
`lastModified`	`number`	Tempo da última modificação em milissegundos desde a época
`fileSize`	`number \| undefined`	Tamanho do arquivo de sessão em bytes. Apenas preenchido para armazenamento JSONL local
`customTitle`	`string \| undefined`	Título de sessão definido pelo usuário (via `/rename`)
`firstPrompt`	`string \| undefined`	Primeiro prompt de usuário significativo na sessão
`gitBranch`	`string \| undefined`	Branch git no final da sessão
`cwd`	`string \| undefined`	Diretório de trabalho para a sessão
`tag`	`string \| undefined`	Tag de sessão definida pelo usuário (veja `tagSession()`)
`createdAt`	`number \| undefined`	Tempo de criação em milissegundos desde a época, do timestamp da primeira entrada

Exemplo

Imprima as 10 sessões mais recentes para um projeto. Os resultados são classificados por lastModified descendente, então o primeiro item é o mais novo. Omita dir para pesquisar em todos os projetos.

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

const sessions = await listSessions({ dir: "/path/to/project", limit: 10 });

for (const session of sessions) {
  console.log(`${session.summary} (${session.sessionId})`);
}

`getSessionMessages()`

Lê mensagens de usuário e assistente de uma transcrição de sessão passada.

function getSessionMessages(
  sessionId: string,
  options?: GetSessionMessagesOptions
): Promise<SessionMessage[]>;

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`sessionId`	`string`	obrigatório	UUID da sessão a ler (veja `listSessions()`)
`options.dir`	`string`	`undefined`	Diretório do projeto para encontrar a sessão. Quando omitido, pesquisa todos os projetos
`options.limit`	`number`	`undefined`	Número máximo de mensagens a retornar
`options.offset`	`number`	`undefined`	Número de mensagens a pular do início

Tipo de retorno: `SessionMessage`

Propriedade	Tipo	Descrição
`type`	`"user" \| "assistant"`	Papel da mensagem
`uuid`	`string`	Identificador único de mensagem
`session_id`	`string`	Sessão a que esta mensagem pertence
`message`	`unknown`	Payload de mensagem bruta da transcrição
`parent_tool_use_id`	`null`	Reservado

Exemplo

import { listSessions, getSessionMessages } from "@anthropic-ai/claude-agent-sdk";

const [latest] = await listSessions({ dir: "/path/to/project", limit: 1 });

if (latest) {
  const messages = await getSessionMessages(latest.sessionId, {
    dir: "/path/to/project",
    limit: 20
  });

  for (const msg of messages) {
    console.log(`[${msg.type}] ${msg.uuid}`);
  }
}

`getSessionInfo()`

Lê metadados para uma única sessão por ID sem verificar o diretório do projeto completo.

function getSessionInfo(
  sessionId: string,
  options?: GetSessionInfoOptions
): Promise<SDKSessionInfo | undefined>;

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`sessionId`	`string`	obrigatório	UUID da sessão a procurar
`options.dir`	`string`	`undefined`	Caminho do diretório do projeto. Quando omitido, pesquisa todos os diretórios de projeto

Retorna SDKSessionInfo, ou undefined se a sessão não for encontrada.

`renameSession()`

Renomeia uma sessão anexando uma entrada de título personalizado. Chamadas repetidas são seguras; o título mais recente vence.

function renameSession(
  sessionId: string,
  title: string,
  options?: SessionMutationOptions
): Promise<void>;

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`sessionId`	`string`	obrigatório	UUID da sessão a renomear
`title`	`string`	obrigatório	Novo título. Deve ser não-vazio após aparar espaços em branco
`options.dir`	`string`	`undefined`	Caminho do diretório do projeto. Quando omitido, pesquisa todos os diretórios de projeto

`tagSession()`

Marca uma sessão. Passe null para limpar a tag. Chamadas repetidas são seguras; a tag mais recente vence.

function tagSession(
  sessionId: string,
  tag: string | null,
  options?: SessionMutationOptions
): Promise<void>;

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`sessionId`	`string`	obrigatório	UUID da sessão a marcar
`tag`	`string \| null`	obrigatório	String de tag, ou `null` para limpar
`options.dir`	`string`	`undefined`	Caminho do diretório do projeto. Quando omitido, pesquisa todos os diretórios de projeto

Tipos

`Options`

Objeto de configuração para a função query().

Propriedade	Tipo	Padrão	Descrição
`abortController`	`AbortController`	`new AbortController()`	Controlador para cancelar operações
`additionalDirectories`	`string[]`	`[]`	Diretórios adicionais que Claude pode acessar
`agent`	`string`	`undefined`	Nome do agente para a thread principal. O agente deve ser definido na opção `agents` ou em configurações
`agents`	`Record<string, [`AgentDefinition`](#agent-definition)>`	`undefined`	Defina subagentes programaticamente
`allowDangerouslySkipPermissions`	`boolean`	`false`	Ativar bypass de permissões. Obrigatório ao usar `permissionMode: 'bypassPermissions'`
`allowedTools`	`string[]`	`[]`	Ferramentas para auto-aprovar sem solicitar. Isso não restringe Claude apenas a essas ferramentas; ferramentas não listadas caem em `permissionMode` e `canUseTool`. Use `disallowedTools` para bloquear ferramentas. Veja Permissões
`betas`	`SdkBeta[]`	`[]`	Ativar recursos beta
`canUseTool`	`CanUseTool`	`undefined`	Função de permissão personalizada para uso de ferramentas
`continue`	`boolean`	`false`	Continuar a conversa mais recente
`cwd`	`string`	`process.cwd()`	Diretório de trabalho atual
`debug`	`boolean`	`false`	Ativar modo de depuração para o processo Claude Code
`debugFile`	`string`	`undefined`	Escrever logs de depuração em um caminho de arquivo específico. Ativa implicitamente o modo de depuração
`disallowedTools`	`string[]`	`[]`	Ferramentas para sempre negar. Regras de negação são verificadas primeiro e substituem `allowedTools` e `permissionMode` (incluindo `bypassPermissions`)
`effort`	`'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'`	`'high'`	Controla quanto esforço Claude coloca em sua resposta. Funciona com pensamento adaptativo para guiar a profundidade do pensamento
`enableFileCheckpointing`	`boolean`	`false`	Ativar rastreamento de mudanças de arquivo para retrocesso. Veja File checkpointing
`env`	`Record<string, string \| undefined>`	`process.env`	Variáveis de ambiente. Defina `CLAUDE_AGENT_SDK_CLIENT_APP` para identificar sua aplicação no cabeçalho User-Agent
`executable`	`'bun' \| 'deno' \| 'node'`	Auto-detectado	Runtime JavaScript a usar
`executableArgs`	`string[]`	`[]`	Argumentos a passar para o executável
`extraArgs`	`Record<string, string \| null>`	`{}`	Argumentos adicionais
`fallbackModel`	`string`	`undefined`	Modelo a usar se o primário falhar
`forkSession`	`boolean`	`false`	Ao retomar com `resume`, bifurcar para um novo ID de sessão em vez de continuar a sessão original
`hooks`	`Partial<Record<HookEvent,` `HookCallbackMatcher[]>>`	`{}`	Callbacks de hook para eventos
`includePartialMessages`	`boolean`	`false`	Incluir eventos de mensagem parcial
`maxBudgetUsd`	`number`	`undefined`	Parar a consulta quando a estimativa de custo do lado do cliente atingir este valor em USD. Comparado com a mesma estimativa que `total_cost_usd`; veja Track cost and usage para ressalvas de precisão
`maxThinkingTokens`	`number`	`undefined`	Descontinuado: Use `thinking` em vez disso. Tokens máximos para processo de pensamento
`maxTurns`	`number`	`undefined`	Turnos agênticos máximos (round trips de uso de ferramenta)
`mcpServers`	`Record<string, [`McpServerConfig`](#mcp-server-config)>`	`{}`	Configurações de servidor MCP
`model`	`string`	Padrão da CLI	Modelo Claude a usar
`outputFormat`	`{ type: 'json_schema', schema: JSONSchema }`	`undefined`	Defina o formato de saída para resultados de agente. Veja Structured outputs para detalhes
`pathToClaudeCodeExecutable`	`string`	Auto-resolvido do binário nativo agrupado	Caminho para executável Claude Code. Apenas necessário se dependências opcionais foram puladas durante a instalação ou sua plataforma não está no conjunto suportado
`permissionMode`	`PermissionMode`	`'default'`	Modo de permissão para a sessão
`permissionPromptToolName`	`string`	`undefined`	Nome da ferramenta MCP para prompts de permissão
`persistSession`	`boolean`	`true`	Quando `false`, desativa persistência de sessão em disco. Sessões não podem ser retomadas depois
`plugins`	`SdkPluginConfig[]`	`[]`	Carregar plugins personalizados de caminhos locais. Veja Plugins para detalhes
`promptSuggestions`	`boolean`	`false`	Ativar sugestões de prompt. Emite uma mensagem `prompt_suggestion` após cada turno com um prompt de usuário previsto
`resume`	`string`	`undefined`	ID de sessão a retomar
`resumeSessionAt`	`string`	`undefined`	Retomar sessão em um UUID de mensagem específico
`sandbox`	`SandboxSettings`	`undefined`	Configurar comportamento de sandbox programaticamente. Veja Sandbox settings para detalhes
`sessionId`	`string`	Auto-gerado	Use um UUID específico para a sessão em vez de auto-gerar um
`settingSources`	`SettingSource[]`	Padrões da CLI (todas as fontes)	Controle quais configurações do sistema de arquivos carregar. Passe `[]` para desativar configurações de usuário, projeto e local. Configurações de política gerenciada carregam independentemente. Veja Use Claude Code features
`spawnClaudeCodeProcess`	`(options: SpawnOptions) => SpawnedProcess`	`undefined`	Função personalizada para gerar o processo Claude Code. Use para executar Claude Code em VMs, contêineres ou ambientes remotos
`stderr`	`(data: string) => void`	`undefined`	Callback para saída stderr
`strictMcpConfig`	`boolean`	`false`	Aplicar validação MCP rigorosa
`systemPrompt`	`string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }`	`undefined` (prompt mínimo)	Configuração de prompt do sistema. Passe uma string para prompt personalizado, ou `{ type: 'preset', preset: 'claude_code' }` para usar o prompt do sistema do Claude Code. Ao usar a forma de objeto preset, adicione `append` para estendê-lo com instruções adicionais, e defina `excludeDynamicSections: true` para mover contexto por sessão para a primeira mensagem do usuário para melhor reutilização de cache de prompt entre máquinas
`thinking`	`ThinkingConfig`	`{ type: 'adaptive' }` para modelos suportados	Controla o comportamento de pensamento/raciocínio do Claude. Veja `ThinkingConfig` para opções
`toolConfig`	`ToolConfig`	`undefined`	Configuração para comportamento de ferramenta integrada. Veja `ToolConfig` para detalhes
`tools`	`string[] \| { type: 'preset'; preset: 'claude_code' }`	`undefined`	Configuração de ferramenta. Passe um array de nomes de ferramentas ou use o preset para obter as ferramentas padrão do Claude Code

Objeto `Query`

Interface retornada pela função query().

interface Query extends AsyncGenerator<SDKMessage, void> {
  interrupt(): Promise<void>;
  rewindFiles(
    userMessageId: string,
    options?: { dryRun?: boolean }
  ): Promise<RewindFilesResult>;
  setPermissionMode(mode: PermissionMode): Promise<void>;
  setModel(model?: string): Promise<void>;
  setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;
  initializationResult(): Promise<SDKControlInitializeResponse>;
  supportedCommands(): Promise<SlashCommand[]>;
  supportedModels(): Promise<ModelInfo[]>;
  supportedAgents(): Promise<AgentInfo[]>;
  mcpServerStatus(): Promise<McpServerStatus[]>;
  accountInfo(): Promise<AccountInfo>;
  reconnectMcpServer(serverName: string): Promise<void>;
  toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;
  setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;
  streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;
  stopTask(taskId: string): Promise<void>;
  close(): void;
}

Métodos

Método	Descrição
`interrupt()`	Interrompe a consulta (apenas disponível em modo de entrada de transmissão)
`rewindFiles(userMessageId, options?)`	Restaura arquivos para seu estado na mensagem de usuário especificada. Passe `{ dryRun: true }` para visualizar mudanças. Requer `enableFileCheckpointing: true`. Veja File checkpointing
`setPermissionMode()`	Altera o modo de permissão (apenas disponível em modo de entrada de transmissão)
`setModel()`	Altera o modelo (apenas disponível em modo de entrada de transmissão)
`setMaxThinkingTokens()`	Descontinuado: Use a opção `thinking` em vez disso. Altera os tokens de pensamento máximos
`initializationResult()`	Retorna o resultado de inicialização completo incluindo comandos suportados, modelos, informações de conta e configuração de estilo de saída
`supportedCommands()`	Retorna comandos slash disponíveis
`supportedModels()`	Retorna modelos disponíveis com informações de exibição
`supportedAgents()`	Retorna subagentes disponíveis como `AgentInfo[]`
`mcpServerStatus()`	Retorna status de servidores MCP conectados
`accountInfo()`	Retorna informações de conta
`reconnectMcpServer(serverName)`	Reconectar um servidor MCP por nome
`toggleMcpServer(serverName, enabled)`	Ativar ou desativar um servidor MCP por nome
`setMcpServers(servers)`	Substituir dinamicamente o conjunto de servidores MCP para esta sessão. Retorna informações sobre quais servidores foram adicionados, removidos e quaisquer erros
`streamInput(stream)`	Transmitir mensagens de entrada para a consulta para conversas multi-turno
`stopTask(taskId)`	Parar uma tarefa de fundo em execução por ID
`close()`	Fechar a consulta e encerrar o processo subjacente. Força o término da consulta e limpa todos os recursos

`WarmQuery`

Handle retornado por startup(). O subprocesso já está gerado e inicializado, então chamar query() neste handle escreve o prompt diretamente em um processo pronto sem latência de inicialização.

interface WarmQuery extends AsyncDisposable {
  query(prompt: string | AsyncIterable<SDKUserMessage>): Query;
  close(): void;
}

Métodos

Método	Descrição
`query(prompt)`	Enviar um prompt para o subprocesso pré-aquecido e retornar uma `Query`. Pode ser chamado apenas uma vez por `WarmQuery`
`close()`	Fechar o subprocesso sem enviar um prompt. Use isso para descartar uma consulta quente que não é mais necessária

WarmQuery implementa AsyncDisposable, então pode ser usado com await using para limpeza automática.

`SDKControlInitializeResponse`

Tipo de retorno de initializationResult(). Contém dados de inicialização de sessão.

type SDKControlInitializeResponse = {
  commands: SlashCommand[];
  agents: AgentInfo[];
  output_style: string;
  available_output_styles: string[];
  models: ModelInfo[];
  account: AccountInfo;
  fast_mode_state?: "off" | "cooldown" | "on";
};

`AgentDefinition`

Configuração para um subagente definido programaticamente.

type AgentDefinition = {
  description: string;
  tools?: string[];
  disallowedTools?: string[];
  prompt: string;
  model?: "sonnet" | "opus" | "haiku" | "inherit";
  mcpServers?: AgentMcpServerSpec[];
  skills?: string[];
  maxTurns?: number;
  criticalSystemReminder_EXPERIMENTAL?: string;
};

Campo	Obrigatório	Descrição
`description`	Sim	Descrição em linguagem natural de quando usar este agente
`tools`	Não	Array de nomes de ferramentas permitidas. Se omitido, herda todas as ferramentas do pai
`disallowedTools`	Não	Array de nomes de ferramentas para explicitamente desallocar para este agente
`prompt`	Sim	O prompt do sistema do agente
`model`	Não	Substituição de modelo para este agente. Se omitido ou `'inherit'`, usa o modelo principal
`mcpServers`	Não	Especificações de servidor MCP para este agente
`skills`	Não	Array de nomes de skills para pré-carregar no contexto do agente
`maxTurns`	Não	Número máximo de turnos agênticos (round-trips de API) antes de parar
`criticalSystemReminder_EXPERIMENTAL`	Não	Experimental: Lembrete crítico adicionado ao prompt do sistema

`AgentMcpServerSpec`

Especifica servidores MCP disponíveis para um subagente. Pode ser um nome de servidor (string referenciando um servidor da configuração mcpServers do pai) ou um registro de configuração de servidor inline mapeando nomes de servidor para configs.

type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;

Onde McpServerConfigForProcessTransport é McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig.

`SettingSource`

Controla quais fontes de configuração baseadas em sistema de arquivos o SDK carrega configurações.

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

Valor	Descrição	Localização
`'user'`	Configurações globais do usuário	`~/.claude/settings.json`
`'project'`	Configurações de projeto compartilhadas (controladas por versão)	`.claude/settings.json`
`'local'`	Configurações de projeto local (gitignored)	`.claude/settings.local.json`

Comportamento padrão

Quando settingSources é omitido ou undefined, query() carrega as mesmas configurações do sistema de arquivos que a CLI do Claude Code: usuário, projeto e local. Configurações de política gerenciada são carregadas em todos os casos. Veja What settingSources does not control para entradas que são lidas independentemente desta opção, e como desativá-las.

Por que usar settingSources

Desativar configurações do sistema de arquivos:

// Não carregar configurações de usuário, projeto ou local do disco
const result = query({
  prompt: "Analyze this code",
  options: { settingSources: [] }
});

Carregar todas as configurações do sistema de arquivos explicitamente:

const result = query({
  prompt: "Analyze this code",
  options: {
    settingSources: ["user", "project", "local"] // Carregar todas as configurações
  }
});

Carregar apenas fontes de configuração específicas:

// Carregar apenas configurações de projeto, ignorar usuário e local
const result = query({
  prompt: "Run CI checks",
  options: {
    settingSources: ["project"] // Apenas .claude/settings.json
  }
});

Ambientes de teste e CI:

// Garantir comportamento consistente em CI excluindo configurações locais
const result = query({
  prompt: "Run tests",
  options: {
    settingSources: ["project"], // Apenas configurações compartilhadas da equipe
    permissionMode: "bypassPermissions"
  }
});

Aplicações apenas SDK:

// Defina tudo programaticamente.
// Passe [] para optar por não usar fontes de configuração do sistema de arquivos.
const result = query({
  prompt: "Review this PR",
  options: {
    settingSources: [],
    agents: {
      /* ... */
    },
    mcpServers: {
      /* ... */
    },
    allowedTools: ["Read", "Grep", "Glob"]
  }
});

Carregando instruções de projeto CLAUDE.md:

// Carregar configurações de projeto para incluir arquivos CLAUDE.md
const result = query({
  prompt: "Add a new feature following project conventions",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code" // Usar o prompt do sistema do Claude Code
    },
    settingSources: ["project"], // Carrega CLAUDE.md do diretório do projeto
    allowedTools: ["Read", "Write", "Edit"]
  }
});

Precedência de configurações

Quando múltiplas fontes são carregadas, as configurações são mescladas com esta precedência (maior para menor):

Configurações locais (.claude/settings.local.json)
Configurações de projeto (.claude/settings.json)
Configurações do usuário (~/.claude/settings.json)

Opções programáticas como agents e allowedTools substituem configurações do sistema de arquivos de usuário, projeto e local. Configurações de política gerenciada têm precedência sobre opções programáticas.

`PermissionMode`

type PermissionMode =
  | "default" // Comportamento de permissão padrão
  | "acceptEdits" // Auto-aceitar edições de arquivo
  | "bypassPermissions" // Bypass de todas as verificações de permissão
  | "plan" // Modo de planejamento - sem execução
  | "dontAsk" // Não solicitar permissões, negar se não pré-aprovado
  | "auto"; // Usar um classificador de modelo para aprovar ou negar cada chamada de ferramenta

`CanUseTool`

Tipo de função de permissão personalizada para controlar o uso de ferramentas.

type CanUseTool = (
  toolName: string,
  input: Record<string, unknown>,
  options: {
    signal: AbortSignal;
    suggestions?: PermissionUpdate[];
    blockedPath?: string;
    decisionReason?: string;
    toolUseID: string;
    agentID?: string;
  }
) => Promise<PermissionResult>;

Opção	Tipo	Descrição
`signal`	`AbortSignal`	Sinalizado se a operação deve ser abortada
`suggestions`	`PermissionUpdate[]`	Atualizações de permissão sugeridas para que o usuário não seja solicitado novamente para esta ferramenta
`blockedPath`	`string`	O caminho do arquivo que acionou a solicitação de permissão, se aplicável
`decisionReason`	`string`	Explica por que esta solicitação de permissão foi acionada
`toolUseID`	`string`	Identificador único para esta chamada de ferramenta específica dentro da mensagem do assistente
`agentID`	`string`	Se executando dentro de um sub-agente, o ID do sub-agente

`PermissionResult`

Resultado de uma verificação de permissão.

type PermissionResult =
  | {
      behavior: "allow";
      updatedInput?: Record<string, unknown>;
      updatedPermissions?: PermissionUpdate[];
      toolUseID?: string;
    }
  | {
      behavior: "deny";
      message: string;
      interrupt?: boolean;
      toolUseID?: string;
    };

`ToolConfig`

Configuração para comportamento de ferramenta integrada.

type ToolConfig = {
  askUserQuestion?: {
    previewFormat?: "markdown" | "html";
  };
};

Campo	Tipo	Descrição
`askUserQuestion.previewFormat`	`'markdown' \| 'html'`	Opta pelo campo `preview` em opções `AskUserQuestion` e define seu formato de conteúdo. Quando não definido, Claude não emite visualizações

`McpServerConfig`

Configuração para servidores MCP.

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

`McpStdioServerConfig`

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

`McpSSEServerConfig`

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

`McpHttpServerConfig`

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

`McpSdkServerConfigWithInstance`

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

`McpClaudeAIProxyServerConfig`

type McpClaudeAIProxyServerConfig = {
  type: "claudeai-proxy";
  url: string;
  id: string;
};

`SdkPluginConfig`

Configuração para carregar plugins no SDK.

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

Campo	Tipo	Descrição
`type`	`'local'`	Deve ser `'local'` (apenas plugins locais atualmente suportados)
`path`	`string`	Caminho absoluto ou relativo para o diretório do plugin

Exemplo:

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

Para informações completas sobre criação e uso de plugins, veja Plugins.

Tipos de Mensagem

`SDKMessage`

Tipo de união de todas as mensagens possíveis retornadas pela consulta.

type SDKMessage =
  | SDKAssistantMessage
  | SDKUserMessage
  | SDKUserMessageReplay
  | SDKResultMessage
  | SDKSystemMessage
  | SDKPartialAssistantMessage
  | SDKCompactBoundaryMessage
  | SDKStatusMessage
  | SDKLocalCommandOutputMessage
  | SDKHookStartedMessage
  | SDKHookProgressMessage
  | SDKHookResponseMessage
  | SDKPluginInstallMessage
  | SDKToolProgressMessage
  | SDKAuthStatusMessage
  | SDKTaskNotificationMessage
  | SDKTaskStartedMessage
  | SDKTaskProgressMessage
  | SDKFilesPersistedEvent
  | SDKToolUseSummaryMessage
  | SDKRateLimitEvent
  | SDKPromptSuggestionMessage;

`SDKAssistantMessage`

Mensagem de resposta do assistente.

type SDKAssistantMessage = {
  type: "assistant";
  uuid: UUID;
  session_id: string;
  message: BetaMessage; // Do SDK Anthropic
  parent_tool_use_id: string | null;
  error?: SDKAssistantMessageError;
};

O campo message é uma BetaMessage do SDK Anthropic. Inclui campos como id, content, model, stop_reason e usage. SDKAssistantMessageError é um de: 'authentication_failed', 'billing_error', 'rate_limit', 'invalid_request', 'server_error', 'max_output_tokens', ou 'unknown'.

`SDKUserMessage`

Mensagem de entrada do usuário.

type SDKUserMessage = {
  type: "user";
  uuid?: UUID;
  session_id: string;
  message: MessageParam; // Do SDK Anthropic
  parent_tool_use_id: string | null;
  isSynthetic?: boolean;
  shouldQuery?: boolean;
  tool_use_result?: unknown;
};

Defina shouldQuery como false para anexar a mensagem à transcrição sem acionar um turno do assistente. A mensagem é mantida e mesclada na próxima mensagem do usuário que aciona um turno. Use isso para injetar contexto, como a saída de um comando que você executou fora de banda, sem gastar uma chamada de modelo nela.

`SDKUserMessageReplay`

Mensagem de usuário repetida com UUID obrigatório.

type SDKUserMessageReplay = {
  type: "user";
  uuid: UUID;
  session_id: string;
  message: MessageParam;
  parent_tool_use_id: string | null;
  isSynthetic?: boolean;
  tool_use_result?: unknown;
  isReplay: true;
};

`SDKResultMessage`

Mensagem de resultado final.

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

`SDKSystemMessage`

Mensagem de inicialização do sistema.

type SDKSystemMessage = {
  type: "system";
  subtype: "init";
  uuid: UUID;
  session_id: string;
  agents?: string[];
  apiKeySource: ApiKeySource;
  betas?: string[];
  claude_code_version: string;
  cwd: string;
  tools: string[];
  mcp_servers: {
    name: string;
    status: string;
  }[];
  model: string;
  permissionMode: PermissionMode;
  slash_commands: string[];
  output_style: string;
  skills: string[];
  plugins: { name: string; path: string }[];
};

`SDKPartialAssistantMessage`

Mensagem parcial de transmissão (apenas quando includePartialMessages é true).

type SDKPartialAssistantMessage = {
  type: "stream_event";
  event: BetaRawMessageStreamEvent; // Do SDK Anthropic
  parent_tool_use_id: string | null;
  uuid: UUID;
  session_id: string;
};

`SDKCompactBoundaryMessage`

Mensagem indicando um limite de compactação de conversa.

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

`SDKPluginInstallMessage`

Evento de progresso de instalação de plugin. Emitido quando CLAUDE_CODE_SYNC_PLUGIN_INSTALL está definido, para que sua aplicação Agent SDK possa rastrear a instalação de plugin do marketplace antes do primeiro turno. Os status started e completed delimitam a instalação geral. Os status installed e failed relatam marketplaces individuais e incluem name.

type SDKPluginInstallMessage = {
  type: "system";
  subtype: "plugin_install";
  status: "started" | "installed" | "failed" | "completed";
  name?: string;
  error?: string;
  uuid: UUID;
  session_id: string;
};

`SDKPermissionDenial`

Informações sobre um uso de ferramenta negado.

type SDKPermissionDenial = {
  tool_name: string;
  tool_use_id: string;
  tool_input: Record<string, unknown>;
};

Tipos de Hook

Para um guia abrangente sobre o uso de hooks com exemplos e padrões comuns, veja o guia de Hooks.

`HookEvent`

Eventos de hook disponíveis.

type HookEvent =
  | "PreToolUse"
  | "PostToolUse"
  | "PostToolUseFailure"
  | "Notification"
  | "UserPromptSubmit"
  | "SessionStart"
  | "SessionEnd"
  | "Stop"
  | "SubagentStart"
  | "SubagentStop"
  | "PreCompact"
  | "PermissionRequest"
  | "Setup"
  | "TeammateIdle"
  | "TaskCompleted"
  | "ConfigChange"
  | "WorktreeCreate"
  | "WorktreeRemove";

`HookCallback`

Tipo de função de callback de hook.

type HookCallback = (
  input: HookInput, // União de todos os tipos de entrada de hook
  toolUseID: string | undefined,
  options: { signal: AbortSignal }
) => Promise<HookJSONOutput>;

`HookCallbackMatcher`

Configuração de hook com matcher opcional.

interface HookCallbackMatcher {
  matcher?: string;
  hooks: HookCallback[];
  timeout?: number; // Timeout em segundos para todos os hooks neste matcher
}

`HookInput`

Tipo de união de todos os tipos de entrada de hook.

type HookInput =
  | PreToolUseHookInput
  | PostToolUseHookInput
  | PostToolUseFailureHookInput
  | NotificationHookInput
  | UserPromptSubmitHookInput
  | SessionStartHookInput
  | SessionEndHookInput
  | StopHookInput
  | SubagentStartHookInput
  | SubagentStopHookInput
  | PreCompactHookInput
  | PermissionRequestHookInput
  | SetupHookInput
  | TeammateIdleHookInput
  | TaskCompletedHookInput
  | ConfigChangeHookInput
  | WorktreeCreateHookInput
  | WorktreeRemoveHookInput;

`BaseHookInput`

Interface base que todos os tipos de entrada de hook estendem.

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

`PreToolUseHookInput`

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

`PostToolUseHookInput`

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

`PostToolUseFailureHookInput`

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

`NotificationHookInput`

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

`UserPromptSubmitHookInput`

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

`SessionStartHookInput`

type SessionStartHookInput = BaseHookInput & {
  hook_event_name: "SessionStart";
  source: "startup" | "resume" | "clear" | "compact";
  agent_type?: string;
  model?: string;
};

`SessionEndHookInput`

type SessionEndHookInput = BaseHookInput & {
  hook_event_name: "SessionEnd";
  reason: ExitReason; // String do array EXIT_REASONS
};

`StopHookInput`

type StopHookInput = BaseHookInput & {
  hook_event_name: "Stop";
  stop_hook_active: boolean;
  last_assistant_message?: string;
};

`SubagentStartHookInput`

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

`SubagentStopHookInput`

type SubagentStopHookInput = BaseHookInput & {
  hook_event_name: "SubagentStop";
  stop_hook_active: boolean;
  agent_id: string;
  agent_transcript_path: string;
  agent_type: string;
  last_assistant_message?: string;
};

`PreCompactHookInput`

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

`PermissionRequestHookInput`

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

`SetupHookInput`

type SetupHookInput = BaseHookInput & {
  hook_event_name: "Setup";
  trigger: "init" | "maintenance";
};

`TeammateIdleHookInput`

type TeammateIdleHookInput = BaseHookInput & {
  hook_event_name: "TeammateIdle";
  teammate_name: string;
  team_name: string;
};

`TaskCompletedHookInput`

type TaskCompletedHookInput = BaseHookInput & {
  hook_event_name: "TaskCompleted";
  task_id: string;
  task_subject: string;
  task_description?: string;
  teammate_name?: string;
  team_name?: string;
};

`ConfigChangeHookInput`

type ConfigChangeHookInput = BaseHookInput & {
  hook_event_name: "ConfigChange";
  source:
    | "user_settings"
    | "project_settings"
    | "local_settings"
    | "policy_settings"
    | "skills";
  file_path?: string;
};

`WorktreeCreateHookInput`

type WorktreeCreateHookInput = BaseHookInput & {
  hook_event_name: "WorktreeCreate";
  name: string;
};

`WorktreeRemoveHookInput`

type WorktreeRemoveHookInput = BaseHookInput & {
  hook_event_name: "WorktreeRemove";
  worktree_path: string;
};

`HookJSONOutput`

Valor de retorno de hook.

type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput;

`AsyncHookJSONOutput`

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

`SyncHookJSONOutput`

type SyncHookJSONOutput = {
  continue?: boolean;
  suppressOutput?: boolean;
  stopReason?: string;
  decision?: "approve" | "block";
  systemMessage?: string;
  reason?: string;
  hookSpecificOutput?:
    | {
        hookEventName: "PreToolUse";
        permissionDecision?: "allow" | "deny" | "ask";
        permissionDecisionReason?: string;
        updatedInput?: Record<string, unknown>;
        additionalContext?: string;
      }
    | {
        hookEventName: "UserPromptSubmit";
        additionalContext?: string;
      }
    | {
        hookEventName: "SessionStart";
        additionalContext?: string;
      }
    | {
        hookEventName: "Setup";
        additionalContext?: string;
      }
    | {
        hookEventName: "SubagentStart";
        additionalContext?: string;
      }
    | {
        hookEventName: "PostToolUse";
        additionalContext?: string;
        updatedMCPToolOutput?: unknown;
      }
    | {
        hookEventName: "PostToolUseFailure";
        additionalContext?: string;
      }
    | {
        hookEventName: "Notification";
        additionalContext?: string;
      }
    | {
        hookEventName: "PermissionRequest";
        decision:
          | {
              behavior: "allow";
              updatedInput?: Record<string, unknown>;
              updatedPermissions?: PermissionUpdate[];
            }
          | {
              behavior: "deny";
              message?: string;
              interrupt?: boolean;
            };
      };
};

Tipos de Entrada de Ferramenta

Documentação de esquemas de entrada para todas as ferramentas integradas do Claude Code. Esses tipos são exportados de @anthropic-ai/claude-agent-sdk e podem ser usados para interações de ferramenta type-safe.

`ToolInputSchemas`

União de todos os tipos de entrada de ferramenta, exportada de @anthropic-ai/claude-agent-sdk.

type ToolInputSchemas =
  | AgentInput
  | AskUserQuestionInput
  | BashInput
  | TaskOutputInput
  | ConfigInput
  | EnterWorktreeInput
  | ExitPlanModeInput
  | FileEditInput
  | FileReadInput
  | FileWriteInput
  | GlobInput
  | GrepInput
  | ListMcpResourcesInput
  | McpInput
  | MonitorInput
  | NotebookEditInput
  | ReadMcpResourceInput
  | SubscribeMcpResourceInput
  | SubscribePollingInput
  | TaskStopInput
  | TodoWriteInput
  | UnsubscribeMcpResourceInput
  | UnsubscribePollingInput
  | WebFetchInput
  | WebSearchInput;

Agent

Nome da ferramenta: Agent (anteriormente Task, que ainda é aceito como alias)

type AgentInput = {
  description: string;
  prompt: string;
  subagent_type: string;
  model?: "sonnet" | "opus" | "haiku";
  resume?: string;
  run_in_background?: boolean;
  max_turns?: number;
  name?: string;
  team_name?: string;
  mode?: "acceptEdits" | "bypassPermissions" | "default" | "dontAsk" | "plan";
  isolation?: "worktree";
};

Lança um novo agente para lidar com tarefas complexas e multi-etapas autonomamente.

AskUserQuestion

Nome da ferramenta: AskUserQuestion

type AskUserQuestionInput = {
  questions: Array<{
    question: string;
    header: string;
    options: Array<{ label: string; description: string; preview?: string }>;
    multiSelect: boolean;
  }>;
};

Faz perguntas de esclarecimento ao usuário durante a execução. Veja Handle approvals and user input para detalhes de uso.

Bash

Nome da ferramenta: Bash

type BashInput = {
  command: string;
  timeout?: number;
  description?: string;
  run_in_background?: boolean;
  dangerouslyDisableSandbox?: boolean;
};

Executa comandos bash em uma sessão de shell persistente com timeout opcional e execução em background.

Monitor

Nome da ferramenta: Monitor

type MonitorInput = {
  command: string;
  description: string;
  timeout_ms?: number;
  persistent?: boolean;
};

Executa um script de background e entrega cada linha stdout para Claude como um evento para que possa reagir sem polling. Defina persistent: true para watches de comprimento de sessão, como tails de log. Monitor segue as mesmas regras de permissão que Bash. Veja a referência da ferramenta Monitor para comportamento e disponibilidade de provedor.

TaskOutput

Nome da ferramenta: TaskOutput

type TaskOutputInput = {
  task_id: string;
  block: boolean;
  timeout: number;
};

Recupera saída de uma tarefa de background em execução ou concluída.

Edit

Nome da ferramenta: Edit

type FileEditInput = {
  file_path: string;
  old_string: string;
  new_string: string;
  replace_all?: boolean;
};

Realiza substituições exatas de string em arquivos.

Read

Nome da ferramenta: Read

type FileReadInput = {
  file_path: string;
  offset?: number;
  limit?: number;
  pages?: string;
};

Lê arquivos do sistema de arquivos local, incluindo texto, imagens, PDFs e notebooks Jupyter. Use pages para intervalos de página PDF (por exemplo, "1-5").

Write

Nome da ferramenta: Write

type FileWriteInput = {
  file_path: string;
  content: string;
};

Escreve um arquivo no sistema de arquivos local, sobrescrevendo se existir.

Glob

Nome da ferramenta: Glob

type GlobInput = {
  pattern: string;
  path?: string;
};

Correspondência rápida de padrão de arquivo que funciona com qualquer tamanho de codebase.

Grep

Nome da ferramenta: Grep

type GrepInput = {
  pattern: string;
  path?: string;
  glob?: string;
  type?: string;
  output_mode?: "content" | "files_with_matches" | "count";
  "-i"?: boolean;
  "-n"?: boolean;
  "-B"?: number;
  "-A"?: number;
  "-C"?: number;
  context?: number;
  head_limit?: number;
  offset?: number;
  multiline?: boolean;
};

Ferramenta de busca poderosa construída em ripgrep com suporte a regex.

TaskStop

Nome da ferramenta: TaskStop

type TaskStopInput = {
  task_id?: string;
  shell_id?: string; // Descontinuado: use task_id
};

Para uma tarefa de background em execução ou shell por ID.

NotebookEdit

Nome da ferramenta: NotebookEdit

type NotebookEditInput = {
  notebook_path: string;
  cell_id?: string;
  new_source: string;
  cell_type?: "code" | "markdown";
  edit_mode?: "replace" | "insert" | "delete";
};

Edita células em arquivos de notebook Jupyter.

WebFetch

Nome da ferramenta: WebFetch

type WebFetchInput = {
  url: string;
  prompt: string;
};

Busca conteúdo de uma URL e o processa com um modelo de IA.

WebSearch

Nome da ferramenta: WebSearch

type WebSearchInput = {
  query: string;
  allowed_domains?: string[];
  blocked_domains?: string[];
};

Pesquisa a web e retorna resultados formatados.

TodoWrite

Nome da ferramenta: TodoWrite

type TodoWriteInput = {
  todos: Array<{
    content: string;
    status: "pending" | "in_progress" | "completed";
    activeForm: string;
  }>;
};

Cria e gerencia uma lista de tarefas estruturada para rastrear progresso.

ExitPlanMode

Nome da ferramenta: ExitPlanMode

type ExitPlanModeInput = {
  allowedPrompts?: Array<{
    tool: "Bash";
    prompt: string;
  }>;
};

Sai do modo de planejamento. Opcionalmente especifica permissões baseadas em prompt necessárias para implementar o plano.

ListMcpResources

Nome da ferramenta: ListMcpResources

type ListMcpResourcesInput = {
  server?: string;
};

Lista recursos MCP disponíveis de servidores conectados.

ReadMcpResource

Nome da ferramenta: ReadMcpResource

type ReadMcpResourceInput = {
  server: string;
  uri: string;
};

Lê um recurso MCP específico de um servidor.

Config

Nome da ferramenta: Config

type ConfigInput = {
  setting: string;
  value?: string | boolean | number;
};

Obtém ou define um valor de configuração.

EnterWorktree

Nome da ferramenta: EnterWorktree

type EnterWorktreeInput = {
  name?: string;
  path?: string;
};

Cria e entra em um worktree git temporário para trabalho isolado. Passe path para mudar para um worktree existente do repositório atual em vez de criar um novo. name e path são mutuamente exclusivos.

Tipos de Saída de Ferramenta

Documentação de esquemas de saída para todas as ferramentas integradas do Claude Code. Esses tipos são exportados de @anthropic-ai/claude-agent-sdk e representam os dados de resposta reais retornados por cada ferramenta.

`ToolOutputSchemas`

União de todos os tipos de saída de ferramenta.

type ToolOutputSchemas =
  | AgentOutput
  | AskUserQuestionOutput
  | BashOutput
  | ConfigOutput
  | EnterWorktreeOutput
  | ExitPlanModeOutput
  | FileEditOutput
  | FileReadOutput
  | FileWriteOutput
  | GlobOutput
  | GrepOutput
  | ListMcpResourcesOutput
  | MonitorOutput
  | NotebookEditOutput
  | ReadMcpResourceOutput
  | TaskStopOutput
  | TodoWriteOutput
  | WebFetchOutput
  | WebSearchOutput;

Agent

Nome da ferramenta: Agent (anteriormente Task, que ainda é aceito como alias)

type AgentOutput =
  | {
      status: "completed";
      agentId: string;
      content: Array<{ type: "text"; text: string }>;
      totalToolUseCount: number;
      totalDurationMs: number;
      totalTokens: number;
      usage: {
        input_tokens: number;
        output_tokens: number;
        cache_creation_input_tokens: number | null;
        cache_read_input_tokens: number | null;
        server_tool_use: {
          web_search_requests: number;
          web_fetch_requests: number;
        } | null;
        service_tier: ("standard" | "priority" | "batch") | null;
        cache_creation: {
          ephemeral_1h_input_tokens: number;
          ephemeral_5m_input_tokens: number;
        } | null;
      };
      prompt: string;
    }
  | {
      status: "async_launched";
      agentId: string;
      description: string;
      prompt: string;
      outputFile: string;
      canReadOutputFile?: boolean;
    }
  | {
      status: "sub_agent_entered";
      description: string;
      message: string;
    };

Retorna o resultado do subagente. Discriminado no campo status: "completed" para tarefas concluídas, "async_launched" para tarefas de background e "sub_agent_entered" para subagentes interativos.

AskUserQuestion

Nome da ferramenta: AskUserQuestion

type AskUserQuestionOutput = {
  questions: Array<{
    question: string;
    header: string;
    options: Array<{ label: string; description: string; preview?: string }>;
    multiSelect: boolean;
  }>;
  answers: Record<string, string>;
};

Retorna as perguntas feitas e as respostas do usuário.

Bash

Nome da ferramenta: Bash

type BashOutput = {
  stdout: string;
  stderr: string;
  rawOutputPath?: string;
  interrupted: boolean;
  isImage?: boolean;
  backgroundTaskId?: string;
  backgroundedByUser?: boolean;
  dangerouslyDisableSandbox?: boolean;
  returnCodeInterpretation?: string;
  structuredContent?: unknown[];
  persistedOutputPath?: string;
  persistedOutputSize?: number;
};

Retorna saída de comando com stdout/stderr divididos. Comandos de background incluem um backgroundTaskId.

Monitor

Nome da ferramenta: Monitor

type MonitorOutput = {
  taskId: string;
  timeoutMs: number;
  persistent?: boolean;
};

Retorna o ID da tarefa de background para o monitor em execução. Use este ID com TaskStop para cancelar a watch antecipadamente.

Edit

Nome da ferramenta: Edit

type FileEditOutput = {
  filePath: string;
  oldString: string;
  newString: string;
  originalFile: string;
  structuredPatch: Array<{
    oldStart: number;
    oldLines: number;
    newStart: number;
    newLines: number;
    lines: string[];
  }>;
  userModified: boolean;
  replaceAll: boolean;
  gitDiff?: {
    filename: string;
    status: "modified" | "added";
    additions: number;
    deletions: number;
    changes: number;
    patch: string;
  };
};

Retorna o diff estruturado da operação de edição.

Read

Nome da ferramenta: Read

type FileReadOutput =
  | {
      type: "text";
      file: {
        filePath: string;
        content: string;
        numLines: number;
        startLine: number;
        totalLines: number;
      };
    }
  | {
      type: "image";
      file: {
        base64: string;
        type: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
        originalSize: number;
        dimensions?: {
          originalWidth?: number;
          originalHeight?: number;
          displayWidth?: number;
          displayHeight?: number;
        };
      };
    }
  | {
      type: "notebook";
      file: {
        filePath: string;
        cells: unknown[];
      };
    }
  | {
      type: "pdf";
      file: {
        filePath: string;
        base64: string;
        originalSize: number;
      };
    }
  | {
      type: "parts";
      file: {
        filePath: string;
        originalSize: number;
        count: number;
        outputDir: string;
      };
    };

Retorna conteúdo do arquivo em um formato apropriado ao tipo de arquivo. Discriminado no campo type.

Write

Nome da ferramenta: Write

type FileWriteOutput = {
  type: "create" | "update";
  filePath: string;
  content: string;
  structuredPatch: Array<{
    oldStart: number;
    oldLines: number;
    newStart: number;
    newLines: number;
    lines: string[];
  }>;
  originalFile: string | null;
  gitDiff?: {
    filename: string;
    status: "modified" | "added";
    additions: number;
    deletions: number;
    changes: number;
    patch: string;
  };
};

Retorna o resultado da escrita com informações de diff estruturado.

Glob

Nome da ferramenta: Glob

type GlobOutput = {
  durationMs: number;
  numFiles: number;
  filenames: string[];
  truncated: boolean;
};

Retorna caminhos de arquivo correspondentes ao padrão glob, classificados por tempo de modificação.

Grep

Nome da ferramenta: Grep

type GrepOutput = {
  mode?: "content" | "files_with_matches" | "count";
  numFiles: number;
  filenames: string[];
  content?: string;
  numLines?: number;
  numMatches?: number;
  appliedLimit?: number;
  appliedOffset?: number;
};

Retorna resultados de busca. A forma varia por mode: lista de arquivo, conteúdo com correspondências ou contagens de correspondência.

TaskStop

Nome da ferramenta: TaskStop

type TaskStopOutput = {
  message: string;
  task_id: string;
  task_type: string;
  command?: string;
};

Retorna confirmação após parar a tarefa de background.

NotebookEdit

Nome da ferramenta: NotebookEdit

type NotebookEditOutput = {
  new_source: string;
  cell_id?: string;
  cell_type: "code" | "markdown";
  language: string;
  edit_mode: string;
  error?: string;
  notebook_path: string;
  original_file: string;
  updated_file: string;
};

Retorna o resultado da edição do notebook com conteúdo de arquivo original e atualizado.

WebFetch

Nome da ferramenta: WebFetch

type WebFetchOutput = {
  bytes: number;
  code: number;
  codeText: string;
  result: string;
  durationMs: number;
  url: string;
};

Retorna o conteúdo buscado com status HTTP e metadados.

WebSearch

Nome da ferramenta: WebSearch

type WebSearchOutput = {
  query: string;
  results: Array<
    | {
        tool_use_id: string;
        content: Array<{ title: string; url: string }>;
      }
    | string
  >;
  durationSeconds: number;
};

Retorna resultados de busca da web.

TodoWrite

Nome da ferramenta: TodoWrite

type TodoWriteOutput = {
  oldTodos: Array<{
    content: string;
    status: "pending" | "in_progress" | "completed";
    activeForm: string;
  }>;
  newTodos: Array<{
    content: string;
    status: "pending" | "in_progress" | "completed";
    activeForm: string;
  }>;
};

Retorna as listas de tarefas anteriores e atualizadas.

ExitPlanMode

Nome da ferramenta: ExitPlanMode

type ExitPlanModeOutput = {
  plan: string | null;
  isAgent: boolean;
  filePath?: string;
  hasTaskTool?: boolean;
  awaitingLeaderApproval?: boolean;
  requestId?: string;
};

Retorna o estado do plano após sair do modo de planejamento.

ListMcpResources

Nome da ferramenta: ListMcpResources

type ListMcpResourcesOutput = Array<{
  uri: string;
  name: string;
  mimeType?: string;
  description?: string;
  server: string;
}>;

Retorna um array de recursos MCP disponíveis.

ReadMcpResource

Nome da ferramenta: ReadMcpResource

type ReadMcpResourceOutput = {
  contents: Array<{
    uri: string;
    mimeType?: string;
    text?: string;
  }>;
};

Retorna o conteúdo do recurso MCP solicitado.

Config

Nome da ferramenta: Config

type ConfigOutput = {
  success: boolean;
  operation?: "get" | "set";
  setting?: string;
  value?: unknown;
  previousValue?: unknown;
  newValue?: unknown;
  error?: string;
};

Retorna o resultado de uma operação de configuração get ou set.

EnterWorktree

Nome da ferramenta: EnterWorktree

type EnterWorktreeOutput = {
  worktreePath: string;
  worktreeBranch?: string;
  message: string;
};

Retorna informações sobre o worktree git.

Tipos de Permissão

`PermissionUpdate`

Operações para atualizar permissões.

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

`PermissionBehavior`

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

`PermissionUpdateDestination`

type PermissionUpdateDestination =
  | "userSettings" // Configurações globais do usuário
  | "projectSettings" // Configurações de projeto por diretório
  | "localSettings" // Configurações locais gitignored
  | "session" // Apenas sessão atual
  | "cliArg"; // Argumento CLI

`PermissionRuleValue`

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

Outros Tipos

`ApiKeySource`

type ApiKeySource = "user" | "project" | "org" | "temporary" | "oauth";

`SdkBeta`

Recursos beta disponíveis que podem ser ativados via opção betas. Veja Beta headers para mais informações.

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

O beta context-1m-2025-08-07 foi descontinuado a partir de 30 de abril de 2026. Passar este valor com Claude Sonnet 4.5 ou Sonnet 4 não tem efeito, e requisições que excedem a janela de contexto padrão de 200k-token retornam um erro. Para usar uma janela de contexto de 1M-token, migre para Claude Sonnet 4.6, Claude Opus 4.6, ou Claude Opus 4.7, que incluem contexto de 1M a preço padrão sem header beta necessário.

`SlashCommand`

Informações sobre um comando slash disponível.

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

`ModelInfo`

Informações sobre um modelo disponível.

type ModelInfo = {
  value: string;
  displayName: string;
  description: string;
  supportsEffort?: boolean;
  supportedEffortLevels?: ("low" | "medium" | "high" | "xhigh" | "max")[];
  supportsAdaptiveThinking?: boolean;
  supportsFastMode?: boolean;
};

`AgentInfo`

Informações sobre um subagente disponível que pode ser invocado via ferramenta Agent.

type AgentInfo = {
  name: string;
  description: string;
  model?: string;
};

Campo	Tipo	Descrição
`name`	`string`	Identificador de tipo de agente (por exemplo, `"Explore"`, `"general-purpose"`)
`description`	`string`	Descrição de quando usar este agente
`model`	`string \| undefined`	Alias de modelo que este agente usa. Se omitido, herda o modelo do pai

`McpServerStatus`

Status de um servidor MCP conectado.

type McpServerStatus = {
  name: string;
  status: "connected" | "failed" | "needs-auth" | "pending" | "disabled";
  serverInfo?: {
    name: string;
    version: string;
  };
  error?: string;
  config?: McpServerStatusConfig;
  scope?: string;
  tools?: {
    name: string;
    description?: string;
    annotations?: {
      readOnly?: boolean;
      destructive?: boolean;
      openWorld?: boolean;
    };
  }[];
};

`McpServerStatusConfig`

A configuração de um servidor MCP conforme relatado por mcpServerStatus(). Esta é a união de todos os tipos de transporte de servidor MCP.

type McpServerStatusConfig =
  | McpStdioServerConfig
  | McpSSEServerConfig
  | McpHttpServerConfig
  | McpSdkServerConfig
  | McpClaudeAIProxyServerConfig;

Veja McpServerConfig para detalhes sobre cada tipo de transporte.

`AccountInfo`

Informações de conta para o usuário autenticado.

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

`ModelUsage`

Estatísticas de uso por modelo retornadas em mensagens de resultado. O valor costUSD é uma estimativa do lado do cliente. Veja Track cost and usage para ressalvas de faturamento.

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

`ConfigScope`

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

`NonNullableUsage`

Uma versão de Usage com todos os campos anuláveis tornados não-anuláveis.

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

`Usage`

Estatísticas de uso de token (de @anthropic-ai/sdk).

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

`CallToolResult`

Tipo de resultado de ferramenta MCP (de @modelcontextprotocol/sdk/types.js).

type CallToolResult = {
  content: Array<{
    type: "text" | "image" | "resource";
    // Campos adicionais variam por tipo
  }>;
  isError?: boolean;
};

`ThinkingConfig`

Controla o comportamento de pensamento/raciocínio do Claude. Tem precedência sobre o maxThinkingTokens descontinuado.

type ThinkingConfig =
  | { type: "adaptive" } // O modelo determina quando e quanto raciocinar (Opus 4.6+)
  | { type: "enabled"; budgetTokens?: number } // Orçamento de token de pensamento fixo
  | { type: "disabled" }; // Sem pensamento estendido

`SpawnedProcess`

Interface para geração de processo personalizado (usada com opção spawnClaudeCodeProcess). ChildProcess já satisfaz esta interface.

interface SpawnedProcess {
  stdin: Writable;
  stdout: Readable;
  readonly killed: boolean;
  readonly exitCode: number | null;
  kill(signal: NodeJS.Signals): boolean;
  on(
    event: "exit",
    listener: (code: number | null, signal: NodeJS.Signals | null) => void
  ): void;
  on(event: "error", listener: (error: Error) => void): void;
  once(
    event: "exit",
    listener: (code: number | null, signal: NodeJS.Signals | null) => void
  ): void;
  once(event: "error", listener: (error: Error) => void): void;
  off(
    event: "exit",
    listener: (code: number | null, signal: NodeJS.Signals | null) => void
  ): void;
  off(event: "error", listener: (error: Error) => void): void;
}

`SpawnOptions`

Opções passadas para a função de geração personalizada.

interface SpawnOptions {
  command: string;
  args: string[];
  cwd?: string;
  env: Record<string, string | undefined>;
  signal: AbortSignal;
}

`McpSetServersResult`

Resultado de uma operação setMcpServers().

type McpSetServersResult = {
  added: string[];
  removed: string[];
  errors: Record<string, string>;
};

`RewindFilesResult`

Resultado de uma operação rewindFiles().

type RewindFilesResult = {
  canRewind: boolean;
  error?: string;
  filesChanged?: string[];
  insertions?: number;
  deletions?: number;
};

`SDKStatusMessage`

Mensagem de atualização de status (por exemplo, compactando).

type SDKStatusMessage = {
  type: "system";
  subtype: "status";
  status: "compacting" | null;
  permissionMode?: PermissionMode;
  uuid: UUID;
  session_id: string;
};

`SDKTaskNotificationMessage`

Notificação quando uma tarefa de background é concluída, falha ou é parada. Tarefas de background incluem comandos Bash run_in_background, watches Monitor e subagentes de background.

type SDKTaskNotificationMessage = {
  type: "system";
  subtype: "task_notification";
  task_id: string;
  tool_use_id?: string;
  status: "completed" | "failed" | "stopped";
  output_file: string;
  summary: string;
  usage?: {
    total_tokens: number;
    tool_uses: number;
    duration_ms: number;
  };
  uuid: UUID;
  session_id: string;
};

`SDKToolUseSummaryMessage`

Resumo do uso de ferramenta em uma conversa.

type SDKToolUseSummaryMessage = {
  type: "tool_use_summary";
  summary: string;
  preceding_tool_use_ids: string[];
  uuid: UUID;
  session_id: string;
};

`SDKHookStartedMessage`

Emitido quando um hook começa a executar.

type SDKHookStartedMessage = {
  type: "system";
  subtype: "hook_started";
  hook_id: string;
  hook_name: string;
  hook_event: string;
  uuid: UUID;
  session_id: string;
};

`SDKHookProgressMessage`

Emitido enquanto um hook está em execução, com saída stdout/stderr.

type SDKHookProgressMessage = {
  type: "system";
  subtype: "hook_progress";
  hook_id: string;
  hook_name: string;
  hook_event: string;
  stdout: string;
  stderr: string;
  output: string;
  uuid: UUID;
  session_id: string;
};

`SDKHookResponseMessage`

Emitido quando um hook termina de executar.

type SDKHookResponseMessage = {
  type: "system";
  subtype: "hook_response";
  hook_id: string;
  hook_name: string;
  hook_event: string;
  output: string;
  stdout: string;
  stderr: string;
  exit_code?: number;
  outcome: "success" | "error" | "cancelled";
  uuid: UUID;
  session_id: string;
};

`SDKToolProgressMessage`

Emitido periodicamente enquanto uma ferramenta está sendo executada para indicar progresso.

type SDKToolProgressMessage = {
  type: "tool_progress";
  tool_use_id: string;
  tool_name: string;
  parent_tool_use_id: string | null;
  elapsed_time_seconds: number;
  task_id?: string;
  uuid: UUID;
  session_id: string;
};

`SDKAuthStatusMessage`

Emitido durante fluxos de autenticação.

type SDKAuthStatusMessage = {
  type: "auth_status";
  isAuthenticating: boolean;
  output: string[];
  error?: string;
  uuid: UUID;
  session_id: string;
};

`SDKTaskStartedMessage`

Emitido quando uma tarefa de background começa. O campo task_type é "local_bash" para comandos Bash de background e watches Monitor, "local_agent" para subagentes, ou "remote_agent".

type SDKTaskStartedMessage = {
  type: "system";
  subtype: "task_started";
  task_id: string;
  tool_use_id?: string;
  description: string;
  task_type?: string;
  uuid: UUID;
  session_id: string;
};

`SDKTaskProgressMessage`

Emitido periodicamente enquanto uma tarefa de background está em execução.

type SDKTaskProgressMessage = {
  type: "system";
  subtype: "task_progress";
  task_id: string;
  tool_use_id?: string;
  description: string;
  usage: {
    total_tokens: number;
    tool_uses: number;
    duration_ms: number;
  };
  last_tool_name?: string;
  uuid: UUID;
  session_id: string;
};

`SDKFilesPersistedEvent`

Emitido quando checkpoints de arquivo são persistidos em disco.

type SDKFilesPersistedEvent = {
  type: "system";
  subtype: "files_persisted";
  files: { filename: string; file_id: string }[];
  failed: { filename: string; error: string }[];
  processed_at: string;
  uuid: UUID;
  session_id: string;
};

`SDKRateLimitEvent`

Emitido quando a sessão encontra um limite de taxa.

type SDKRateLimitEvent = {
  type: "rate_limit_event";
  rate_limit_info: {
    status: "allowed" | "allowed_warning" | "rejected";
    resetsAt?: number;
    utilization?: number;
  };
  uuid: UUID;
  session_id: string;
};

`SDKLocalCommandOutputMessage`

Saída de um comando slash local (por exemplo, /voice ou /cost). Exibido como texto estilo assistente na transcrição.

type SDKLocalCommandOutputMessage = {
  type: "system";
  subtype: "local_command_output";
  content: string;
  uuid: UUID;
  session_id: string;
};

`SDKPromptSuggestionMessage`

Emitido após cada turno quando promptSuggestions está ativado. Contém um prompt de usuário previsto.

type SDKPromptSuggestionMessage = {
  type: "prompt_suggestion";
  suggestion: string;
  uuid: UUID;
  session_id: string;
};

`AbortError`

Classe de erro personalizada para operações de abort.

class AbortError extends Error {}

Configuração de Sandbox

`SandboxSettings`

Configuração para comportamento de sandbox. Use isso para ativar sandboxing de comando e configurar restrições de rede programaticamente.

type SandboxSettings = {
  enabled?: boolean;
  autoAllowBashIfSandboxed?: boolean;
  excludedCommands?: string[];
  allowUnsandboxedCommands?: boolean;
  network?: SandboxNetworkConfig;
  filesystem?: SandboxFilesystemConfig;
  ignoreViolations?: Record<string, string[]>;
  enableWeakerNestedSandbox?: boolean;
  ripgrep?: { command: string; args?: string[] };
};

Propriedade	Tipo	Padrão	Descrição
`enabled`	`boolean`	`false`	Ativar modo sandbox para execução de comando
`autoAllowBashIfSandboxed`	`boolean`	`true`	Auto-aprovar comandos bash quando sandbox está ativado
`excludedCommands`	`string[]`	`[]`	Comandos que sempre contornam restrições de sandbox (por exemplo, `['docker']`). Esses executam sem sandbox automaticamente sem envolvimento do modelo
`allowUnsandboxedCommands`	`boolean`	`true`	Permitir que o modelo solicite executar comandos fora do sandbox. Quando `true`, o modelo pode definir `dangerouslyDisableSandbox` na entrada da ferramenta, que volta para o sistema de permissões
`network`	`SandboxNetworkConfig`	`undefined`	Configuração de sandbox específica de rede
`filesystem`	`SandboxFilesystemConfig`	`undefined`	Configuração de sandbox específica do sistema de arquivos para restrições de leitura/escrita
`ignoreViolations`	`Record<string, string[]>`	`undefined`	Mapa de categorias de violação para padrões a ignorar (por exemplo, `{ file: ['/tmp/*'], network: ['localhost'] }`)
`enableWeakerNestedSandbox`	`boolean`	`false`	Ativar um sandbox aninhado mais fraco para compatibilidade
`ripgrep`	`{ command: string; args?: string[] }`	`undefined`	Configuração de binário ripgrep personalizado para ambientes sandbox

Exemplo de uso

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

for await (const message of query({
  prompt: "Build and test my project",
  options: {
    sandbox: {
      enabled: true,
      autoAllowBashIfSandboxed: true,
      network: {
        allowLocalBinding: true
      }
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

Segurança de socket Unix: A opção allowUnixSockets pode conceder acesso a serviços de sistema poderosos. Por exemplo, permitir /var/run/docker.sock efetivamente concede acesso completo ao sistema host através da API Docker, contornando isolamento de sandbox. Apenas permita sockets Unix que são estritamente necessários e entenda as implicações de segurança de cada um.

`SandboxNetworkConfig`

Configuração específica de rede para modo sandbox.

type SandboxNetworkConfig = {
  allowedDomains?: string[];
  deniedDomains?: string[];
  allowManagedDomainsOnly?: boolean;
  allowLocalBinding?: boolean;
  allowUnixSockets?: string[];
  allowAllUnixSockets?: boolean;
  httpProxyPort?: number;
  socksProxyPort?: number;
};

Propriedade	Tipo	Padrão	Descrição
`allowedDomains`	`string[]`	`[]`	Nomes de domínio que processos sandboxed podem acessar
`deniedDomains`	`string[]`	`[]`	Nomes de domínio que processos sandboxed não podem acessar. Tem precedência sobre `allowedDomains`
`allowManagedDomainsOnly`	`boolean`	`false`	Restringir acesso de rede apenas aos domínios em `allowedDomains`
`allowLocalBinding`	`boolean`	`false`	Permitir que processos se vinculem a portas locais (por exemplo, para servidores dev)
`allowUnixSockets`	`string[]`	`[]`	Caminhos de socket Unix que processos podem acessar (por exemplo, socket Docker)
`allowAllUnixSockets`	`boolean`	`false`	Permitir acesso a todos os sockets Unix
`httpProxyPort`	`number`	`undefined`	Porta de proxy HTTP para requisições de rede
`socksProxyPort`	`number`	`undefined`	Porta de proxy SOCKS para requisições de rede

`SandboxFilesystemConfig`

Configuração específica do sistema de arquivos para modo sandbox.

type SandboxFilesystemConfig = {
  allowWrite?: string[];
  denyWrite?: string[];
  denyRead?: string[];
};

Propriedade	Tipo	Padrão	Descrição
`allowWrite`	`string[]`	`[]`	Padrões de caminho de arquivo para permitir acesso de escrita
`denyWrite`	`string[]`	`[]`	Padrões de caminho de arquivo para negar acesso de escrita
`denyRead`	`string[]`	`[]`	Padrões de caminho de arquivo para negar acesso de leitura

Fallback de Permissões para Comandos Sem Sandbox

Quando allowUnsandboxedCommands está ativado, o modelo pode solicitar executar comandos fora do sandbox definindo dangerouslyDisableSandbox: true na entrada da ferramenta. Essas solicitações voltam para o sistema de permissões existente, significando que seu handler canUseTool é invocado, permitindo que você implemente lógica de autorização personalizada.

excludedCommands vs allowUnsandboxedCommands:

excludedCommands: Uma lista estática de comandos que sempre contornam o sandbox automaticamente (por exemplo, ['docker']). O modelo não tem controle sobre isso.
allowUnsandboxedCommands: Permite que o modelo decida em tempo de execução se solicita execução sem sandbox definindo dangerouslyDisableSandbox: true na entrada da ferramenta.

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

for await (const message of query({
  prompt: "Deploy my application",
  options: {
    sandbox: {
      enabled: true,
      allowUnsandboxedCommands: true // Modelo pode solicitar execução sem sandbox
    },
    permissionMode: "default",
    canUseTool: async (tool, input) => {
      // Verificar se o modelo está solicitando bypass do sandbox
      if (tool === "Bash" && input.dangerouslyDisableSandbox) {
        // O modelo está solicitando executar este comando fora do sandbox
        console.log(`Unsandboxed command requested: ${input.command}`);

        if (isCommandAuthorized(input.command)) {
          return { behavior: "allow" as const, updatedInput: input };
        }
        return {
          behavior: "deny" as const,
          message: "Command not authorized for unsandboxed execution"
        };
      }
      return { behavior: "allow" as const, updatedInput: input };
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

Este padrão permite que você:

Auditar solicitações do modelo: Registre quando o modelo solicita execução sem sandbox
Implementar listas de permissão: Apenas permitir comandos específicos para executar sem sandbox
Adicionar fluxos de aprovação: Exigir autorização explícita para operações privilegiadas

Comandos executando com dangerouslyDisableSandbox: true têm acesso completo ao sistema. Garanta que seu handler canUseTool valide essas solicitações cuidadosamente.Se permissionMode está definido como bypassPermissions e allowUnsandboxedCommands está ativado, o modelo pode autonomamente executar comandos fora do sandbox sem quaisquer prompts de aprovação. Esta combinação efetivamente permite que o modelo escape do isolamento de sandbox silenciosamente.

Veja também

Visão geral do SDK - Conceitos gerais do SDK
Referência do SDK Python - Documentação do SDK Python
Referência da CLI - Interface de linha de comando
Fluxos de trabalho comuns - Guias passo a passo

Agent SDK

Conceitos principais

Entrada e saída

Estender com ferramentas

Personalizar comportamento

Controle e observabilidade

Implantação

Referências do SDK

​Instalação

​Funções

​query()

​Parâmetros

​Retorna

​startup()

​Parâmetros

​Retorna

​Exemplo

​tool()

​Parâmetros

​ToolAnnotations

​createSdkMcpServer()

​Parâmetros

​listSessions()

​Parâmetros

​Tipo de retorno: SDKSessionInfo

​Exemplo

​getSessionMessages()

​Parâmetros

​Tipo de retorno: SessionMessage

​Exemplo

​getSessionInfo()

​Parâmetros

​renameSession()

​Parâmetros

​tagSession()

​Parâmetros

​Tipos

​Options

​Objeto Query

​Métodos

​WarmQuery

​Métodos

​SDKControlInitializeResponse

​AgentDefinition

​AgentMcpServerSpec

​SettingSource

​Comportamento padrão

​Por que usar settingSources

​Precedência de configurações

​PermissionMode

​CanUseTool

​PermissionResult

​ToolConfig

​McpServerConfig

​McpStdioServerConfig

​McpSSEServerConfig

​McpHttpServerConfig

​McpSdkServerConfigWithInstance

​McpClaudeAIProxyServerConfig

​SdkPluginConfig

​Tipos de Mensagem

​SDKMessage

​SDKAssistantMessage

​SDKUserMessage

​SDKUserMessageReplay

​SDKResultMessage

​SDKSystemMessage

​SDKPartialAssistantMessage

​SDKCompactBoundaryMessage

​SDKPluginInstallMessage

​SDKPermissionDenial

​Tipos de Hook

​HookEvent

​HookCallback

​HookCallbackMatcher

​HookInput

​BaseHookInput

​PreToolUseHookInput

​PostToolUseHookInput

​PostToolUseFailureHookInput

Instalação

Funções

`query()`

Parâmetros

Retorna

`startup()`

Parâmetros

Retorna

Exemplo

`tool()`

Parâmetros

`ToolAnnotations`

`createSdkMcpServer()`

Parâmetros

`listSessions()`

Parâmetros

Tipo de retorno: `SDKSessionInfo`

Exemplo

`getSessionMessages()`

Parâmetros

Tipo de retorno: `SessionMessage`

Exemplo

`getSessionInfo()`

Parâmetros

`renameSession()`

Parâmetros

`tagSession()`

Parâmetros

Tipos

`Options`

Objeto `Query`

Métodos

`WarmQuery`

Métodos

`SDKControlInitializeResponse`

`AgentDefinition`

`AgentMcpServerSpec`

`SettingSource`

Comportamento padrão

Por que usar settingSources

Precedência de configurações

`PermissionMode`

`CanUseTool`

`PermissionResult`

`ToolConfig`

`McpServerConfig`

`McpStdioServerConfig`

`McpSSEServerConfig`

`McpHttpServerConfig`

`McpSdkServerConfigWithInstance`

`McpClaudeAIProxyServerConfig`

`SdkPluginConfig`

Tipos de Mensagem

`SDKMessage`

`SDKAssistantMessage`

`SDKUserMessage`

`SDKUserMessageReplay`

`SDKResultMessage`

`SDKSystemMessage`

`SDKPartialAssistantMessage`

`SDKCompactBoundaryMessage`

`SDKPluginInstallMessage`

`SDKPermissionDenial`

Tipos de Hook

`HookEvent`

`HookCallback`

`HookCallbackMatcher`

`HookInput`

`BaseHookInput`

`PreToolUseHookInput`

`PostToolUseHookInput`

`PostToolUseFailureHookInput`

`NotificationHookInput`

`UserPromptSubmitHookInput`

`SessionStartHookInput`

`SessionEndHookInput`

`StopHookInput`

`SubagentStartHookInput`

`SubagentStopHookInput`

`PreCompactHookInput`