Agentverhalten mit Hooks abfangen und steuern

Fangen Sie Agentverhalten an wichtigen Ausführungspunkten mit Hooks ab und passen Sie es an

Hooks sind Callback-Funktionen, die Ihren Code als Reaktion auf Agent-Ereignisse ausführen, z. B. wenn ein Tool aufgerufen wird, eine Sitzung startet oder die Ausführung stoppt. Mit Hooks können Sie:

• Gefährliche Operationen blockieren, bevor sie ausgeführt werden, z. B. destruktive Shell-Befehle oder nicht autorisierter Dateizugriff
• Alle Tool-Aufrufe protokollieren und überprüfen für Compliance, Debugging oder Analytik
• Eingaben und Ausgaben transformieren, um Daten zu bereinigen, Anmeldedaten einzufügen oder Dateipfade umzuleiten
• Menschliche Genehmigung anfordern für sensible Aktionen wie Datenbankschreibvorgänge oder API-Aufrufe
• Sitzungslebenszyklus verfolgen, um den Status zu verwalten, Ressourcen freizugeben oder Benachrichtigungen zu senden

Funktionsweise von Hooks

Das folgende Beispiel bringt diese Schritte zusammen. Es registriert einen PreToolUse Hook (Schritt 1) mit einem "Write|Edit" Matcher (Schritt 3), sodass der Callback nur für Datei-Schreib-Tools ausgelöst wird. Wenn ausgelöst, erhält der Callback die Eingabe des Tools (Schritt 4), prüft, ob der Dateipfad auf eine .env-Datei abzielt, und gibt permissionDecision: "deny" zurück, um die Operation zu blockieren (Schritt 5):

import asyncio
from claude_agent_sdk import (
AssistantMessage,
ClaudeSDKClient,
ClaudeAgentOptions,
HookMatcher,
ResultMessage,
)


# 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():
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])]
}
)

async with ClaudeSDKClient(options=options) as client:
await client.query("Create a .env file with the standard local development database configuration")
async for message in client.receive_response():
# Filter for assistant and result messages
if isinstance(message, (AssistantMessage, ResultMessage)):
print(message)


asyncio.run(main())

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

// Define a hook callback with the HookCallback type
const protectEnvFiles: HookCallback = async (input, toolUseID, { signal }) => {
// Cast input to the specific hook type for type safety
const preInput = input as PreToolUseHookInput;

// Cast tool_input to access its properties (typed as unknown in the SDK)
const toolInput = preInput.tool_input as Record<string, unknown>;
const filePath = toolInput?.file_path as string;
const fileName = filePath?.split("/").pop();

// Block the operation if targeting a .env file
if (fileName === ".env") {
return {
hookSpecificOutput: {
hookEventName: preInput.hook_event_name,
permissionDecision: "deny",
permissionDecisionReason: "Cannot modify .env files"
}
};
}

// Return empty object to allow the operation
return {};
};

for await (const message of query({
prompt: "Create a .env file with the standard local development database configuration",
options: {
hooks: {
// Register the hook for PreToolUse events
// The matcher filters to only Write and Edit tool calls
PreToolUse: [{ matcher: "Write|Edit", hooks: [protectEnvFiles] }]
}
}
})) {
// Filter for assistant and result messages
if (message.type === "assistant" || message.type === "result") {
console.log(message);
}
}

Wenn Sie eines der Skripte ausführen, versucht Claude, die .env-Datei zu erstellen, der Hook verweigert den Tool-Aufruf, und Claudes endgültige Antwort erklärt, dass es keine .env-Dateien erstellen kann.

Verfügbare Hooks

Das SDK bietet Hooks für verschiedene Phasen der Agent-Ausführung. Einige Hooks sind in beiden SDKs verfügbar, während andere nur für TypeScript verfügbar sind.

Hooks konfigurieren

Um einen Hook zu konfigurieren, übergeben Sie ihn im hooks Feld Ihrer Agent-Optionen (ClaudeAgentOptions in Python, das options Objekt in TypeScript). Dieser Ausschnitt setzt voraus, dass Sie bereits einen Hook-Callback definiert haben, wie protect_env_files in Python oder protectEnvFiles in TypeScript aus dem obigen Beispiel:

options = ClaudeAgentOptions(
hooks={"PreToolUse": [HookMatcher(matcher="Bash", hooks=[my_callback])]}
)

