Agent-Verhalten mit Hooks abfangen und steuern

.env

query()

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())

Hook-Ereignis	Python SDK	TypeScript SDK	Was löst es aus	Beispiel-Anwendungsfall
`PreToolUse`	Ja	Ja	Tool-Aufrufanforderung (kann blockiert oder geändert werden)	Gefährliche Shell-Befehle blockieren
`PostToolUse`	Ja	Ja	Tool-Ausführungsergebnis	Alle Dateiänderungen im Audit-Trail protokollieren
`PostToolUseFailure`	Nein	Ja	Tool-Ausführungsfehler	Tool-Fehler behandeln oder protokollieren
`UserPromptSubmit`	Ja	Ja	Benutzer-Prompt-Einreichung	Zusätzlichen Kontext in Prompts einfügen
`Stop`	Ja	Ja	Agent-Ausführung stoppen	Sitzungsstatus vor dem Beenden speichern
`SubagentStart`	Nein	Ja	Subagent-Initialisierung	Parallele Task-Erzeugung verfolgen
`SubagentStop`	Ja	Ja	Subagent-Fertigstellung	Ergebnisse aus parallelen Tasks aggregieren
`PreCompact`	Ja	Ja	Anforderung zur Gesprächskomprimierung	Vollständiges Transkript vor der Zusammenfassung archivieren
`PermissionRequest`	Nein	Ja	Berechtigungsdialog würde angezeigt	Benutzerdefinierte Berechtigungsbehandlung
`SessionStart`	Nein	Ja	Sitzungsinitialisierung	Protokollierung und Telemetrie initialisieren
`SessionEnd`	Nein	Ja	Sitzungsbeendigung	Temporäre Ressourcen bereinigen
`Notification`	Nein	Ja	Agent-Statusmeldungen	Agent-Status-Updates an Slack oder PagerDuty senden

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

