Interceptar e controlar o comportamento do agente com hooks

Hooks permitem que você intercepte a execução do agente em pontos-chave para adicionar validação, logging, controles de segurança ou lógica personalizada. Com hooks, você pode:

• Bloquear operações perigosas antes de serem executadas, como comandos shell destrutivos ou acesso a arquivos não autorizado
• Registrar e auditar cada chamada de ferramenta para conformidade, depuração ou análise
• Transformar entradas e saídas para sanitizar dados, injetar credenciais ou redirecionar caminhos de arquivo
• Exigir aprovação humana para ações sensíveis como gravações em banco de dados ou chamadas de API
• Rastrear ciclo de vida da sessão para gerenciar estado, limpar recursos ou enviar notificações

Um hook tem duas partes:

1. A função de callback: a lógica que é executada quando o hook dispara
2. A configuração do hook: informa ao SDK qual evento conectar (como PreToolUse) e quais ferramentas corresponder

O exemplo a seguir bloqueia o agente de modificar arquivos .env. Primeiro, defina um callback que verifica o caminho do arquivo, depois passe-o para query() para executar antes de qualquer chamada de ferramenta Write ou Edit:

Este é um hook PreToolUse. Ele é executado antes da ferramenta ser executada e pode bloquear ou permitir operações com base em sua lógica. O restante deste guia cobre todos os hooks disponíveis, suas opções de configuração e padrões para casos de uso comuns.

Hooks disponíveis

O SDK fornece hooks para diferentes estágios de execução do agente. Alguns hooks estão disponíveis em ambos os SDKs, enquanto outros são apenas para TypeScript porque o SDK Python não os suporta.

Casos de uso comuns

Hooks são flexíveis o suficiente para lidar com muitos cenários diferentes. Aqui estão alguns dos padrões mais comuns organizados por categoria.

Configurar hooks

Para configurar um hook para seu agente, passe o hook no parâmetro options.hooks ao chamar query():

async for message in query(
    prompt="Your prompt",
    options=ClaudeAgentOptions(
        hooks={
            'PreToolUse': [HookMatcher(matcher='Bash', hooks=[my_callback])]
        }
    )
):
    print(message)

A opção hooks é um dicionário (Python) ou objeto (TypeScript) onde:

• Chaves são nomes de eventos de hook (por exemplo, 'PreToolUse', 'PostToolUse', 'Stop')
• Valores são arrays de matchers, cada um contendo um padrão de filtro opcional e suas funções de callback

Suas funções de callback de hook recebem dados de entrada sobre o evento e retornam uma resposta para que o agente saiba permitir, bloquear ou modificar a operação.

Matchers

Use matchers para filtrar quais ferramentas disparam seus callbacks:

Use o padrão matcher para direcionar ferramentas específicas sempre que possível. Um matcher com 'Bash' é executado apenas para comandos Bash, enquanto omitir o padrão executa seus callbacks para cada chamada de ferramenta. Observe que matchers apenas filtram por nome da ferramenta, não por caminhos de arquivo ou outros argumentos—para filtrar por caminho de arquivo, verifique tool_input.file_path dentro de seu callback.

Matchers se aplicam apenas a hooks baseados em ferramentas (PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest). Para hooks de ciclo de vida como Stop, SessionStart e Notification, matchers são ignorados e o hook dispara para todos os eventos desse tipo.

Este exemplo usa um matcher para executar um hook apenas para ferramentas que modificam arquivos quando o evento PreToolUse dispara:

options = ClaudeAgentOptions(
    hooks={
        'PreToolUse': [
            HookMatcher(matcher='Write|Edit', hooks=[validate_file_path])
        ]
    }
)

Entradas de função de callback

Cada callback de hook recebe três argumentos:

1. Dados de entrada (dict / HookInput): Detalhes do evento. Veja dados de entrada para campos
2. ID de uso de ferramenta (str | None / string | null): Correlacionar eventos PreToolUse e PostToolUse
3. Contexto (HookContext): Em TypeScript, contém uma propriedade signal (AbortSignal) para cancelamento. Passe isso para operações assíncronas como fetch() para que elas se cancelem automaticamente se o hook expirar. Em Python, este argumento é reservado para uso futuro.

Dados de entrada

O primeiro argumento para seu callback de hook contém informações sobre o evento. Os nomes dos campos são idênticos entre SDKs (ambos usam snake_case).

Campos comuns presentes em todos os tipos de hook:

Campos específicos do hook variam por tipo de hook. Itens marcados ^TS estão disponíveis apenas no SDK TypeScript:

O código abaixo define um callback de hook que usa tool_name e tool_input para registrar detalhes sobre cada chamada de ferramenta:

Saídas de callback

Sua função de callback retorna um objeto que informa ao SDK como proceder. Retorne um objeto vazio {} para permitir a operação sem alterações. Para bloquear, modificar ou adicionar contexto à operação, retorne um objeto com um campo hookSpecificOutput contendo sua decisão.

Campos de nível superior (fora de hookSpecificOutput):

Campos dentro de hookSpecificOutput:

Este exemplo bloqueia operações de gravação no diretório /etc enquanto injeta uma mensagem do sistema para lembrar Claude sobre práticas seguras de arquivo:

Fluxo de decisão de permissão

Quando múltiplos hooks ou regras de permissão se aplicam, o SDK os avalia nesta ordem:

1. Regras de negação são verificadas primeiro (qualquer correspondência = negação imediata).
2. Regras de pergunta são verificadas em segundo lugar.
3. Regras de permissão são verificadas em terceiro lugar.
4. Padrão para pergunta se nada corresponder.

Se qualquer hook retornar deny, a operação é bloqueada—outros hooks retornando allow não a substituirão.

Bloquear uma ferramenta

Retorne uma decisão de negação para impedir a execução da ferramenta:

Modificar entrada de ferramenta

Retorne entrada atualizada para alterar o que a ferramenta recebe:

Adicionar uma mensagem do sistema

Injetar contexto na conversa:

async def add_security_reminder(input_data, tool_use_id, context):
    return {
        'systemMessage': 'Remember to follow security best practices.'
    }

Aprovar automaticamente ferramentas específicas

Contornar prompts de permissão para ferramentas confiáveis. Isso é útil quando você quer que certas operações sejam executadas sem confirmação do usuário:

Lidar com cenários avançados

Esses padrões ajudam você a construir sistemas de hook mais sofisticados para casos de uso complexos.

Encadeando múltiplos hooks

Hooks são executados na ordem em que aparecem no array. Mantenha cada hook focado em uma única responsabilidade e encadeie múltiplos hooks para lógica complexa. Este exemplo executa todos os quatro hooks para cada chamada de ferramenta (nenhum matcher especificado):

Matchers de ferramentas específicas com regex

Use padrões regex para corresponder múltiplas ferramentas:

Rastreando atividade de subagente

Use hooks SubagentStop para monitorar a conclusão de subagente. O tool_use_id ajuda a correlacionar chamadas de agente pai com seus subagentes:

Operações assíncronas em hooks

Hooks podem realizar operações assíncronas como requisições HTTP. Lidar com erros graciosamente capturando exceções em vez de lançá-las. Em TypeScript, passe o signal para fetch() para que a requisição seja cancelada se o hook expirar:

Enviando notificações (apenas TypeScript)

Use hooks Notification para receber atualizações de status do agente e encaminhá-las para serviços externos como Slack ou painéis de monitoramento:

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

const notificationHandler: HookCallback = async (input, toolUseID, { signal }) => {
  const notification = input as NotificationHookInput;

  await fetch('https://hooks.slack.com/services/YOUR/WEBHOOK/URL', {
    method: 'POST',
    body: JSON.stringify({
      text: `Agent status: ${notification.message}`
    }),
    signal
  });

  return {};
};