async with ClaudeSDKClient(options=options) as client:
await client.query("Your prompt")
async for message in client.receive_response():
print(message)

for await (const message of query({
prompt: "Your prompt",
options: {
hooks: {
PreToolUse: [{ matcher: "Bash", hooks: [myCallback] }]
}
}
})) {
console.log(message);
}

Die hooks Option ist ein Wörterbuch in Python oder ein Objekt in TypeScript, wobei:

• Schlüssel: Hook-Ereignisnamen wie 'PreToolUse', 'PostToolUse' und 'Stop'
• Werte: Arrays von Matchern, die jeweils ein optionales Filtermuster und Ihre Callback-Funktionen enthalten

Matcher

Verwenden Sie Matcher, um zu filtern, wann Ihre Callbacks ausgelöst werden. Das matcher Feld wird gegen einen anderen Wert abgeglichen, je nach Hook-Ereignistyp. Beispielsweise werden Tool-basierte Hooks gegen den Tool-Namen abgeglichen, während Notification Hooks gegen den Benachrichtigungstyp abgeglichen werden.

SDK-Matcher folgen den gleichen Regeln wie Matcher in Einstellungsdateien. Dieser Abschnitt dokumentiert die Pfade für exakte Zeichenketten- und reguläre Ausdrucksbewertung, ihre Versionsanforderungen und die Matcher-Werte für jeden Ereignistyp.

Verwenden Sie das matcher Muster, um nach Möglichkeit spezifische Tools anzusteuern. Ein Matcher mit 'Bash' wird nur für Bash-Befehle ausgeführt, während das Weglassen des Musters Ihre Callbacks für jedes Vorkommen des Ereignisses ausführt. Lassen Sie es absichtlich weg, um jeden Tool-Aufruf Ihrer Sitzung zu protokollieren.

Callback-Funktionen

Eingaben

Jeder Hook-Callback erhält drei Argumente:

• Eingabedaten: ein typisiertes Objekt mit Ereignisdetails. Jeder Hook-Typ hat seine eigene Eingabeform. Beispielsweise enthält PreToolUseHookInput tool_name und tool_input, während NotificationHookInput message enthält. Siehe die vollständigen Typdefinitionen in den TypeScript und Python SDK-Referenzen.
  • Alle Hook-Eingaben teilen session_id, cwd und hook_event_name.
  • agent_id und agent_type werden ausgefüllt, wenn der Hook in einem Subagent ausgelöst wird. In TypeScript befinden sich diese in der Basis-Hook-Eingabe und sind für alle Hook-Typen verfügbar. In Python sind sie optionale Felder auf PreToolUse, PostToolUse, PostToolUseFailure und PermissionRequest, und erforderliche Felder auf SubagentStart und SubagentStop.
• Tool-Verwendungs-ID (str | None / string | undefined): korreliert PreToolUse und PostToolUse Ereignisse für denselben Tool-Aufruf.
• Kontext: In TypeScript enthält eine signal Eigenschaft (AbortSignal) für Abbruch. In Python ist dieses Argument für zukünftige Verwendung reserviert.

Ausgaben

Ihr Callback gibt ein Objekt mit zwei Kategorien von Feldern zurück:

• Top-Level-Felder werden bei jedem Ereignis akzeptiert: systemMessage zeigt eine Nachricht für den Benutzer an, und continue (continue_ in Python) bestimmt, ob der Agent nach diesem Hook weiterläuft. Einige Ereignisse verwerfen sie oder liefern sie an anderer Stelle. Jeder Abschnitt des Ereignisses auf der Hooks-Seite sagt, wo sie landen.
• hookSpecificOutput steuert die aktuelle Operation. Die Felder, die Sie darin setzen, hängen vom Hook-Ereignistyp ab:
  • Für PreToolUse Hooks ist dies der Ort, an dem Sie permissionDecision ("allow", "deny", "ask" oder "defer"), permissionDecisionReason und updatedInput setzen. Wenn Sie "defer" zurückgeben, endet die Abfrage, damit Sie sie später fortsetzen können.
  • Für PostToolUse Hooks können Sie additionalContext setzen, um Informationen zum Tool-Ergebnis anzuhängen. Um die Ausgabe des Tools vor Claude zu ersetzen, setzen Sie updatedToolOutput, das für jedes Tool in beiden SDKs funktioniert. Das ältere updatedMCPToolOutput Feld ersetzt nur MCP-Tool-Ausgabe und ist veraltet.
  • Im TypeScript SDK kann ein PostToolUse Callback auch classifierContext zurückgeben, eine kurze Notiz über das Ergebnis des Tool-Aufrufs für den Auto-Modus Berechtigungsklassifizierer. Da Ihr Callback in Ihrem eigenen Anwendungsprozess ausgeführt wird, kann der Klassifizierer eine Benutzeraussage, die Sie in der Notiz weitergeben, als Benutzerabsicht gewichten. Das Feld erfordert TypeScript Agent SDK v0.3.236 oder später. Annotieren Sie ein Ergebnis für den Auto-Modus Klassifizierer behandelt die Längenbegrenzung, die Nur-Synchron-Regel und was nicht in die Notiz gehört.

