SpyBara
Go Premium

agent-sdk/hooks.md 2026-06-29 23:02 UTC to 2026-06-30 23:02 UTC

21 added, 13 removed.

2026
Tue 30 23:02 Mon 29 23:02 Sat 27 01:01 Fri 26 23:00 Thu 25 23:58 Wed 24 22:02 Tue 23 22:00 Mon 22 23:59 Fri 19 22:58 Thu 18 22:00 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

Intercept dan kontrol perilaku agent dengan hooks

Intercept dan customize perilaku agent pada titik eksekusi kunci dengan hooks

Hooks adalah fungsi callback yang menjalankan kode Anda sebagai respons terhadap peristiwa agent, seperti tool yang dipanggil, sesi dimulai, atau eksekusi berhenti. Dengan hooks, Anda dapat:

  • Blokir operasi berbahaya sebelum dieksekusi, seperti perintah shell yang merusak atau akses file yang tidak sah
  • Log dan audit setiap pemanggilan tool untuk kepatuhan, debugging, atau analitik
  • Transform input dan output untuk membersihkan data, menyuntikkan kredensial, atau mengalihkan jalur file
  • Memerlukan persetujuan manusia untuk tindakan sensitif seperti penulisan database atau panggilan API
  • Track lifecycle sesi untuk mengelola state, membersihkan resources, atau mengirim notifikasi

Panduan ini mencakup cara kerja hooks, cara mengonfigurasinya, dan menyediakan contoh untuk pola umum seperti memblokir tools, memodifikasi input, dan meneruskan notifikasi.

Cara kerja hooks

1

Sebuah event terjadi

Sesuatu terjadi selama eksekusi agent dan SDK menembakkan event: tool akan dipanggil (PreToolUse), tool mengembalikan hasil (PostToolUse), subagent dimulai atau berhenti, agent idle, atau eksekusi selesai. Lihat daftar lengkap events.

2

SDK mengumpulkan hooks terdaftar

SDK memeriksa hooks yang terdaftar untuk tipe event tersebut. Ini termasuk callback hooks yang Anda berikan di options.hooks dan shell command hooks dari file pengaturan ketika settingSources atau setting_sources entry yang sesuai diaktifkan, yang mana untuk opsi query() default.

3

Matchers memfilter hooks mana yang berjalan

Jika hook memiliki pola matcher (seperti "Write|Edit"), SDK mengujinya terhadap target event (misalnya, nama tool). Hooks tanpa matcher berjalan untuk setiap event dari tipe tersebut.

4

Fungsi callback dieksekusi

Setiap fungsi callback hook yang cocok menerima input tentang apa yang terjadi: nama tool, argumennya, ID sesi, dan detail spesifik event lainnya.

5

Callback Anda mengembalikan keputusan

Setelah melakukan operasi apa pun (logging, panggilan API, validasi), callback Anda mengembalikan output object yang memberi tahu agent apa yang harus dilakukan: izinkan operasi, blokir, modifikasi input, atau suntikkan konteks ke dalam percakapan.