Option	Typ	Standard	Beschreibung
`matcher`	`string`	`undefined`	Regex-Muster zum Abgleich von Tool-Namen. Integrierte Tools umfassen `Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `WebFetch`, `Task` und andere. MCP-Tools verwenden das Muster `mcp__<server>__<action>`.
`hooks`	`HookCallback[]`	-	Erforderlich. Array von Callback-Funktionen, die ausgeführt werden, wenn das Muster übereinstimmt
`timeout`	`number`	`60`	Timeout in Sekunden; erhöhen Sie es für Hooks, die externe API-Aufrufe tätigen

Feld	Typ	Beschreibung
`hook_event_name`	`string`	Der Hook-Typ (`PreToolUse`, `PostToolUse` usw.)
`session_id`	`string`	Aktuelle Sitzungskennung
`transcript_path`	`string`	Pfad zum Gesprächstranskript
`cwd`	`string`	Aktuelles Arbeitsverzeichnis

Feld	Typ	Beschreibung	Hooks
`tool_name`	`string`	Name des aufgerufenen Tools	PreToolUse, PostToolUse, PostToolUseFailure^TS, PermissionRequest^TS
`tool_input`	`object`	An das Tool übergebene Argumente	PreToolUse, PostToolUse, PostToolUseFailure^TS, PermissionRequest^TS
`tool_response`	`any`	Von der Tool-Ausführung zurückgegebenes Ergebnis	PostToolUse
`error`	`string`	Fehlermeldung aus Tool-Ausführungsfehler	PostToolUseFailure^TS
`is_interrupt`	`boolean`	Ob der Fehler durch eine Unterbrechung verursacht wurde	PostToolUseFailure^TS
`prompt`	`string`	Der Text des Benutzer-Prompts	UserPromptSubmit
`stop_hook_active`	`boolean`	Ob ein Stop-Hook gerade verarbeitet wird	Stop, SubagentStop
`agent_id`	`string`	Eindeutige Kennung für den Subagent	SubagentStart^TS, SubagentStop^TS
`agent_type`	`string`	Typ/Rolle des Subagents	SubagentStart^TS
`agent_transcript_path`	`string`	Pfad zum Gesprächstranskript des Subagents	SubagentStop^TS
`trigger`	`string`	Was die Komprimierung ausgelöst hat: `manual` oder `auto`	PreCompact
`custom_instructions`	`string`	Benutzerdefinierte Anweisungen für die Komprimierung	PreCompact
`permission_suggestions`	`array`	Vorgeschlagene Berechtigungsaktualisierungen für das Tool	PermissionRequest^TS
`source`	`string`	Wie die Sitzung gestartet wurde: `startup`, `resume`, `clear` oder `compact`	SessionStart^TS
`reason`	`string`	Warum die Sitzung endete: `clear`, `logout`, `prompt_input_exit`, `bypass_permissions_disabled` oder `other`	SessionEnd^TS
`message`	`string`	Statusmeldung vom Agent	Notification^TS
`notification_type`	`string`	Art der Benachrichtigung: `permission_prompt`, `idle_prompt`, `auth_success` oder `elicitation_dialog`	Notification^TS
`title`	`string`	Optionaler Titel, der vom Agent gesetzt wird	Notification^TS

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

Feld	Typ	Beschreibung
`continue`	`boolean`	Ob der Agent nach diesem Hook fortfahren soll (Standard: `true`)
`stopReason`	`string`	Meldung, die angezeigt wird, wenn `continue` `false` ist
`suppressOutput`	`boolean`	Stdout aus dem Transkript ausblenden (Standard: `false`)
`systemMessage`	`string`	Meldung, die in das Gespräch für Claude eingefügt wird

Feld	Typ	Hooks	Beschreibung
`hookEventName`	`string`	Alle	Erforderlich. Verwenden Sie `input.hook_event_name`, um das aktuelle Ereignis abzugleichen
`permissionDecision`	`'allow'` \| `'deny'` \| `'ask'`	PreToolUse	Steuert, ob das Tool ausgeführt wird
`permissionDecisionReason`	`string`	PreToolUse	Erklärung, die Claude für die Entscheidung angezeigt wird
`updatedInput`	`object`	PreToolUse	Geänderte Tool-Eingabe (erfordert `permissionDecision: 'allow'`)
`additionalContext`	`string`	PostToolUse, UserPromptSubmit, SessionStart^TS, SubagentStart^TS	Kontext, der zum Gespräch hinzugefügt wird

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

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

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

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

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

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

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

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

TypeScript

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

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

Stellen Sie sicher, dass updatedInput in hookSpecificOutput ist, nicht auf der obersten Ebene:

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

Sie müssen auch permissionDecision: 'allow' zurückgeben, damit die Eingabeänderung wirksam wird
Schließen Sie hookEventName in hookSpecificOutput ein, um zu identifizieren, welcher Hook-Typ die Ausgabe ist

Agent-Verhalten mit Hooks abfangen und steuern

Agent-Verhalten mit Hooks abfangen und steuern

Verfügbare Hooks

Häufige Anwendungsfälle

Hooks konfigurieren

Matcher

Callback-Funktionseingaben

Eingabedaten

Callback-Ausgaben

Berechtigungsentscheidungsfluss

Ein Tool blockieren

Tool-Eingabe ändern

Eine Systemnachricht hinzufügen

Spezifische Tools automatisch genehmigen

Erweiterte Szenarien handhaben

Mehrere Hooks verketten

Tool-spezifische Matcher mit Regex

Subagent-Aktivität verfolgen

Asynchrone Operationen in Hooks

Benachrichtigungen senden (nur TypeScript)

Häufige Probleme beheben

Hook wird nicht ausgelöst

Matcher filtert nicht wie erwartet

Hook-Timeout

Tool unerwartet blockiert

Geänderte Eingabe nicht angewendet

Sitzungs-Hooks nicht verfügbar

Subagent-Berechtigungsaufforderungen vervielfachen sich

Rekursive Hook-Schleifen mit Subagents

systemMessage erscheint nicht in der Ausgabe

Weitere Informationen