Geben Sie {} zurück, um die Operation ohne Änderungen zuzulassen. SDK-Callback-Hooks verwenden das gleiche JSON-Ausgabeformat wie Claude Code Shell-Befehls-Hooks, das jedes Feld und ereignisspezifische Option dokumentiert. Für die SDK-Typdefinitionen siehe die TypeScript und Python SDK-Referenzen.

Asynchrone Ausgabe

Standardmäßig wartet der Agent darauf, dass Ihr Hook zurückkommt, bevor er fortfährt. Wenn Ihr Hook einen Nebeneffekt ausführt, wie Protokollierung oder Webhook-Versand, und das Verhalten des Agenten nicht beeinflussen muss, können Sie stattdessen eine asynchrone Ausgabe zurückgeben. Dies teilt dem Agent mit, dass er sofort fortfahren soll, ohne auf die Fertigstellung des Hooks zu warten. In diesem Ausschnitt stehen send_to_logging_service in Python und sendToLoggingService in TypeScript für jede Protokollierungsfunktion, die Sie definieren:

async def async_hook(input_data, tool_use_id, context):
# Start a background task, then return immediately
asyncio.create_task(send_to_logging_service(input_data))
return {"async_": True, "asyncTimeout": 30000}

const asyncHook: HookCallback = async (input, toolUseID, { signal }) => {
// Start a background task, then return immediately
sendToLoggingService(input).catch(console.error);
return { async: true, asyncTimeout: 30000 };
};

Beispiele

Mehrere Beispiele in diesem Abschnitt zeigen nur die Callback-Funktion. Um eines auszuführen, registrieren Sie den Callback unter dem entsprechenden Ereignis im hooks Feld Ihrer Optionen, wie in Hooks konfigurieren gezeigt.

Tool-Eingabe ändern

Dieses Beispiel fängt Write-Tool-Aufrufe ab und schreibt das file_path Argument um, um /sandbox voranzustellen, wodurch alle Datei-Schreibvorgänge in ein Sandbox-Verzeichnis umgeleitet werden. Der Callback gibt updatedInput mit dem geänderten Pfad und permissionDecision: 'allow' zurück, um die umgeschriebene Operation automatisch zu genehmigen:

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

const redirectToSandbox: HookCallback = async (input, toolUseID, { signal }) => {
if (input.hook_event_name !== "PreToolUse") return {};

const preInput = input as PreToolUseHookInput;
const toolInput = preInput.tool_input as Record<string, unknown>;
if (preInput.tool_name === "Write") {
const originalPath = toolInput.file_path as string;
return {
hookSpecificOutput: {
hookEventName: preInput.hook_event_name,
permissionDecision: "allow",
updatedInput: {
...toolInput,
file_path: `/sandbox${originalPath}`
}
}
};
}
return {};
};

Um die Umleitung zu bestätigen, setzen Sie das Präfix auf einen Pfad, in den Sie schreiben können, z. B. ./sandbox oder /tmp/sandbox (macOS erlaubt nicht das Erstellen eines Root-Level /sandbox Verzeichnisses), und bitten Sie dann den Agent, eine Datei zu schreiben: Das Ergebnis des Write-Tools im Nachrichtenstrom nennt den Pfad mit Ihrem Sandbox-Präfix anstelle des von Claude angeforderten.

Kontext hinzufügen und ein Tool blockieren

Dieses Beispiel blockiert Schreibvorgänge in das /etc Verzeichnis und erklärt den Grund sowohl dem Modell als auch dem Benutzer:

• permissionDecision: 'deny' stoppt den Tool-Aufruf.
• permissionDecisionReason teilt dem Modell mit, warum, damit es nicht erneut versucht.
• systemMessage zeigt dem Benutzer, was passiert ist.

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: message shown to the user
"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 {}