Contoh berikut menyatukan langkah-langkah ini. Ini mendaftarkan hook PreToolUse (langkah 1) dengan matcher "Write|Edit" (langkah 3) sehingga callback hanya terjadi untuk tools penulisan file. Ketika dipicu, callback menerima input tool (langkah 4), memeriksa apakah jalur file menargetkan file .env, dan mengembalikan permissionDecision: "deny" untuk memblokir operasi (langkah 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("Update the 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())

Available hooks

SDK menyediakan hooks untuk tahap berbeda dari eksekusi agent. Beberapa hooks tersedia di kedua SDK, sementara yang lain hanya TypeScript.

Hook Event Python SDK TypeScript SDK Apa yang memicunya Contoh use case
PreToolUse Ya Ya Permintaan pemanggilan tool (dapat memblokir atau memodifikasi) Blokir perintah shell berbahaya
PostToolUse Ya Ya Hasil eksekusi tool Log semua perubahan file ke audit trail
PostToolUseFailure Ya Ya Kegagalan eksekusi tool Tangani atau log kesalahan tool
PostToolBatch Tidak Ya Batch lengkap pemanggilan tool terselesaikan, sekali per batch sebelum panggilan model berikutnya Suntikkan konvensi sekali untuk seluruh batch
UserPromptSubmit Ya Ya Pengajuan prompt pengguna Suntikkan konteks tambahan ke dalam prompts
MessageDisplay Tidak Ya Pesan asisten dengan teks selesai, sekali per pesan dengan teks pesan lengkap Redaksi atau format ulang teks yang ditampilkan tanpa mengubah transcript
Stop Ya Ya Penghentian eksekusi agent Simpan state sesi sebelum keluar
SubagentStart Ya Ya Inisialisasi subagent Track spawning tugas paralel
SubagentStop Ya Ya Penyelesaian subagent Agregasi hasil dari tugas paralel
PreCompact Ya Ya Permintaan compaction percakapan Arsipkan transcript lengkap sebelum merangkum
PermissionRequest Ya Ya Dialog permission akan ditampilkan Custom permission handling
SessionStart Tidak Ya Inisialisasi sesi Inisialisasi logging dan telemetry
SessionEnd Tidak Ya Penghentian sesi Bersihkan resources sementara
Notification Ya Ya Pesan status agent Kirim update status agent ke Slack atau PagerDuty
Setup Tidak Ya Setup/maintenance sesi Jalankan tugas inisialisasi
TeammateIdle Tidak Ya Teammate menjadi idle Reassign pekerjaan atau notifikasi
TaskCompleted Tidak Ya Background task selesai Agregasi hasil dari tugas paralel
ConfigChange Tidak Ya File konfigurasi berubah Reload pengaturan secara dinamis
WorktreeCreate Tidak Ya Git worktree dibuat Track isolated workspaces
WorktreeRemove Tidak Ya Git worktree dihapus Bersihkan workspace resources

Konfigurasi hooks

Untuk mengonfigurasi hook, berikan di field hooks dari opsi agent Anda (ClaudeAgentOptions di Python, object options di TypeScript):

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)

Opsi hooks adalah dictionary di Python atau object di TypeScript, di mana:

Matchers

Gunakan matchers untuk memfilter kapan callbacks Anda terjadi. Field matcher cocok dengan nilai berbeda tergantung pada tipe hook event. Misalnya, tool-based hooks cocok dengan nama tool, sementara hooks Notification cocok dengan tipe notifikasi. Lihat referensi hooks Claude Code untuk daftar lengkap nilai matcher untuk setiap tipe event.

SDK matchers mengikuti aturan yang sama dengan matchers dalam file settings. Matcher yang hanya berisi huruf, digit, _, -, spasi, ,, dan | dibandingkan sebagai string yang tepat, dengan alternatif dipisahkan oleh | atau , dan spasi putih opsional di sekitarnya, jadi Write|Edit dan Write, Edit masing-masing cocok dengan tepat kedua tools tersebut dan code-reviewer cocok hanya dengan tipe agent tersebut. Matcher *, string kosong, atau menghilangkan matcher sepenuhnya cocok dengan setiap kemunculan event.

Matcher yang berisi karakter lain apa pun dievaluasi sebagai regular expression yang tidak berlabuh, jadi ^mcp__ cocok dengan setiap MCP tool dan Edit.* cocok dengan baik Edit maupun NotebookEdit. Bungkus regular expression dalam ^ dan $ ketika Anda memerlukan pencocokan seluruh string.

Matcher seperti mcp__memory atau mcp__brave-search hanya berisi karakter pencocokan yang tepat, jadi dibandingkan sebagai string yang tepat dan tidak cocok dengan tool apa pun; gunakan mcp__memory__.* untuk cocok dengan setiap tool dari server tersebut.

Tanda hubung dalam set pencocokan yang tepat memerlukan runtime Claude Code v2.1.195 atau lebih baru. Pada versi sebelumnya, nama dengan tanda hubung seperti code-reviewer dievaluasi sebagai regular expression yang tidak berlabuh dan harus berlabuh sebagai ^code-reviewer$ untuk cocok dengan tepat.

Option Type Default Description
matcher string undefined Pola yang cocok dengan field filter event, mengikuti aturan perbandingan di atas. Untuk tool hooks, ini adalah nama tool. Built-in tools termasuk Bash, Read, Write, Edit, Glob, Grep, WebFetch, Agent, dan lainnya (lihat Tool Input Types untuk daftar lengkap). MCP tools menggunakan pola mcp__<server>__<action>.
hooks HookCallback[] - Diperlukan. Array dari fungsi callback untuk dieksekusi ketika pola cocok
timeout number 60 Timeout dalam detik

Gunakan pola matcher untuk menargetkan tools spesifik kapan pun memungkinkan. Matcher dengan 'Bash' hanya berjalan untuk perintah Bash, sementara menghilangkan pola menjalankan callbacks Anda untuk setiap kemunculan event.

Untuk tool-based hooks, matchers hanya memfilter berdasarkan nama tool, bukan jalur file atau argumen lainnya. Untuk memfilter berdasarkan jalur file, periksa tool_input.file_path di dalam callback Anda.

Callback functions

Inputs

Setiap hook callback menerima tiga argumen:

  • Input data: object yang diketik berisi detail event. Setiap tipe hook memiliki bentuk input sendiri. Misalnya, PreToolUseHookInput mencakup tool_name dan tool_input, sementara NotificationHookInput mencakup message. Lihat definisi tipe lengkap di referensi SDK TypeScript dan Python.
    • Semua hook inputs berbagi session_id, cwd, dan hook_event_name.
    • agent_id dan agent_type diisi ketika hook terjadi di dalam subagent. Di TypeScript, ini berada di base hook input dan tersedia untuk semua tipe hook. Di Python, ini hanya ada di PreToolUse, PostToolUse, dan PostToolUseFailure.
  • Tool use ID (str | None / string | undefined): mengkorelasikan events PreToolUse dan PostToolUse untuk pemanggilan tool yang sama.
  • Context: di TypeScript, berisi property signal (AbortSignal) untuk pembatalan. Di Python, argumen ini dicadangkan untuk penggunaan di masa depan.

Outputs

Callback Anda mengembalikan object dengan dua kategori fields:

  • Top-level fields bekerja sama pada setiap event: systemMessage menampilkan pesan kepada pengguna, dan continue (continue_ di Python) menentukan apakah agent terus berjalan setelah hook ini.
  • hookSpecificOutput mengontrol operasi saat ini. Fields di dalamnya tergantung pada tipe hook event. Untuk hooks PreToolUse, di sinilah Anda menetapkan permissionDecision ("allow", "deny", "ask", atau "defer"), permissionDecisionReason, dan updatedInput. Mengembalikan "defer" mengakhiri query sehingga Anda dapat melanjutkannya nanti. Untuk hooks PostToolUse, Anda dapat menetapkan additionalContext untuk menambahkan informasi ke hasil tool. Untuk mengganti output tool sebelum Claude melihatnya, tetapkan updatedToolOutput, yang bekerja untuk tool apa pun di kedua SDK. Field updatedMCPToolOutput yang lebih lama mengganti output MCP tool saja dan sudah usang.

Kembalikan {} untuk mengizinkan operasi tanpa perubahan. SDK callback hooks menggunakan format output JSON yang sama dengan Claude Code shell command hooks, yang mendokumentasikan setiap field dan opsi spesifik event. Untuk definisi tipe SDK, lihat referensi SDK TypeScript dan Python.

Asynchronous output

Secara default, agent menunggu hook Anda kembali sebelum melanjutkan. Jika hook Anda melakukan side effect, seperti logging atau mengirim webhook, dan tidak perlu mempengaruhi perilaku agent, Anda dapat mengembalikan async output sebagai gantinya. Ini memberi tahu agent untuk melanjutkan segera tanpa menunggu hook selesai:

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}
Field Type Description
async true Sinyal mode async. Agent melanjutkan tanpa menunggu. Di Python, gunakan async_ untuk menghindari reserved keyword.
asyncTimeout number Optional timeout dalam milliseconds untuk operasi background