for await (const message of query({
  prompt: "Analyze this codebase",
  options: {
    hooks: {
      Notification: [{ hooks: [notificationHandler] }]
    }
  }
})) {
  console.log(message);
}

Corrigir problemas comuns

Esta seção cobre problemas comuns e como resolvê-los.

Hook não dispara

• Verifique se o nome do evento do hook está correto e sensível a maiúsculas (PreToolUse, não preToolUse)
• Verifique se seu padrão de matcher corresponde ao nome da ferramenta exatamente
• Certifique-se de que o hook está sob o tipo de evento correto em options.hooks
• Para hooks SubagentStop, Stop, SessionStart, SessionEnd e Notification, matchers são ignorados. Esses hooks disparam para todos os eventos desse tipo.
• Hooks podem não disparar quando o agente atinge o limite max_turns porque a sessão termina antes dos hooks poderem ser executados

Matcher não filtrando conforme esperado

Matchers apenas correspondem nomes de ferramentas, não caminhos de arquivo ou outros argumentos. Para filtrar por caminho de arquivo, verifique tool_input.file_path dentro de seu hook:

const myHook: HookCallback = async (input, toolUseID, { signal }) => {
  const preInput = input as PreToolUseHookInput;
  const filePath = preInput.tool_input?.file_path as string;
  if (!filePath?.endsWith('.md')) return {};  // Skip non-markdown files
  // Process markdown files...
};

Hook timeout

• Aumente o valor timeout na configuração HookMatcher
• Use o AbortSignal do terceiro argumento de callback para lidar com cancelamento graciosamente em TypeScript

Ferramenta bloqueada inesperadamente

• Verifique todos os hooks PreToolUse para retornos permissionDecision: 'deny'
• Adicione logging aos seus hooks para ver qual permissionDecisionReason eles estão retornando
• Verifique se os padrões de matcher não são muito amplos (um matcher vazio corresponde a todas as ferramentas)

Entrada modificada não aplicada

• Certifique-se de que updatedInput está dentro de hookSpecificOutput, não no nível superior:

  return {
    hookSpecificOutput: {
      hookEventName: input.hook_event_name,
      permissionDecision: 'allow',
      updatedInput: { command: 'new command' }
    }
  };

• Você também deve retornar permissionDecision: 'allow' para que a modificação de entrada tenha efeito

Hooks de sessão não disponíveis

Hooks SessionStart, SessionEnd e Notification estão disponíveis apenas no SDK TypeScript. O SDK Python não suporta esses eventos devido a limitações de configuração.

Prompts de permissão de subagente se multiplicando

Ao gerar múltiplos subagentes, cada um pode solicitar permissões separadamente. Subagentes não herdam automaticamente permissões de agente pai. Para evitar prompts repetidos, use hooks PreToolUse para aprovar automaticamente ferramentas específicas, ou configure regras de permissão que se apliquem a sessões de subagente.

Loops recursivos de hook com subagentes

Um hook UserPromptSubmit que gera subagentes pode criar loops infinitos se esses subagentes disparem o mesmo hook. Para evitar isso:

• Verifique um indicador de subagente na entrada do hook antes de gerar
• Use o campo parent_tool_use_id para detectar se você já está em um contexto de subagente
• Escope hooks para executar apenas para a sessão de agente de nível superior

systemMessage não aparecendo na saída

O campo systemMessage adiciona contexto à conversa que o modelo vê, mas pode não aparecer em todos os modos de saída do SDK. Se você precisar exibir decisões de hook para sua aplicação, registre-as separadamente ou use um canal de saída dedicado.

Saiba mais

• Permissões: controlar o que seu agente pode fazer
• Ferramentas Personalizadas: construir ferramentas para estender capacidades do agente
• Referência do SDK TypeScript
• Referência do SDK Python