const blockEtcWrites: HookCallback = async (input, toolUseID, { signal }) => {
const preInput = input as PreToolUseHookInput;
const toolInput = preInput.tool_input as Record<string, unknown>;
const filePath = toolInput?.file_path as string;

if (filePath?.startsWith("/etc")) {
return {
// Top-level field: message shown to the user
systemMessage: "Remember: system directories like /etc are protected.",
// hookSpecificOutput: block the operation
hookSpecificOutput: {
hookEventName: preInput.hook_event_name,
permissionDecision: "deny",
permissionDecisionReason: "Writing to /etc is not allowed"
}
};
}
return {};
};

Spezifische Tools automatisch genehmigen

Standardmäßig kann der Agent vor der Verwendung bestimmter Tools um Genehmigung bitten. Dieses Beispiel genehmigt schreibgeschützte Dateisystem-Tools (Read, Glob, Grep) automatisch, indem permissionDecision: 'allow' zurückgegeben wird, sodass sie ohne Benutzerbestätigung ausgeführt werden, während alle anderen Tools normalen Berechtigungsprüfungen unterliegen:

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

const autoApproveReadOnly: HookCallback = async (input, toolUseID, { signal }) => {
if (input.hook_event_name !== "PreToolUse") return {};

const preInput = input as PreToolUseHookInput;
const readOnlyTools = ["Read", "Glob", "Grep"];
if (readOnlyTools.includes(preInput.tool_name)) {
return {
hookSpecificOutput: {
hookEventName: preInput.hook_event_name,
permissionDecision: "allow",
permissionDecisionReason: "Read-only tool auto-approved"
}
};
}
return {};
};

Mehrere Hooks registrieren

Wenn ein Ereignis ausgelöst wird, werden alle übereinstimmenden Hooks parallel ausgeführt. Bei Berechtigungsentscheidungen gewinnt das restriktivste Ergebnis: Ein einzelnes deny blockiert den Tool-Aufruf, unabhängig davon, was die anderen Hooks zurückgeben. Da die Abschlussreihenfolge nicht deterministisch ist, schreiben Sie jeden Hook so, dass er unabhängig agiert, anstatt sich darauf zu verlassen, dass ein anderer Hook zuerst ausgeführt wurde.

Das folgende Beispiel registriert drei unabhängige Prüfungen für jeden Tool-Aufruf:

options = ClaudeAgentOptions(
hooks={
"PreToolUse": [
HookMatcher(hooks=[authorization_check]),
HookMatcher(hooks=[input_validator]),
HookMatcher(hooks=[audit_logger]),
]
}
)

const options = {
hooks: {
PreToolUse: [
{ hooks: [authorizationCheck] },
{ hooks: [inputValidator] },
{ hooks: [auditLogger] }
]
}
};

Mit Multi-Tool-Matchern filtern

Verwenden Sie Multi-Tool-Matcher, um einen Callback über verwandte Tools hinweg zu teilen. Dieses Beispiel registriert drei Matcher mit unterschiedlichen Bereichen:

• Eine durch Pipe getrennte exakte Liste (Write|Edit|NotebookEdit) löst file_security_hook nur für Datei-Änderungs-Tools aus.
• Ein Regex (^mcp__) löst mcp_audit_hook für alle MCP-Tools aus, deren Namen mit mcp__ beginnen.
• Ein weggelassener Matcher löst global_logger für jeden Tool-Aufruf unabhängig vom Namen aus.

options = ClaudeAgentOptions(
hooks={
"PreToolUse": [
# Match file modification tools
HookMatcher(matcher="Write|Edit|NotebookEdit", hooks=[file_security_hook]),
# Match all MCP tools
HookMatcher(matcher="^mcp__", hooks=[mcp_audit_hook]),
# Match everything (no matcher)
HookMatcher(hooks=[global_logger]),
]
}
)

const options = {
hooks: {
PreToolUse: [
// Match file modification tools
{ matcher: "Write|Edit|NotebookEdit", hooks: [fileSecurityHook] },

// Match all MCP tools
{ matcher: "^mcp__", hooks: [mcpAuditHook] },

// Match everything (no matcher)
{ hooks: [globalLogger] }
]
}
};

Subagent-Aktivität verfolgen