Contoh

Modifikasi input tool

Contoh ini mengintersepsi pemanggilan tool Write dan menulis ulang argumen file_path untuk menambahkan /sandbox, mengalihkan semua penulisan file ke direktori sandboxed. Callback mengembalikan updatedInput dengan jalur yang dimodifikasi dan permissionDecision: 'allow' untuk auto-approve operasi yang ditulis ulang:

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

Tambahkan konteks dan blokir tool

Contoh ini memblokir penulisan ke direktori /etc dan menjelaskan alasannya kepada model dan pengguna:

  • permissionDecision: 'deny' menghentikan pemanggilan tool.
  • permissionDecisionReason memberitahu model mengapa, sehingga menghindari percobaan ulang.
  • systemMessage menunjukkan kepada pengguna apa yang terjadi.
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 {}

Auto-approve tools spesifik

Secara default, agent dapat meminta permission sebelum menggunakan tools tertentu. Contoh ini auto-approves read-only filesystem tools (Read, Glob, Grep) dengan mengembalikan permissionDecision: 'allow', membiarkan mereka berjalan tanpa konfirmasi pengguna sambil meninggalkan semua tools lainnya tunduk pada pemeriksaan permission normal:

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

Daftarkan multiple hooks

Ketika event terjadi, semua hooks yang cocok berjalan secara paralel. Untuk keputusan permission, hasil yang paling ketat menang: satu deny memblokir pemanggilan tool terlepas dari apa yang dikembalikan hooks lainnya. Karena urutan penyelesaian tidak dapat diprediksi, tulis setiap hook untuk bertindak secara independen daripada mengandalkan hook lain yang telah berjalan terlebih dahulu.

