Halaman ini diterjemahkan dari dokumentasi bahasa Inggris. Perintah, pengenal, dan contoh tidak diubah. Runtime 7.24.4 · SDK 2.6.7. Sumber bahasa Inggris

Hook siklus hidup

Status: Aktif
Cakupan: kondisi terkini
Terakhir ditinjau: 2026-08-23 Pemilik: runtime ax-code

Hook siklus hidup memungkinkan Anda menjalankan perintah shell pada peristiwa agen tanpa membangun ulang runtime. Mereka melengkapi aturan izin dan sandbox isolasi: hook adalah efek samping deterministik (“selalu format”, “jangan pernah force-push”), sementara prompt tetap bersifat nasihat.

Peristiwa

Empat peristiwa siklus hidup sesi (SessionStart, SessionEnd, PostCompact, Interrupt) dan PostToolUseFailure hanya pengamatan: mereka menembak dan melupakan, tidak pernah memblokir jalur siklus hidup, dan muatannya hanya membawa id/alasan/stempel waktu — tidak pernah teks percakapan, ringkasan, atau keluaran alat. Sesi subagen tidak menembakkan SessionStart (mereka sudah muncul melalui SubagentStop). SubagentStop menembak untuk anak yang dimulai oleh task maupun task_parallel.

Umpan balik PostToolUse sampai ke model

Hook PostToolUse dapat menyerahkan teks kembali ke model. Ia ditambahkan ke hasil alat di dalam blok <hook_feedback event="PostToolUse">, setelah keluaran milik alat; ia tidak pernah mengganti keluaran dan tidak pernah memblokir.

• Entri lama (tanpa protocol): stdout yang dipangkas dari hook yang keluar 0.
• Entri protocol: "claude-code": hookSpecificOutput.additionalContext, reason dari putusan {"decision": "block", "reason": "..."}, atau stderr bila hook keluar 2. Keluar bukan nol yang lain tidak menyumbang apa pun.

Umpan balik dibatasi 4,000 karakter per hook dan 8,000 karakter per panggilan alat, jadi hook yang berisik tidak dapat membanjiri konteks. Inilah yang membuat paket format-after-edit berguna: pengingatnya kini mendarat di giliran model berikutnya alih-alih hanya di log.

Nama ini dipetakan ke pemicu plugin internal AX Code (tool.execute.before / tool.execute.after) plus hook prompt, pemadatan, subagen, dan berhenti tingkat sesi. Prompt kelanjutan sintetis (prompt internal agentRouting: "preserve") tidak menembakkan UserPromptSubmit.

Aktifkan paket

Hook dan plugin proyek mengeksekusi kode yang dikendalikan repositori, jadi .ax-code/hooks.json, .ax-code/plugin/, dan plugin yang dikonfigurasi proyek dinonaktifkan secara bawaan. Setelah meninjaunya, ikut serta di luar repositori saat memulai AX Code:

AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

Lalu buat .ax-code/hooks.json di proyek Anda:

{
  "packs": ["format-after-edit", "block-force-push", "require-tests-on-stop", "protect-env-files", "log-bash-commands"]
}

Paket resmi (≥5)

Hook kustom:

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "bash",
      "command": "echo running bash",
      "blockOnFailure": false
    }
  ]
}

Protokol kawat Claude Code (ikut serta)

Jika Anda sudah memiliki hook yang ditulis untuk Claude Code, sebuah entri dapat ikut serta ke protokol kawat Claude Code dengan "protocol": "claude-code":

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "bash",
      "command": "my-claude-code-hook.sh",
      "protocol": "claude-code"
    }
  ]
}

Untuk peristiwa yang dapat diblokir (PreToolUse, UserPromptSubmit), entri yang ikut serta didekode dengan semantik Claude Code alih-alih pemeriksaan blockOnFailure:

• Keluar 2 memblokir tindakan; stderr hook ditampilkan sebagai alasan. Stdout yang rusak tetap memblokir (gagal-aman).
• Keluar 0 dengan JSON stdout {"permissionDecision": "allow"|"deny"|"ask", "reason"?}: allow melanjutkan; deny memblokir dengan reason; ask menjeda panggilan alat pada prompt izin hook interaktif yang menampilkan alasan (bawaan "hook requested user confirmation"). Prompt hanya interaktif: tidak ada aturan always, pemberian wildcard, atau persetujuan otomatis otonom yang dapat menjawabnya, dan jalankan tanpa interaksi menolaknya, yang dilihat model sebagai penolakan izin biasa. Hook berikutnya yang menjawab deny menang atas ask yang lebih awal. UserPromptSubmit tidak memiliki panggilan alat untuk menempelkan prompt, jadi ask tetap memblokir di sana. Bentuk Claude Code bersarang {"hookSpecificOutput": {"permissionDecision": "...", "permissionDecisionReason": "..."}} diterima sebagai alias.
• Keluar lain apa pun adalah kesalahan yang tidak memblokir (dicatat, tindakan berlanjut).

Peristiwa hanya-pengamatan mengabaikan dekoder sepenuhnya — mereka tidak pernah dapat memblokir. Entri tanpa bidang protocol berperilaku persis seperti sebelumnya.

Variabel lingkungan yang tersedia untuk perintah hook:

• HOOK_EVENT — salah satu dari PreToolUse, PostToolUse, PostToolUseFailure, Stop, UserPromptSubmit, PreCompact, SubagentStop, SessionStart, SessionEnd, PostCompact, atau Interrupt
• HOOK_TOOL — id alat
• HOOK_SESSION_ID
• HOOK_ARGS_JSON — argumen alat JSON
• HOOK_ARGS_STDIN=1 — argumen JSON lengkap selalu tersedia di stdin; HOOK_ARGS_JSON kosong untuk muatan yang lebih besar dari 32 KiB
• HOOK_PACK — nama paket bila berlaku

Proses anak hook mewarisi versi tersanitasi dari lingkungan AX Code. AX Code mempertahankan variabel platform dan perkakas biasa, tetapi menghapus nama yang mirip rahasia, URL yang membawa kredensial, pembantu kredensial seperti SSH_AUTH_SOCK, dan variabel injeksi proses seperti NODE_OPTIONS. Variabel protokol HOOK_* di atas ditambahkan setelah sanitasi dan selalu tersedia.

Hook lama yang sepenuhnya tepercaya dan membutuhkan kredensial ambien dapat memulihkan perilaku sebelumnya di luar repositori:

AX_CODE_HOOKS_FULL_ENV=1 AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

Pintu darurat ini mengekspos setiap variabel lingkungan ke setiap hook yang diaktifkan. Repositori tidak dapat memintanya melalui .ax-code/hooks.json; pakai hanya setelah meninjau semua hook dan paket.

Catatan keamanan: sanitasi lingkungan mengurangi paparan kredensial ambien tetapi tidak mengurung perintah hook. Hook tetap berupa kode shell sembarang yang dapat membaca berkas yang dapat diakses dan memakai jaringan host. Perlakukan sebagai kode tepercaya dan tinjau setiap hook serta paket yang diaktifkan.

Hubungan dengan isolasi

Hook tidak menggantikan sandbox. Pakai:

1. Isolasi aplikasi untuk batas penulisan/jaringan yang portabel
2. Isolasi OS (backend bawaan "auto") untuk sandbox bash yang ditegakkan kernel bila tersedia
3. Hook untuk efek samping kebijakan dan blok keras seperti force-push

Lihat Mode sandbox dan SECURITY.md.