Verwenden Sie SubagentStop Hooks, um zu überwachen, wenn Subagents ihre Arbeit beenden. Siehe den vollständigen Eingabetyp in den TypeScript und Python SDK-Referenzen. Dieses Beispiel protokolliert eine Zusammenfassung jedes Mal, wenn ein Subagent abgeschlossen wird:

async def subagent_tracker(input_data, tool_use_id, context):
# Log subagent details when it finishes
print(f"[SUBAGENT] Completed: {input_data['agent_id']}")
print(f"  Transcript: {input_data['agent_transcript_path']}")
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 { HookCallback, SubagentStopHookInput } from "@anthropic-ai/claude-agent-sdk";

const subagentTracker: HookCallback = async (input, toolUseID, { signal }) => {
// Cast to SubagentStopHookInput to access subagent-specific fields
const subInput = input as SubagentStopHookInput;

// Log subagent details when it finishes
console.log(`[SUBAGENT] Completed: ${subInput.agent_id}`);
console.log(`  Transcript: ${subInput.agent_transcript_path}`);
console.log(`  Tool use ID: ${toolUseID}`);
console.log(`  Stop hook active: ${subInput.stop_hook_active}`);
return {};
};

const options = {
hooks: {
SubagentStop: [{ hooks: [subagentTracker] }]
}
};

HTTP-Anfragen von Hooks aus stellen

Hooks können asynchrone Operationen wie HTTP-Anfragen ausführen. Fangen Sie Fehler in Ihrem Hook ab, anstatt sie zu propagieren.

Dieses Beispiel sendet einen Webhook nach jeder Tool-Fertigstellung und protokolliert, welches Tool ausgeführt wurde und wann. Der Hook fängt Fehler von einem fehlgeschlagenen Webhook ab:

import asyncio
import json
import urllib.request
from datetime import datetime


def _send_webhook(tool_name):
"""Synchronous helper that POSTs tool usage data to an external webhook."""
data = json.dumps(
{
"tool": tool_name,
"timestamp": datetime.now().isoformat(),
}
).encode()
req = urllib.request.Request(
"https://api.example.com/webhook",
data=data,
headers={"Content-Type": "application/json"},
method="POST",
)
urllib.request.urlopen(req)


async def webhook_notifier(input_data, tool_use_id, context):
# Only fire after a tool completes (PostToolUse), not before
if input_data["hook_event_name"] != "PostToolUse":
return {}

try:
# Run the blocking HTTP call in a thread to avoid blocking the event loop
await asyncio.to_thread(_send_webhook, input_data["tool_name"])
except Exception as e:
# Log the error but don't raise
print(f"Webhook request failed: {e}")

return {}

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

const webhookNotifier: HookCallback = async (input, toolUseID, { signal }) => {
// Only fire after a tool completes (PostToolUse), not before
if (input.hook_event_name !== "PostToolUse") return {};

try {
await fetch("https://api.example.com/webhook", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
tool: (input as PostToolUseHookInput).tool_name,
timestamp: new Date().toISOString()
}),
// Pass signal so the request cancels if the hook times out
signal
});
} catch (error) {
// Handle cancellation separately from other errors
if (error instanceof Error && error.name === "AbortError") {
console.log("Webhook request cancelled");
}
// Don't re-throw
}

return {};
};

// Register as a PostToolUse hook
for await (const message of query({
prompt: "Refactor the auth module",
options: {
hooks: {
PostToolUse: [{ hooks: [webhookNotifier] }]
}
}
})) {
console.log(message);
}

Um zu bestätigen, dass der Hook ausgelöst wird, verweisen Sie die Webhook-URL auf einen Endpunkt, den Sie überwachen können, und senden Sie eine Eingabeaufforderung, die ein Tool verwendet: Der Hook sendet einen POST mit dem Tool-Namen und dem Zeitstempel nach jeder Tool-Fertigstellung.

Benachrichtigungen an Slack weiterleiten

Verwenden Sie Notification Hooks, um Systembenachrichtigungen vom Agent zu empfangen und sie an externe Dienste weiterzuleiten. In SDK-Sitzungen führt Claude Code diesen Hook für die folgenden Benachrichtigungstypen aus:

• permission_prompt sobald eine Berechtigungsanfrage etwa sechs Sekunden auf Ihrem canUseTool Callback gewartet hat. Erfordert TypeScript Agent SDK v0.3.233 oder später oder Python Agent SDK v0.2.139 oder später
• elicitation_complete und elicitation_response für Benutzer-Abfrage-Flows