Contoh di bawah ini mendaftarkan tiga pemeriksaan independen untuk setiap pemanggilan tool:

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

Filter dengan multi-tool matchers

Gunakan multi-tool matchers untuk berbagi satu callback di seluruh tools terkait. Contoh ini mendaftarkan tiga matchers dengan scope berbeda:

  • Daftar exact yang dipisahkan pipe (Write|Edit|Delete) memicu file_security_hook hanya untuk file modification tools.
  • Regex (^mcp__) memicu mcp_audit_hook untuk tool MCP apa pun yang namanya dimulai dengan mcp__.
  • Matcher yang dihilangkan memicu global_logger untuk setiap pemanggilan tool terlepas dari nama.
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]),
]
}
)

Lacak aktivitas subagent

Gunakan hooks SubagentStop untuk memantau ketika subagents menyelesaikan pekerjaan mereka. Lihat tipe input lengkap di referensi SDK TypeScript dan Python. Contoh ini mencatat ringkasan setiap kali subagent selesai:

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

Buat HTTP requests dari hooks

Hooks dapat melakukan operasi asynchronous seperti HTTP requests. Tangkap errors di dalam hook Anda daripada membiarkan mereka menyebar, karena exception yang tidak ditangani dapat mengganggu agent.

Contoh ini mengirim webhook setelah setiap tool selesai, mencatat tool mana yang berjalan dan kapan. Hook menangkap errors sehingga webhook yang gagal tidak mengganggu agent:

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. A failed webhook shouldn't stop the agent
print(f"Webhook request failed: {e}")

return {}

Teruskan notifikasi ke Slack

Gunakan hooks Notification untuk menerima notifikasi sistem dari agent dan meneruskannya ke layanan eksternal. Notifikasi terjadi untuk tipe event seperti:

  • permission_prompt ketika Claude memerlukan permission
  • idle_prompt ketika Claude menunggu input
  • auth_success ketika authentication selesai
  • elicitation_dialog, elicitation_complete, dan elicitation_response untuk alur elicitation user-prompt

Setiap notifikasi mencakup field message dengan deskripsi yang dapat dibaca manusia dan secara opsional title.

