Intercettare e controllare il comportamento dell'agente con hook

Gli hook ti permettono di intercettare l'esecuzione dell'agente nei punti chiave per aggiungere validazione, logging, controlli di sicurezza o logica personalizzata. Con gli hook, puoi:

• Bloccare operazioni pericolose prima che vengano eseguite, come comandi shell distruttivi o accesso a file non autorizzato
• Registrare e controllare ogni chiamata di strumento per conformità, debug o analitiche
• Trasformare input e output per sanificare i dati, iniettare credenziali o reindirizzare percorsi di file
• Richiedere approvazione umana per azioni sensibili come scritture su database o chiamate API
• Tracciare il ciclo di vita della sessione per gestire lo stato, pulire risorse o inviare notifiche

Un hook ha due parti:

1. La funzione di callback: la logica che viene eseguita quando l'hook si attiva
2. La configurazione dell'hook: dice all'SDK quale evento agganciare (come PreToolUse) e quali strumenti abbinare

L'esempio seguente blocca l'agente dal modificare i file .env. Per prima cosa, definisci un callback che controlla il percorso del file, quindi passalo a query() per eseguirlo prima di qualsiasi chiamata a uno strumento Write o Edit:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher

# Definisci un callback hook che riceve i dettagli della chiamata dello strumento
async def protect_env_files(input_data, tool_use_id, context):
    # Estrai il percorso del file dagli argomenti di input dello strumento
    file_path = input_data['tool_input'].get('file_path', '')
    file_name = file_path.split('/')[-1]

    # Blocca l'operazione se è destinata a un file .env
    if file_name == '.env':
        return {
            'hookSpecificOutput': {
                'hookEventName': input_data['hook_event_name'],
                'permissionDecision': 'deny',
                'permissionDecisionReason': 'Cannot modify .env files'
            }
        }

    # Restituisci un oggetto vuoto per consentire l'operazione
    return {}

async def main():
    async for message in query(
        prompt="Update the database configuration",
        options=ClaudeAgentOptions(
            hooks={
                # Registra l'hook per gli eventi PreToolUse
                # Il matcher filtra solo le chiamate agli strumenti Write e Edit
                'PreToolUse': [HookMatcher(matcher='Write|Edit', hooks=[protect_env_files])]
            }
        )
    ):
        print(message)

asyncio.run(main())

Questo è un hook PreToolUse. Viene eseguito prima che lo strumento si esegua e può bloccare o consentire operazioni in base alla tua logica. Il resto di questa guida copre tutti gli hook disponibili, le loro opzioni di configurazione e i modelli per i casi d'uso comuni.

Hook disponibili

L'SDK fornisce hook per diverse fasi dell'esecuzione dell'agente. Alcuni hook sono disponibili in entrambi gli SDK, mentre altri sono solo TypeScript perché l'SDK Python non li supporta.

Casi d'uso comuni

Gli hook sono abbastanza flessibili da gestire molti scenari diversi. Ecco alcuni dei modelli più comuni organizzati per categoria.

Configurare gli hook

Per configurare un hook per il tuo agente, passa l'hook nel parametro options.hooks quando chiami query():

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

L'opzione hooks è un dizionario (Python) o un oggetto (TypeScript) dove:

• Le chiavi sono nomi degli eventi hook (ad es. 'PreToolUse', 'PostToolUse', 'Stop')
• I valori sono array di matcher, ognuno contenente un modello di filtro opzionale e le tue funzioni di callback

Le tue funzioni di callback hook ricevono dati di input sull'evento e restituiscono una risposta in modo che l'agente sappia se consentire, bloccare o modificare l'operazione.

Matcher

Usa i matcher per filtrare quali strumenti attivano i tuoi callback:

Usa il modello matcher per indirizzare strumenti specifici quando possibile. Un matcher con 'Bash' viene eseguito solo per i comandi Bash, mentre omettere il modello esegue i tuoi callback per ogni chiamata di strumento. Nota che i matcher filtrano solo per nome dello strumento, non per percorsi di file o altri argomenti—per filtrare per percorso di file, controlla tool_input.file_path all'interno del tuo callback.

I matcher si applicano solo agli hook basati su strumenti (PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest). Per gli hook del ciclo di vita come Stop, SessionStart e Notification, i matcher vengono ignorati e l'hook si attiva per tutti gli eventi di quel tipo.

Questo esempio utilizza un matcher per eseguire un hook solo per gli strumenti che modificano i file quando si attiva l'evento PreToolUse:

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