Claude Code gibt die anderen Typen aus, wie idle_prompt, auth_success und elicitation_dialog, aus interaktiver Benutzeroberfläche, die SDK-Sitzungen nicht ausführen.

Jede Benachrichtigung enthält ein message Feld mit einer für Menschen lesbaren Beschreibung und optional einen title.

Dieses Beispiel leitet jede Benachrichtigung an einen Slack-Kanal weiter. Es erfordert eine Slack Incoming Webhook URL, die Sie erstellen, indem Sie eine App zu Ihrem Slack-Workspace hinzufügen und Incoming Webhooks aktivieren:

import asyncio
import json
import urllib.request

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, HookMatcher


def _send_slack_notification(message):
"""Synchronous helper that sends a message to Slack via incoming webhook."""
data = json.dumps({"text": f"Agent status: {message}"}).encode()
req = urllib.request.Request(
"https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
data=data,
headers={"Content-Type": "application/json"},
method="POST",
)
urllib.request.urlopen(req)


async def notification_handler(input_data, tool_use_id, context):
try:
# Run the blocking HTTP call in a thread to avoid blocking the event loop
await asyncio.to_thread(_send_slack_notification, input_data.get("message", ""))
except Exception as e:
print(f"Failed to send notification: {e}")

# Return empty object. Notification hooks don't modify agent behavior
return {}


async def main():
options = ClaudeAgentOptions(
hooks={
# Register the hook for Notification events (no matcher needed)
"Notification": [HookMatcher(hooks=[notification_handler])],
},
)

async with ClaudeSDKClient(options=options) as client:
await client.query("Analyze this codebase")
async for message in client.receive_response():
print(message)


asyncio.run(main())

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

// Define a hook callback that sends notifications to Slack
const notificationHandler: HookCallback = async (input, toolUseID, { signal }) => {
// Cast to NotificationHookInput to access the message field
const notification = input as NotificationHookInput;

try {
// POST the notification message to a Slack incoming webhook
await fetch("https://hooks.slack.com/services/YOUR/WEBHOOK/URL", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
text: `Agent status: ${notification.message}`
}),
// Pass signal so the request cancels if the hook times out
signal
});
} catch (error) {
if (error instanceof Error && error.name === "AbortError") {
console.log("Notification cancelled");
} else {
console.error("Failed to send notification:", error);
}
}

// Return empty object. Notification hooks don't modify agent behavior
return {};
};

// Register the hook for Notification events (no matcher needed)
for await (const message of query({
prompt: "Analyze this codebase",
options: {
hooks: {
Notification: [{ hooks: [notificationHandler] }]
}
}
})) {
console.log(message);
}

Wenn ein Notification Ereignis ausgelöst wird, sendet der Hook die message der Benachrichtigung, mit dem Präfix Agent status:, an den Kanal, auf den Ihr Webhook abzielt.

Häufige Probleme beheben

Hook wird nicht ausgelöst

• Überprüfen Sie, ob der Hook-Ereignisname korrekt und case-sensitiv ist (PreToolUse, nicht preToolUse)
• Überprüfen Sie, ob Ihr Matcher-Muster den Tool-Namen genau abgleicht
• Stellen Sie sicher, dass der Hook unter dem richtigen Ereignistyp in options.hooks ist
• Für Nicht-Tool-Hooks, die Matcher unterstützen, wie Notification und SubagentStop, gleichen Matcher gegen verschiedene Felder ab, und Stop ignoriert Matcher vollständig (siehe Matcher-Muster)
• Hooks werden möglicherweise nicht ausgelöst, wenn der Agent das max_turns Limit erreicht, da die Sitzung endet, bevor Hooks ausgeführt werden können

Matcher filtert nicht wie erwartet

Matcher gleichen nur Tool-Namen ab, nicht Dateipfade oder andere Argumente. Um nach Dateipfad zu filtern, prüfen Sie tool_input.file_path in Ihrem Hook:

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

Hook-Timeout

Claude Code führt jeden Callback mit einem Timeout aus, den Sie in Sekunden mit dem Feld timeout auf seinem HookMatcher festlegen. Wenn Sie keinen festlegen, verwendet Claude Code den Standard des Ereignisses: 600 Sekunden für die meisten Ereignisse, 30 Sekunden für UserPromptSubmit, PreModelSwitch und PostModelSwitch, und 10 Sekunden für MessageDisplay. Claude Code führt SessionEnd Callbacks während des Herunterfahrens unter dem kürzeren SessionEnd-Timeout-Budget aus, standardmäßig 1,5 Sekunden.