Contoh ini meneruskan setiap notifikasi ke channel Slack. Ini memerlukan Slack incoming webhook URL, yang Anda buat dengan menambahkan app ke workspace Slack Anda dan mengaktifkan incoming webhooks:

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

Perbaiki masalah umum

Hook not firing

  • Verifikasi nama hook event benar dan case-sensitive (PreToolUse, bukan preToolUse)
  • Periksa bahwa pola matcher Anda cocok dengan nama tool dengan tepat
  • Pastikan hook berada di bawah tipe event yang benar di options.hooks
  • Untuk non-tool hooks yang mendukung matchers, seperti Notification dan SubagentStop, matchers cocok dengan fields berbeda, dan Stop mengabaikan matchers sepenuhnya (lihat matcher patterns)
  • Hooks mungkin tidak terjadi ketika agent mencapai batas max_turns karena sesi berakhir sebelum hooks dapat dieksekusi

Matcher not filtering as expected

Matchers hanya cocok dengan nama tool, bukan jalur file atau argumen lainnya. Untuk memfilter berdasarkan jalur file, periksa tool_input.file_path di dalam hook Anda:

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

  • Tingkatkan nilai timeout dalam konfigurasi HookMatcher
  • Gunakan AbortSignal dari argumen callback ketiga untuk menangani pembatalan dengan baik di TypeScript

Tool blocked unexpectedly

  • Periksa semua hooks PreToolUse untuk returns permissionDecision: 'deny'
  • Tambahkan logging ke hooks Anda untuk melihat apa permissionDecisionReason yang mereka kembalikan
  • Verifikasi pola matcher tidak terlalu luas: matcher kosong cocok dengan semua tools

Modified input not applied

  • Pastikan updatedInput berada di dalam hookSpecificOutput, bukan di top level:

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

  • Kembalikan permissionDecision: 'allow' untuk auto-approve input yang dimodifikasi, atau 'ask' untuk menampilkannya kepada pengguna untuk persetujuan

  • Sertakan hookEventName di hookSpecificOutput untuk mengidentifikasi tipe hook mana output-nya

Session hooks not available in Python

SessionStart dan SessionEnd dapat didaftarkan sebagai SDK callback hooks di TypeScript, tetapi tidak tersedia di Python SDK karena tipe HookEvent-nya menghilangkannya. Di Python, mereka hanya tersedia sebagai shell command hooks yang didefinisikan dalam file pengaturan seperti .claude/settings.json. Untuk memuat shell command hooks dari aplikasi SDK Anda, sertakan setting source yang sesuai dengan setting_sources atau settingSources:

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

Untuk menjalankan logika inisialisasi sebagai callback Python SDK sebagai gantinya, gunakan pesan pertama dari client.receive_response() sebagai trigger Anda.

Subagent permission prompts multiplying

Ketika spawning multiple subagents, masing-masing mungkin meminta permissions secara terpisah. Subagents tidak secara otomatis mewarisi parent agent permissions. Untuk menghindari prompts berulang, gunakan hooks PreToolUse untuk auto-approve tools spesifik, atau konfigurasi permission rules yang berlaku untuk sesi subagent.

Recursive hook loops with subagents

Hook UserPromptSubmit yang spawns subagents dapat membuat infinite loops jika subagents tersebut memicu hook yang sama. Untuk mencegah ini:

  • Periksa indikator subagent di hook input sebelum spawning
  • Gunakan shared variable atau session state untuk track apakah Anda sudah berada di dalam subagent
  • Scope hooks untuk hanya berjalan untuk sesi top-level agent

systemMessage not appearing in output

Field systemMessage menampilkan pesan kepada pengguna, bukan model. Secara default SDK tidak menampilkan hook output di message stream, jadi pesan mungkin tidak muncul kecuali Anda mengatur includeHookEvents (include_hook_events di Python). Untuk meneruskan konteks ke model sebagai gantinya, kembalikan additionalContext.

Jika Anda perlu menampilkan hook decisions ke aplikasi Anda dengan andal, log mereka secara terpisah atau gunakan dedicated output channel.