Input della funzione di callback

Ogni callback hook riceve tre argomenti:

1. Dati di input (dict / HookInput): Dettagli dell'evento. Vedi dati di input per i campi
2. ID di utilizzo dello strumento (str | None / string | null): Correla gli eventi PreToolUse e PostToolUse
3. Contesto (HookContext): In TypeScript, contiene una proprietà signal (AbortSignal) per l'annullamento. Passalo alle operazioni asincrone come fetch() in modo che si annullino automaticamente se l'hook scade. In Python, questo argomento è riservato per uso futuro.

Dati di input

Il primo argomento del tuo callback hook contiene informazioni sull'evento. I nomi dei campi sono identici tra gli SDK (entrambi usano snake_case).

Campi comuni presenti in tutti i tipi di hook:

Campi specifici dell'hook variano in base al tipo di hook. Gli elementi contrassegnati ^TS sono disponibili solo nell'SDK TypeScript:

Il codice seguente definisce un callback hook che utilizza tool_name e tool_input per registrare i dettagli di ogni chiamata di strumento:

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 {}

Output del callback

La tua funzione di callback restituisce un oggetto che dice all'SDK come procedere. Restituisci un oggetto vuoto {} per consentire l'operazione senza modifiche. Per bloccare, modificare o aggiungere contesto all'operazione, restituisci un oggetto con un campo hookSpecificOutput contenente la tua decisione.

Campi di livello superiore (al di fuori di hookSpecificOutput):

Campi all'interno di hookSpecificOutput:

Questo esempio blocca le operazioni di scrittura nella directory /etc mentre inietta un messaggio di sistema per ricordare a Claude le pratiche di file sicure:

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 {
            # Campo di livello superiore: inietta guida nella conversazione
            'systemMessage': 'Remember: system directories like /etc are protected.',
            # hookSpecificOutput: blocca l'operazione
            'hookSpecificOutput': {
                'hookEventName': input_data['hook_event_name'],
                'permissionDecision': 'deny',
                'permissionDecisionReason': 'Writing to /etc is not allowed'
            }
        }
    return {}

Flusso di decisione delle autorizzazioni

Quando si applicano più hook o regole di autorizzazione, l'SDK le valuta in questo ordine:

1. Le regole Deny vengono controllate per prime (qualsiasi corrispondenza = negazione immediata).
2. Le regole Ask vengono controllate per seconde.
3. Le regole Allow vengono controllate per terze.
4. Predefinito su Ask se nulla corrisponde.

Se un hook restituisce deny, l'operazione viene bloccata—altri hook che restituiscono allow non la sovrascriveranno.

Bloccare uno strumento

Restituisci una decisione di negazione per impedire l'esecuzione dello strumento:

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 {}

Modificare l'input dello strumento

Restituisci l'input aggiornato per cambiare ciò che lo strumento riceve:

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 {}

Aggiungere un messaggio di sistema

Inietta contesto nella conversazione:

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

Approvare automaticamente strumenti specifici

Ignora i prompt di autorizzazione per gli strumenti affidabili. Questo è utile quando vuoi che determinate operazioni vengano eseguite senza conferma dell'utente:

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 {}

Gestire scenari avanzati

Questi modelli ti aiutano a costruire sistemi di hook più sofisticati per casi d'uso complessi.

Concatenare più hook

Gli hook vengono eseguiti nell'ordine in cui appaiono nell'array. Mantieni ogni hook focalizzato su una singola responsabilità e concatena più hook per logica complessa. Questo esempio esegue tutti e quattro gli hook per ogni chiamata di strumento (nessun matcher specificato):

options = ClaudeAgentOptions(
    hooks={
        'PreToolUse': [
            HookMatcher(hooks=[rate_limiter]),        # Primo: controlla i limiti di velocità
            HookMatcher(hooks=[authorization_check]), # Secondo: verifica le autorizzazioni
            HookMatcher(hooks=[input_sanitizer]),     # Terzo: sanifica gli input
            HookMatcher(hooks=[audit_logger])         # Ultimo: registra l'azione
        ]
    }
)

Matcher specifici per strumenti con regex

Usa modelli regex per abbinare più strumenti:

options = ClaudeAgentOptions(
    hooks={
        'PreToolUse': [
            # Abbina gli strumenti di modifica dei file
            HookMatcher(matcher='Write|Edit|Delete', hooks=[file_security_hook]),

            # Abbina tutti gli strumenti MCP
            HookMatcher(matcher='^mcp__', hooks=[mcp_audit_hook]),

            # Abbina tutto (nessun matcher)
            HookMatcher(hooks=[global_logger])
        ]
    }
)