Wenn ein Callback sein Timeout überschreitet, bricht Claude Code es ab und verwirft seine Ausgabe, und die Sitzung wird fortgesetzt, anstatt zu hängen. Was danach passiert, hängt vom Ereignis ab:

• PreToolUse: Claude Code führt den Tool-Aufruf nicht aus, Claude erhält ein Tool-Ergebnis, das besagt, dass der Hook nicht vor seinem Timeout geantwortet hat, und der Turn wird fortgesetzt. Wenn ein anderer PreToolUse Hook eine explizite Ablehnung zurückgegeben hat, erhält Claude stattdessen diese Ablehnung. Vor v2.1.210 meldete Claude Code das Timeout an Claude als Benutzerabweisung, was unbeaufsichtigte Sitzungen zum Stoppen und Warten auf Eingabe führte.
• PostToolUse und PostToolUseFailure: Claude Code behält das Tool-Ergebnis bei und der Turn wird fortgesetzt.
• UserPromptSubmit und UserPromptExpansion: Claude Code blockiert die Aufforderung mit einer Nachricht, die den Hook und das Timeout benennt, und die Sitzung wird fortgesetzt. Da ein Callback bei diesen Ereignissen als Richtlinien-Gate fungieren kann, lässt Claude Code niemals eine abgelaufene Aufforderung ungeprüft durch. Vor v2.1.208 endete Claude Code die Abfrage mit error_during_execution, wenn ein Callback bei diesen Ereignissen abgelaufen ist.
• Stop und SubagentStop: der abgelaufene Callback zählt als Rückgabe ohne Entscheidung. Der Agent oder Subagent stoppt, als hätte dieser Callback es erlaubt, und eine Entscheidung von Ihren anderen Hooks bei dem Ereignis wird immer noch angewendet. Vor Claude Code v2.1.273 zählte ein abgelaufener Stop oder SubagentStop Callback als fehlgeschlagener Hook-Lauf, und Claude Code verwarf die Entscheidungen Ihrer anderen Hooks bei dem Ereignis.
• SessionStart: der abgelaufene Callback zählt als Rückgabe ohne Ausgabe, und die Sitzung wird mit der Ausgabe Ihrer anderen SessionStart Hooks fortgesetzt.
• PreModelSwitch: Claude Code blockiert den Modellwechsel. Ein Hook, der nicht antwortet, hat den Wechsel nicht genehmigt.
• Andere Ereignisse, wie Notification, PreCompact und PostModelSwitch: Claude Code protokolliert den Fehler und wird fortgesetzt.

Das erste Mal, wenn ein Stop oder SessionStart Callback in der Hauptsitzung abläuft, fügt Claude Code auch eine SDKInformationalMessage zum Nachrichtenstrom hinzu, die besagt, dass die App, die die Sitzung steuert, nicht geantwortet hat. Spätere Timeouts wiederholen diese Nachricht nicht, während Ihre App nicht reagiert.

Wenn Sie die Abfrage unterbrechen, während ein Callback ausstehend ist, bricht Claude Code den ausstehenden Tool-Aufruf ab. Vor v2.1.208 konnte der Tool-Aufruf noch fortfahren, wenn Sie während eines ausstehenden PreToolUse Callbacks unterbrochen haben.

Wenn Ihr Callback mehr Zeit benötigt, legen Sie einen höheren timeout auf seinem HookMatcher fest. In TypeScript verwenden Sie das AbortSignal aus dem dritten Callback-Argument, um Abbruch elegant zu behandeln, wenn das Timeout abläuft.

Tool wird unerwartet blockiert

• Überprüfen Sie alle PreToolUse Hooks auf permissionDecision: 'deny' Rückgaben
• Fügen Sie Protokollierung zu Ihren Hooks hinzu, um zu sehen, welche permissionDecisionReason sie zurückgeben
• Überprüfen Sie, ob Matcher-Muster nicht zu breit sind: ein leerer Matcher gleicht alle Tools ab

Geänderte Eingabe wird nicht angewendet

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

  return {
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "allow",
      updatedInput: { command: "new command" }
    }
  };
  

