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 não autorizado a arquivos
• 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 o 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 é acionado
2. A configuração do hook: informa ao SDK qual evento deve ser interceptado (como PreToolUse) e quais ferramentas devem corresponder

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

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher

# Define a hook callback that receives tool call details
async def protect_env_files(input_data, tool_use_id, context):
    # Extract the file path from the tool's input arguments
    file_path = input_data['tool_input'].get('file_path', '')
    file_name = file_path.split('/')[-1]

    # Block the operation if targeting a .env file
    if file_name == '.env':
        return {
            'hookSpecificOutput': {
                'hookEventName': input_data['hook_event_name'],
                'permissionDecision': 'deny',
                'permissionDecisionReason': 'Cannot modify .env files'
            }
        }

    # Return empty object to allow the operation
    return {}

async def main():
    async for message in query(
        prompt="Update the database configuration",
        options=ClaudeAgentOptions(
            hooks={
                # Register the hook for PreToolUse events
                # The matcher filters to only Write and Edit tool calls
                'PreToolUse': [HookMatcher(matcher='Write|Edit', hooks=[protect_env_files])]
            }
        )
    ):
        print(message)

asyncio.run(main())

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 acionam 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 filtram apenas 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 é acionado 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 é acionado:

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

Entradas da 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 sejam canceladas 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:

async def log_tool_calls(input_data, tool_use_id, context):
    if input_data['hook_event_name'] == 'PreToolUse':
        print(f"Tool: {input_data['tool_name']}")
        print(f"Input: {input_data['tool_input']}")
    return {}

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 de sistema para lembrar Claude sobre práticas seguras de arquivo:

async def block_etc_writes(input_data, tool_use_id, context):
    file_path = input_data['tool_input'].get('file_path', '')

    if file_path.startswith('/etc'):
        return {
            # Top-level field: inject guidance into the conversation
            'systemMessage': 'Remember: system directories like /etc are protected.',
            # hookSpecificOutput: block the operation
            'hookSpecificOutput': {
                'hookEventName': input_data['hook_event_name'],
                'permissionDecision': 'deny',
                'permissionDecisionReason': 'Writing to /etc is not allowed'
            }
        }
    return {}

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:

async def block_dangerous_commands(input_data, tool_use_id, context):
    if input_data['hook_event_name'] != 'PreToolUse':
        return {}

    command = input_data['tool_input'].get('command', '')

    if 'rm -rf /' in command:
        return {
            'hookSpecificOutput': {
                'hookEventName': input_data['hook_event_name'],
                'permissionDecision': 'deny',
                'permissionDecisionReason': 'Dangerous command blocked: rm -rf /'
            }
        }
    return {}

Modificar entrada de ferramenta

Retorne entrada atualizada para alterar o que a ferramenta recebe:

async def redirect_to_sandbox(input_data, tool_use_id, context):
    if input_data['hook_event_name'] != 'PreToolUse':
        return {}

    if input_data['tool_name'] == 'Write':
        original_path = input_data['tool_input'].get('file_path', '')
        return {
            'hookSpecificOutput': {
                'hookEventName': input_data['hook_event_name'],
                'permissionDecision': 'allow',
                'updatedInput': {
                    **input_data['tool_input'],
                    'file_path': f'/sandbox{original_path}'
                }
            }
        }
    return {}

Adicionar uma mensagem de 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:

async def auto_approve_read_only(input_data, tool_use_id, context):
    if input_data['hook_event_name'] != 'PreToolUse':
        return {}

    read_only_tools = ['Read', 'Glob', 'Grep', 'LS']
    if input_data['tool_name'] in read_only_tools:
        return {
            'hookSpecificOutput': {
                'hookEventName': input_data['hook_event_name'],
                'permissionDecision': 'allow',
                'permissionDecisionReason': 'Read-only tool auto-approved'
            }
        }
    return {}

Lidar com cenários avançados

Esses padrões ajudam você a construir sistemas de hooks 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):

options = ClaudeAgentOptions(
    hooks={
        'PreToolUse': [
            HookMatcher(hooks=[rate_limiter]),        # First: check rate limits
            HookMatcher(hooks=[authorization_check]), # Second: verify permissions
            HookMatcher(hooks=[input_sanitizer]),     # Third: sanitize inputs
            HookMatcher(hooks=[audit_logger])         # Last: log the action
        ]
    }
)

Matchers específicos de ferramenta com regex

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

options = ClaudeAgentOptions(
    hooks={
        'PreToolUse': [
            # Match file modification tools
            HookMatcher(matcher='Write|Edit|Delete', hooks=[file_security_hook]),

            # Match all MCP tools
            HookMatcher(matcher='^mcp__', hooks=[mcp_audit_hook]),

            # Match everything (no matcher)
            HookMatcher(hooks=[global_logger])
        ]
    }
)

Rastreando atividade de subaagente

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

async def subagent_tracker(input_data, tool_use_id, context):
    if input_data['hook_event_name'] == 'SubagentStop':
        print(f"[SUBAGENT] Completed")
        print(f"  Tool use ID: {tool_use_id}")
        print(f"  Stop hook active: {input_data.get('stop_hook_active')}")
    return {}

options = ClaudeAgentOptions(
    hooks={
        'SubagentStop': [HookMatcher(hooks=[subagent_tracker])]
    }
)

Operações assíncronas em hooks

Hooks podem executar operações assíncronas como requisições HTTP. Trate 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:

import aiohttp
from datetime import datetime

async def webhook_notifier(input_data, tool_use_id, context):
    if input_data['hook_event_name'] != 'PostToolUse':
        return {}

    try:
        async with aiohttp.ClientSession() as session:
            await session.post(
                'https://api.example.com/webhook',
                json={
                    'tool': input_data['tool_name'],
                    'timestamp': datetime.now().isoformat()
                }
            )
    except Exception as e:
        print(f'Webhook request failed: {e}')

    return {}

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 está sendo acionado

• Verifique se o nome do evento do hook está correto e diferencia maiúsculas de minúsculas (PreToolUse, não preToolUse)
• Verifique se seu padrão de matcher corresponde exatamente ao nome da ferramenta
• 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 são acionados para todos os eventos desse tipo.
• Hooks podem não ser acionados quando o agente atinge o limite max_turns porque a sessão termina antes dos hooks poderem ser executados

Matcher não está filtrando conforme esperado

Matchers correspondem apenas a nomes de ferramentas, não a 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...
};

Timeout do hook

• 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

• Inclua hookEventName em hookSpecificOutput para identificar qual tipo de hook a saída é

Hooks de sessão não disponíveis

Os 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 subaagente se multiplicando

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

Loops recursivos de hook com subaagentes

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

• Verifique um indicador de subaagente na entrada do hook antes de gerar
• Use o campo parent_tool_use_id para detectar se você já está em um contexto de subaagente
• 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 as capacidades do agente
• Referência do SDK TypeScript
• Referência do SDK Python