Intercept dan kontrol perilaku agen dengan hooks

Hooks memungkinkan Anda untuk menginterceptor eksekusi agen pada titik-titik kunci untuk menambahkan validasi, logging, kontrol keamanan, atau logika kustom. Dengan hooks, Anda dapat:

• Memblokir 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
• Transformasi input dan output untuk membersihkan data, menyuntikkan kredensial, atau mengalihkan jalur file
• Memerlukan persetujuan manusia untuk tindakan sensitif seperti penulisan database atau panggilan API
• Lacak siklus hidup sesi untuk mengelola status, membersihkan sumber daya, atau mengirim notifikasi

Sebuah hook memiliki dua bagian:

1. Fungsi callback: logika yang berjalan ketika hook dipicu
2. Konfigurasi hook: memberitahu SDK acara mana yang akan di-hook (seperti PreToolUse) dan tool mana yang cocok

Contoh berikut memblokir agen dari memodifikasi file .env. Pertama, tentukan callback yang memeriksa jalur file, kemudian teruskan ke query() untuk dijalankan sebelum panggilan tool Write atau Edit apa pun:

Ini adalah hook PreToolUse. Hook ini berjalan sebelum tool dieksekusi dan dapat memblokir atau mengizinkan operasi berdasarkan logika Anda. Sisa panduan ini mencakup semua hook yang tersedia, opsi konfigurasi mereka, dan pola untuk kasus penggunaan umum.

Hook yang tersedia

SDK menyediakan hooks untuk tahap berbeda dari eksekusi agen. Beberapa hooks tersedia di kedua SDK, sementara yang lain hanya TypeScript karena Python SDK tidak mendukungnya.

Kasus penggunaan umum

Hooks cukup fleksibel untuk menangani banyak skenario berbeda. Berikut adalah beberapa pola paling umum yang diorganisir berdasarkan kategori.

Konfigurasi hooks

Untuk mengonfigurasi hook untuk agen Anda, teruskan hook dalam parameter options.hooks saat memanggil query():

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

Opsi hooks adalah kamus (Python) atau objek (TypeScript) di mana:

• Kunci adalah nama acara hook (misalnya, 'PreToolUse', 'PostToolUse', 'Stop')
• Nilai adalah array dari matcher, masing-masing berisi pola filter opsional dan fungsi callback Anda

Fungsi callback hook Anda menerima data input tentang acara dan mengembalikan respons sehingga agen tahu untuk mengizinkan, memblokir, atau memodifikasi operasi.

Matchers

Gunakan matcher untuk memfilter tool mana yang memicu callback Anda:

Gunakan pola matcher untuk menargetkan tool tertentu kapan pun memungkinkan. Matcher dengan 'Bash' hanya berjalan untuk perintah Bash, sementara menghilangkan pola menjalankan callback Anda untuk setiap pemanggilan tool. Perhatikan bahwa matcher 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.

Matcher hanya berlaku untuk hook berbasis tool (PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest). Untuk hook siklus hidup seperti Stop, SessionStart, dan Notification, matcher diabaikan dan hook dipicu untuk semua acara dari tipe itu.

Contoh ini menggunakan matcher untuk menjalankan hook hanya untuk tool yang memodifikasi file ketika acara PreToolUse dipicu:

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

Input fungsi callback

Setiap callback hook menerima tiga argumen:

1. Data input (dict / HookInput): Detail acara. Lihat data input untuk bidang
2. ID penggunaan tool (str | None / string | null): Korelasikan acara PreToolUse dan PostToolUse
3. Konteks (HookContext): Di TypeScript, berisi properti signal (AbortSignal) untuk pembatalan. Teruskan ini ke operasi async seperti fetch() sehingga mereka secara otomatis membatalkan jika hook kedaluwarsa. Di Python, argumen ini dicadangkan untuk penggunaan di masa depan.

Data input

Argumen pertama untuk callback hook Anda berisi informasi tentang acara. Nama bidang identik di seluruh SDK (keduanya menggunakan snake_case).

Bidang umum yang ada di semua tipe hook:

Bidang spesifik hook bervariasi menurut tipe hook. Item yang ditandai ^TS hanya tersedia di TypeScript SDK:

Kode di bawah mendefinisikan callback hook yang menggunakan tool_name dan tool_input untuk mencatat detail tentang setiap pemanggilan tool:

Output callback

Fungsi callback Anda mengembalikan objek yang memberitahu SDK cara melanjutkan. Kembalikan objek kosong {} untuk mengizinkan operasi tanpa perubahan. Untuk memblokir, memodifikasi, atau menambahkan konteks ke operasi, kembalikan objek dengan bidang hookSpecificOutput yang berisi keputusan Anda.

Bidang tingkat atas (di luar hookSpecificOutput):

Bidang di dalam hookSpecificOutput:

Contoh ini memblokir operasi penulisan ke direktori /etc sambil menyuntikkan pesan sistem untuk mengingatkan Claude tentang praktik file yang aman:

Alur keputusan izin

Ketika beberapa hook atau aturan izin berlaku, SDK mengevaluasinya dalam urutan ini:

1. Aturan Deny diperiksa terlebih dahulu (kecocokan apa pun = penolakan segera).
2. Aturan Ask diperiksa kedua.
3. Aturan Allow diperiksa ketiga.
4. Default ke Ask jika tidak ada yang cocok.