• Kombinieren Sie updatedInput nicht mit permissionDecision: 'defer', das die geänderte Eingabe verwirft. Das Weglassen von permissionDecision ist in Ordnung: die geänderte Eingabe wird immer noch durch die normale Berechtigungsevaluierung angewendet. Sie können auch 'allow' zurückgeben, um die geänderte Eingabe automatisch zu genehmigen, oder 'ask', um sie dem Benutzer zur Genehmigung anzuzeigen

• Schließen Sie hookEventName in hookSpecificOutput ein, um zu identifizieren, für welchen Hook-Typ die Ausgabe bestimmt ist

Sitzungs-Hooks nicht in Python verfügbar

SessionStart und SessionEnd können als SDK-Callback-Hooks in TypeScript registriert werden, sind aber im Python SDK nicht verfügbar, da sein HookEvent Typ sie auslässt. In Python sind sie nur als Shell-Befehls-Hooks verfügbar, die in Einstellungsdateien wie .claude/settings.json definiert sind. Um Shell-Befehls-Hooks aus Ihrer SDK-Anwendung zu laden, schließen Sie die entsprechende Einstellungsquelle mit setting_sources oder settingSources ein:

options = ClaudeAgentOptions(
setting_sources=["project"],  # Loads .claude/settings.json including hooks
)

const options = {
settingSources: ["project"] // Loads .claude/settings.json including hooks
};

Um stattdessen Initialisierungslogik als Python SDK-Callback auszuführen, verwenden Sie die erste Nachricht von client.receive_response() als Auslöser.

Subagent-Berechtigungsaufforderungen vervielfachen sich

Beim Spawnen mehrerer Subagents kann jeder einzelne Berechtigungen separat anfordern. Um wiederholte Aufforderungen zu vermeiden, verwenden Sie PreToolUse Hooks, um spezifische Tools automatisch zu genehmigen, oder konfigurieren Sie Berechtigungsregeln, die Subagents vom übergeordneten Gespräch erben.

Rekursive Hook-Schleifen mit Subagents

Ein UserPromptSubmit Hook, der Subagents spawnt, kann unendliche Schleifen erzeugen, wenn diese Subagents denselben Hook auslösen. Um dies zu verhindern:

• Verwenden Sie eine gemeinsame Variable oder Sitzungsstatus, um zu verfolgen, ob Sie bereits in einem Subagent sind
• Beschränken Sie Hooks so, dass sie nur für die Top-Level-Agent-Sitzung ausgeführt werden

systemMessage wird nicht in der Ausgabe angezeigt

Das systemMessage Feld zeigt eine Nachricht für den Benutzer an, nicht für das Modell. Auf Claude Code v2.1.227 oder später kann die systemMessage eines Hooks in dem Nachrichtenstrom als SDKInformationalMessage auftauchen. Ob dies der Fall ist, hängt vom Ereignis ab. Der Abschnitt jedes Ereignisses auf der Hooks-Seite sagt, wie die Ausgabe auftaucht. Um stattdessen Kontext an das Modell zu übergeben, geben Sie additionalContext zurück.

Vor v2.1.227 gab das SDK Hook-Ausgaben im Nachrichtenstrom nur für SessionStart und Setup Hooks aus. Für jedes andere Ereignis erschien die Ausgabe nur in den Lebenszyklusereignissen, die includeHookEvents (include_hook_events in Python) hinzufügt. Der Eintrag dieser Option behandelt, welche Lebenszyklusereignisse jedes Hook-Ereignis erzeugt.

Wenn Sie Hook-Entscheidungen für Ihre Anwendung zuverlässig sichtbar machen müssen, protokollieren Sie sie separat oder verwenden Sie einen dedizierten Ausgabekanal.

Verwandte Ressourcen

• Claude Code Hooks-Referenz: vollständige JSON-Eingabe-/Ausgabeschemas, Ereignisdokumentation und Matcher-Muster
• Claude Code Hooks-Leitfaden: Shell-Befehls-Hook-Beispiele und Walkthroughs
• TypeScript SDK-Referenz: Hook-Typen, Eingabe-/Ausgabedefinitionen und Konfigurationsoptionen
• Python SDK-Referenz: Hook-Typen, Eingabe-/Ausgabedefinitionen und Konfigurationsoptionen
• Berechtigungen: Steuern Sie, was Ihr Agent tun kann
• Benutzerdefinierte Tools: Erstellen Sie Tools, um Agent-Funktionen zu erweitern