Tracciare l'attività del subagente

Usa gli hook SubagentStop per monitorare il completamento del subagente. L'tool_use_id aiuta a correlare le chiamate dell'agente genitore con i loro subagenti:

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])]
    }
)

Operazioni asincrone negli hook

Gli hook possono eseguire operazioni asincrone come richieste HTTP. Gestisci gli errori con grazia catturando le eccezioni invece di lanciarle. In TypeScript, passa il signal a fetch() in modo che la richiesta si annulli se l'hook scade:

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 {}

Inviare notifiche (solo TypeScript)

Usa gli hook Notification per ricevere aggiornamenti di stato dall'agente e inoltrarli a servizi esterni come Slack o dashboard di monitoraggio:

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);
}

Risolvere i problemi comuni

Questa sezione copre i problemi comuni e come risolverli.

Hook non si attiva

• Verifica che il nome dell'evento hook sia corretto e sensibile alle maiuscole (PreToolUse, non preToolUse)
• Controlla che il tuo modello di matcher corrisponda esattamente al nome dello strumento
• Assicurati che l'hook sia sotto il tipo di evento corretto in options.hooks
• Per gli hook SubagentStop, Stop, SessionStart, SessionEnd e Notification, i matcher vengono ignorati. Questi hook si attivano per tutti gli eventi di quel tipo.
• Gli hook potrebbero non attivarsi quando l'agente raggiunge il limite max_turns perché la sessione termina prima che gli hook possano essere eseguiti

Matcher non filtra come previsto

I matcher abbinano solo i nomi degli strumenti, non i percorsi dei file o altri argomenti. Per filtrare per percorso di file, controlla tool_input.file_path all'interno del tuo 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 {};  // Salta i file non markdown
  // Elabora i file markdown...
};

Timeout dell'hook

• Aumenta il valore timeout nella configurazione HookMatcher
• Usa l'AbortSignal dal terzo argomento del callback per gestire l'annullamento con grazia in TypeScript

Strumento bloccato inaspettatamente

• Controlla tutti gli hook PreToolUse per i ritorni permissionDecision: 'deny'
• Aggiungi logging ai tuoi hook per vedere quale permissionDecisionReason stanno restituendo
• Verifica che i modelli di matcher non siano troppo ampi (un matcher vuoto abbina tutti gli strumenti)

Input modificato non applicato

• Assicurati che updatedInput sia all'interno di hookSpecificOutput, non al livello superiore:

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

• Devi anche restituire permissionDecision: 'allow' affinché la modifica dell'input abbia effetto

• Includi hookEventName in hookSpecificOutput per identificare quale tipo di hook è l'output

Hook di sessione non disponibili

Gli hook SessionStart, SessionEnd e Notification sono disponibili solo nell'SDK TypeScript. L'SDK Python non supporta questi eventi a causa di limitazioni di configurazione.

Prompt di autorizzazione del subagente moltiplicati

Quando si generano più subagenti, ognuno potrebbe richiedere autorizzazioni separatamente. I subagenti non ereditano automaticamente le autorizzazioni dell'agente genitore. Per evitare prompt ripetuti, usa gli hook PreToolUse per approvare automaticamente strumenti specifici, o configura regole di autorizzazione che si applicano alle sessioni dei subagenti.

Loop ricorsivi di hook con subagenti

Un hook UserPromptSubmit che genera subagenti può creare loop infiniti se quei subagenti attivano lo stesso hook. Per prevenire questo:

• Controlla un indicatore di subagente nell'input dell'hook prima di generare
• Usa il campo parent_tool_use_id per rilevare se sei già in un contesto di subagente
• Limita gli hook per eseguire solo per la sessione dell'agente di livello superiore

systemMessage non appare nell'output

Il campo systemMessage aggiunge contesto alla conversazione che il modello vede, ma potrebbe non apparire in tutte le modalità di output dell'SDK. Se hai bisogno di esporre le decisioni degli hook alla tua applicazione, registrale separatamente o usa un canale di output dedicato.

Scopri di più

• Autorizzazioni: controlla cosa può fare il tuo agente
• Strumenti personalizzati: costruisci strumenti per estendere le capacità dell'agente
• Riferimento SDK TypeScript
• Riferimento SDK Python