Jika hook apa pun mengembalikan deny, operasi diblokir—hook lain yang mengembalikan allow tidak akan menimpanya.

Blokir tool

Kembalikan keputusan deny untuk mencegah eksekusi tool:

Modifikasi input tool

Kembalikan input yang diperbarui untuk mengubah apa yang diterima tool:

Tambahkan pesan sistem

Suntikkan konteks ke dalam percakapan:

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

Persetujuan otomatis untuk tool tertentu

Lewati prompt izin untuk tool terpercaya. Ini berguna ketika Anda ingin operasi tertentu berjalan tanpa konfirmasi pengguna:

Tangani skenario lanjutan

Pola-pola ini membantu Anda membangun sistem hook yang lebih canggih untuk kasus penggunaan yang kompleks.

Chaining multiple hooks

Hooks dieksekusi dalam urutan kemunculannya di array. Jaga setiap hook tetap fokus pada tanggung jawab tunggal dan rantai beberapa hook untuk logika kompleks. Contoh ini menjalankan keempat hook untuk setiap pemanggilan tool (tidak ada matcher yang ditentukan):

Matcher spesifik tool dengan regex

Gunakan pola regex untuk mencocokkan beberapa tool:

Melacak aktivitas subagen

Gunakan hook SubagentStop untuk memantau penyelesaian subagen. tool_use_id membantu menghubungkan panggilan agen induk dengan subagen mereka:

Operasi async dalam hooks

Hooks dapat melakukan operasi async seperti permintaan HTTP. Tangani kesalahan dengan baik dengan menangkap pengecualian daripada melemparnya. Di TypeScript, teruskan signal ke fetch() sehingga permintaan dibatalkan jika hook kedaluwarsa:

Mengirim notifikasi (hanya TypeScript)

Gunakan hook Notification untuk menerima pembaruan status dari agen dan meneruskannya ke layanan eksternal seperti Slack atau dashboard pemantauan:

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

Perbaiki masalah umum

Bagian ini mencakup masalah umum dan cara menyelesaikannya.

Hook tidak dipicu

• Verifikasi nama acara hook benar dan peka huruf besar-kecil (PreToolUse, bukan preToolUse)
• Periksa bahwa pola matcher Anda cocok dengan nama tool dengan tepat
• Pastikan hook berada di bawah tipe acara yang benar dalam options.hooks
• Untuk hook SubagentStop, Stop, SessionStart, SessionEnd, dan Notification, matcher diabaikan. Hook ini dipicu untuk semua acara dari tipe itu.
• Hook mungkin tidak dipicu ketika agen mencapai batas max_turns karena sesi berakhir sebelum hook dapat dieksekusi

Matcher tidak memfilter seperti yang diharapkan

Matcher hanya mencocokkan 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 filePath = preInput.tool_input?.file_path as string;
  if (!filePath?.endsWith('.md')) return {};  // Skip non-markdown files
  // Process markdown files...
};

Hook timeout

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

Tool diblokir secara tidak terduga

• Periksa semua hook PreToolUse untuk pengembalian permissionDecision: 'deny'
• Tambahkan logging ke hook Anda untuk melihat apa permissionDecisionReason yang mereka kembalikan
• Verifikasi pola matcher tidak terlalu luas (matcher kosong cocok dengan semua tool)

Input yang dimodifikasi tidak diterapkan

• Pastikan updatedInput berada di dalam hookSpecificOutput, bukan di tingkat atas:

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

• Anda juga harus mengembalikan permissionDecision: 'allow' agar modifikasi input berlaku

Hook sesi tidak tersedia

Hook SessionStart, SessionEnd, dan Notification hanya tersedia di TypeScript SDK. Python SDK tidak mendukung acara ini karena keterbatasan setup.

Prompt izin subagen berlipat ganda

Saat memijahkan beberapa subagen, masing-masing mungkin meminta izin secara terpisah. Subagen tidak secara otomatis mewarisi izin agen induk. Untuk menghindari prompt berulang, gunakan hook PreToolUse untuk persetujuan otomatis tool tertentu, atau konfigurasi aturan izin yang berlaku untuk sesi subagen.

Loop hook rekursif dengan subagen

Hook UserPromptSubmit yang memijahkan subagen dapat membuat loop tak terbatas jika subagen tersebut memicu hook yang sama. Untuk mencegah ini:

• Periksa indikator subagen dalam input hook sebelum memijahkan
• Gunakan bidang parent_tool_use_id untuk mendeteksi jika Anda sudah dalam konteks subagen
• Batasi hook hanya berjalan untuk sesi agen tingkat atas

systemMessage tidak muncul dalam output

Bidang systemMessage menambahkan konteks ke percakapan yang model lihat, tetapi mungkin tidak muncul di semua mode output SDK. Jika Anda perlu menampilkan keputusan hook ke aplikasi Anda, log mereka secara terpisah atau gunakan saluran output khusus.

Pelajari lebih lanjut

• Permissions: kontrol apa yang dapat dilakukan agen Anda
• Custom Tools: bangun tool untuk memperluas kemampuan agen
• TypeScript SDK Reference
• Python SDK Reference