Referensi hooks

Siklus hidup hook

• per sesi: SessionStart dan SessionEnd
• per turn: UserPromptSubmit, Stop, dan StopFailure
• pada setiap pemanggilan tool di dalam loop agentic: PreToolUse dan PostToolUse, kecuali panggilan EndConversation, yang melewati keduanya

Bagaimana hook diselesaikan

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/block-rm.sh
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
else
  exit 0  # no decision; normal permission flow applies
fi

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|PowerShell",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-File",
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
            ]
          },
          {
            "type": "command",
            "if": "PowerShell(Remove-Item *)",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-File",
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
            ]
          }
        ]
      }
    ]
  }
}

# .claude/hooks/block-rm.ps1
$callInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
$command = $callInput.tool_input.command

if ($command -match 'rm -rf|Remove-Item.*-Recurse') {
  @{
    hookSpecificOutput = @{
      hookEventName = "PreToolUse"
      permissionDecision = "deny"
      permissionDecisionReason = "Destructive command blocked by hook"
    }
  } | ConvertTo-Json
} else {
  exit 0  # no decision; normal permission flow applies
}

{ "tool_name": "Bash", "tool_input": { "command": "rm -rf /tmp/build" }, ... }

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by hook"
  }
}

Konfigurasi

1. Pilih event hook yang akan direspons, seperti PreToolUse atau Stop
2. Tambahkan grup matcher untuk memfilter kapan hook dipicu, seperti “untuk tool Bash”
3. Definisikan satu atau lebih handler hook untuk dijalankan saat cocok

Lokasi hook

• Hook pengguna, proyek, lokal, dan plugin Anda diblokir. Hook dari plugin yang diaktifkan paksa dalam enabledPlugins pengaturan terkelola dikecualikan
• Claude Code juga mempersempit pengaturan statusLine dan fileSuggestion Anda ke pengaturan terkelola
• Claude Code juga menonaktifkan plugin dengan sumber command, termasuk plugin yang diaktifkan paksa dalam enabledPlugins pengaturan terkelola, kecuali jika disableCommandPluginSources secara eksplisit disetel ke false. Sumber command memerlukan Claude Code v2.1.229 atau yang lebih baru
• Claude Code juga memblokir perintah headersHelper marketplace kecuali jika disableCommandPluginSources secara eksplisit disetel ke false, dengan pengecualian untuk marketplace yang dideklarasikan oleh pengaturan terkelola itu sendiri

• allowedHttpHookUrls: ketika didefinisikan di tingkat pengaturan mana pun, Claude Code menjalankan handler hook HTTP hanya jika URL-nya cocok dengan allowlist yang telah digabungkan
• httpHookAllowedEnvVars: ketika didefinisikan, Claude Code hanya menginterpolasi environment variable yang ada dalam daftar tersebut ke dalam header hook

Pola matcher

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/lint-check.sh"
          }
        ]
      }
    ]
  }
}

Mencocokkan tool MCP

• mcp__memory__create_entities: tool create entities milik server Memory
• mcp__filesystem__read_file: tool read file milik server Filesystem
• mcp__github__search_repositories: tool pencarian milik server GitHub

• mcp__memory__.* cocok dengan semua tool dari server memory
• mcp__brave-search__.* cocok dengan semua tool dari server yang namanya mengandung tanda hubung
• mcp__.*__write.* cocok dengan tool apa pun yang namanya diawali write dari server mana pun

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
          }
        ]
      },
      {
        "matcher": "mcp__.*__write.*",
        "hooks": [
          {
            "type": "command",
            "command": "/home/user/scripts/validate-mcp-write.py"
          }
        ]
      }
    ]
  }
}

Mencocokkan perintah Monitor

• Matcher yang menyertakan Monitor: dengan matcher seperti Bash|Monitor atau .*, atau tanpa matcher, hook mendapatkan input milik panggilan Monitor itu sendiri, dan allow serta updatedInput berlaku. Dalam if, sebutkan Monitor, seperti pada Monitor(tail *), yang mencocokkan berdasarkan aturan yang diikuti Bash(tail *). Jika if-nya menyebutkan Bash, hook tetap mendapatkan input panggilan Monitor, tetapi allow dan updatedInput tidak berpengaruh
• Matcher Bash: hook mendapatkan panggilan Bash. Dalam if, sebutkan Bash, seperti pada Bash(tail *). Hook tidak berjalan jika if-nya menyebutkan Monitor

Field handler hook

• Hook perintah (type: "command"): menjalankan perintah shell. Skrip Anda menerima input JSON milik event melalui stdin dan mengomunikasikan hasil kembali melalui exit code dan stdout.
• Hook HTTP (type: "http"): mengirim input JSON milik event sebagai permintaan HTTP POST ke sebuah URL. Endpoint mengomunikasikan hasil kembali melalui body respons menggunakan format output JSON yang sama seperti hook perintah.
• Hook tool MCP (type: "mcp_tool"): memanggil tool pada server MCP yang dikonfigurasi. Output teks tool diperlakukan seperti stdout hook perintah.
• Hook prompt (type: "prompt"): mengirim prompt ke model Claude untuk evaluasi satu giliran. Model mengembalikan keputusannya sebagai JSON. Lihat Hook berbasis prompt.
• Hook agent (type: "agent"): memunculkan subagent yang dapat menggunakan tool seperti Read, Grep, dan Glob untuk memverifikasi kondisi sebelum mengembalikan keputusan. Hook agent bersifat eksperimental dan dapat berubah. Lihat Hook berbasis agent.

Field umum

Cara pola if mencocokkan perintah Bash

Field hook perintah

Bentuk exec dan bentuk shell

{
  "type": "command",
  "command": "node",
  "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/format.js", "--fix"]
}

{
  "type": "command",
  "command": "node \"${CLAUDE_PLUGIN_ROOT}\"/scripts/format.js --fix"
}

Field hook HTTP

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/pre-tool-use",
            "timeout": 30,
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

Field hook tool MCP

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "my_server",
            "tool": "security_scan",
            "input": { "file_path": "${tool_input.file_path}" }
          }
        ]
      }
    ]
  }
}

Cara hasil tool dibaca

MCP tool "security_scan" on server "my_server" gave no answer that could be read, because a message from the server was too large, so this hook gave no verdict. If this keeps happening, the tool must send a smaller answer.
MCP tool "security_scan" on server "my_server" answered without its text, which happens when a result is too large, so this hook gave no verdict. If this keeps happening, the tool must send a smaller answer.

Ketika server masih terhubung

Event yang dipicu sebelum server MCP tersedia

Field hook prompt dan agent

Mereferensikan skrip berdasarkan path

• ${CLAUDE_PROJECT_DIR}: root proyek tempat sesi dimulai. Claude Code juga menyetel variabel ini di environment server MCP stdio dan server LSP plugin.
• ${CLAUDE_PLUGIN_ROOT}: direktori instalasi plugin, untuk skrip yang dibundel dengan plugin. Lihat environment variable plugin untuk perilaku path di seluruh pembaruan.
• ${CLAUDE_PLUGIN_DATA}: direktori data persisten milik plugin, untuk dependensi dan status yang harus tetap ada setelah pembaruan plugin.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

{
  "description": "Automatic code formatting",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
            "args": [],
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Hook dalam skill dan agent

• Hook subagent: Claude Code menjalankannya hanya selama subagent tersebut berjalan dan menghapusnya ketika subagent selesai. Claude Code mengonversi hook Stop di sini menjadi SubagentStop, event yang dipicunya ketika subagent selesai.
• Hook skill: Claude Code mendaftarkannya ketika Anda atau Claude memanggil skill dan terus menjalankannya selama sisa sesi, termasuk pada giliran setelah giliran skill itu sendiri. Agar Claude Code menghapus hook setelah eksekusi pertamanya yang berhasil, setel once: true pada hook tersebut.

---
name: secure-operations
description: Perform operations with security checks
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

Batasan pada hook skill

• Penguncian khusus plugin: administrator organisasi Anda dapat mengunci hook ke plugin dan pengaturan terkelola dengan pengaturan terkelola strictPluginOnlyCustomization. Skill mempertahankan hook frontmatter-nya di bawah penguncian tersebut hanya jika skill tersebut adalah skill plugin, skill bawaan, atau skill di direktori pengaturan terkelola. Hook dalam file pengaturan Anda sendiri juga tidak berjalan.
  • Periksa: ketik /status dalam sesi Claude Code. Jika baris Setting sources menyertakan Enterprise managed settings, tanyakan kepada administrator Anda apakah strictPluginOnlyCustomization mengunci hook.
  • Perbaiki: pindahkan skill ke dalam plugin, karena skill plugin mempertahankan hook frontmatter-nya. Cantumkan plugin dalam marketplace, lalu instal dari sana. Jika Claude Code menolak marketplace dengan is blocked by enterprise policy, minta administrator Anda untuk mengizinkan marketplace tersebut.
• Batas hook: di Claude Code v2.1.304 atau yang lebih baru, setiap sumber skill memiliki batasnya sendiri per sesi. Proyek Anda, folder skill pribadi Anda, dan setiap plugin dihitung sebagai sumber terpisah. Skill dari satu sumber dapat mendaftarkan paling banyak 1.024 hook. Matcher hook tersebut dapat berjumlah total paling banyak 16.384 karakter. Matcher dengan beberapa hook di bawahnya dihitung sekali untuk setiap hook.
  • Periksa: ulangi sesi di mana hook tidak dipicu, dengan logging debug aktif:
    1. Mulai sesi baru dari shell Anda dengan claude --debug. Jika Anda tidak memulai sesi dari shell, ketik /debug terlebih dahulu dalam sesi baru sebagai gantinya.
    2. Panggil skill yang sama dalam urutan yang sama, termasuk yang dipanggil Claude, karena kedua total terakumulasi skill demi skill. Minta Claude untuk memanggil skill apa pun yang tidak dapat Anda ketik sebagai perintah.
    3. Cari registers none of its hooks di log debug. Baris yang berisi teks tersebut menyebutkan skill yang melewati batas.
  • Perbaiki: deklarasikan lebih sedikit hook atau matcher yang lebih pendek dalam skill tersebut atau dalam skill lain dari sumbernya, lalu mulai sesi baru. Jika skill tersebut tidak dapat Anda edit, minta penulisnya untuk melakukan perubahan tersebut. Sampai saat itu, mulai sesi baru dan panggil skill yang Anda perlukan sebelum skill lain dari sumbernya.

Menu /hooks

Menonaktifkan atau menghapus hook

Input dan output hook

Field input umum

{
  "session_id": "abc123",
  "prompt_id": "550e8400-e29b-41d4-a716-446655440000",
  "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
  "cwd": "/home/user/my-project",
  "scratchpad_dir": "/tmp/claude-1000/-home-user-my-project/abc123/scratchpad",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite",
    "timeout": 120000,
    "run_in_background": false
  },
  "tool_use_id": "toolu_01ABC123..."
}

Output exit code

• Berhasil: hook Anda keluar dengan 0. Claude Code menerapkan field output JSON apa pun yang dicetak hook Anda, dan tindakan dilanjutkan kecuali field tersebut memblokir atau menolaknya. Hook yang memulai proses latar belakang membahas pengecualiannya.
• Error blocking: hook Anda keluar dengan 2. Pada event yang dapat memblokir, Claude Code menghentikan tindakan.
• Error non-blocking: hook Anda keluar dengan kode lain, atau gagal dengan cara lain, seperti tidak dapat dimulai atau mencetak JSON yang tidak valid. Tindakan dilanjutkan, kecuali untuk hook yang kegagalannya memblokir tindakan, misalnya hook dengan onFailure diatur ke "block". Pada event seperti PreToolUse, Anda melihat pemberitahuan <hook name> hook error di transkrip.

• WorktreeCreate: exit code bukan nol apa pun membuat pembuatan worktree gagal, apa pun isi JSON Anda.
• WorktreeRemove: exit code bukan nol apa pun membuat penghapusan worktree gagal jika direktori masih ada setelahnya.
• Stop, SubagentStop, TaskCompleted, dan hook UserPromptSubmit dari plugin: ketika hook Anda keluar dengan 2 tanpa apa pun di stdout dan stderr-nya menyatakan bahwa suatu file tidak ada, seperti No such file or directory, Claude Code memperlakukan eksekusi tersebut sebagai error non-blocking.
• Elicitation dan ElicitationResult: Claude Code menerapkan hookSpecificOutput Anda ketika hook Anda keluar dengan 0, dan mengabaikannya pada exit code lainnya.
• Event yang membuang output hook, seperti StopFailure: Claude Code mengabaikan JSON Anda pada setiap exit code, kecuali field efek samping seperti terminalSequence, yang tetap dijalankan.

Exit code 0

• Output yang tidak diawali dengan {, atau yang diawali dengan { tetapi tidak diakhiri dengan }: teks biasa. Array JSON dan string JSON yang diberi tanda kutip merupakan teks biasa menurut aturan ini.
• Dua baris atau lebih yang masing-masing dapat di-parse sebagai JSON secara terpisah, dengan baris pertama diawali { dan baris terakhir diakhiri }: teks biasa ketika tidak ada baris yang merupakan objek output JSON yang mengatur suatu field. Ketika ada baris yang demikian, output tersebut adalah kegagalan parse, jadi cetak objek tersebut tanpa apa pun lainnya di stdout.
• Apa pun lainnya yang diawali dengan { dan diakhiri dengan } tetapi bukan JSON yang valid: kegagalan parse.

• UserPromptSubmit, UserPromptExpansion, SessionStart, dan PostModelSwitch: Claude Code menambahkan stdout teks biasa sebagai konteks yang dapat dilihat dan ditindaklanjuti oleh Claude. Claude Code tidak menambahkan stdout yang gagal di-parse.
• PreCompact: stdout Anda menjadi instruksi untuk ringkasan compaction

Exit code 2

• JSON yang lolos validasi skema: Claude Code tetap membaca field output JSON, tetapi field tersebut tidak dapat menimpa pemblokiran. Bahkan permissionDecision bernilai "allow" tidak membuat tindakan diloloskan. Pada Elicitation dan ElicitationResult, hookSpecificOutput dari hook yang keluar dengan exit 2 diabaikan.
• JSON yang gagal validasi skema: hook tetap memblokir. Claude Code menggunakan stderr Anda sebagai alasan pemblokiran dan mencatat kegagalan validasi di log debug.

#!/bin/bash
# Reads JSON input from stdin, checks the command
input=$(cat)
command=$(jq -r '.tool_input.command' <<<"$input")

if [[ "$command" == rm* ]]; then
  echo "Blocked: rm commands are not allowed" >&2
  exit 2  # Blocking error: tool call is prevented
fi

exit 0  # No decision: the normal permission flow applies

PreToolUse:Bash hook error: [${CLAUDE_PROJECT_DIR}/.claude/hooks/no-rm.sh]: Blocked: rm commands are not allowed

Exit code lainnya

Failed with non-blocking status code: something broke

Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory

Timeout

Hook yang memulai proses latar belakang

• Jalankan program di latar belakang
• Alihkan stdout dan stderr-nya. Misalnya, perintah Bash npm run dev > dev-server.log 2>&1 & mengirim keduanya ke file. Jika Anda tidak mengalihkannya, hook yang tidak async memerlukan waktu hingga 10 detik untuk selesai setelah prosesnya sendiri keluar.

#!/bin/bash
"$CLAUDE_PROJECT_DIR"/.claude/hooks/policy-check.sh || exit $?
"$CLAUDE_PROJECT_DIR"/.claude/hooks/upload-metrics.sh >/dev/null 2>&1 &

• || exit $?: menjadikan exit code pemeriksaan sebagai exit code hook itu sendiri, sehingga pemeriksaan yang keluar dengan 2 untuk menolak tetap memblokir. Jika tidak, hook keluar dengan kode dari baris terakhir, yaitu 0.
• >/dev/null 2>&1 &: menjalankan upload-metrics.sh di latar belakang dengan output yang dialihkan, sehingga proses tersebut tidak membuat output hook tetap terbuka.

Memblokir tindakan ketika hook gagal

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js"],
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

PreToolUse:Bash hook error: [node ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js]: failed; blocking because onFailure is "block"
Error: Cannot find module '/path/to/project/.claude/hooks/check-command.js'

• Tidak dapat dimulai: hook perintah gagal dimulai, misalnya karena skrip atau executable tidak ada
• Exit code selain 0 atau 2: berlaku untuk hook perintah meskipun hook tersebut mencetak JSON yang mengizinkan tindakan, seperti permissionDecision: "allow". Untuk mengembalikan keputusan JSON, keluar dengan 0
• Error HTTP: koneksi hook HTTP gagal, atau status respons bukan 2xx
• Timeout: hook mencapai timeout-nya
• Output tidak valid: output JSON tidak dapat di-parse atau gagal validasi skema. Untuk hook HTTP, body 2xx yang bukan kosong dan bukan objek JSON juga dihitung. Stdout teks biasa dari hook perintah bukan kegagalan

• Hook Stop, SubagentStop, TaskCompleted, dan TeammateIdle: exit code 2 pada event ini mengirim Claude kembali untuk terus bekerja, dan Claude tidak dapat memperbaiki hook yang tidak mau berjalan
• Hook perintah latar belakang: hook perintah yang mengatur async atau asyncRewake

Hook yang gagal di Windows tanpa Git Bash

blocking because Git Bash wasn't found, so only exit code 0 or 2 counts as this hook's verdict.

• Panggilan sebaiknya dilanjutkan ketika hook gagal: tambahkan "onFailure": "continue" ke hook
• Hook keluar dengan 1 untuk memberi peringatan tetapi harus memblokir ketika crash: dengan "onFailure": "continue", panggilan dilanjutkan pada exit code 1, baik itu peringatan maupun crash. Tambahkan "onFailure": "block" sebagai gantinya, dan akhiri skrip dengan exit code 0 di bagian yang memberi peringatan, sehingga panggilan tersebut dilanjutkan. Untuk tetap menampilkan peringatan pada PreToolUse, cetak peringatan ke stdout sebagai field systemMessage dari satu objek JSON.
• Hook ditulis untuk Bash: tanpa Git Bash, hook berbentuk shell tanpa shell yang diatur berjalan di PowerShell, tempat hook tersebut dapat gagal. Instal Git for Windows, atau atur CLAUDE_CODE_GIT_BASH_PATH jika Git Bash terinstal di lokasi yang tidak ditemukan Claude Code. Lalu mulai sesi baru.
• Hook menjalankan satu .exe, bukan file .cmd atau .bat: letakkan program di command dan argumennya di args untuk menggunakan bentuk exec, lalu tambahkan "onFailure": "block". Claude Code kemudian memulai program tanpa shell. Tanpa "onFailure": "block", panggilan dapat dilanjutkan ketika program gagal, tidak ada, atau mengalami timeout
• Hook penjaga PowerShell yang harus memblokir saat gagal: dengan onFailure tidak diatur, hook ini berhenti memblokir setelah Git for Windows terinstal dan Claude Code menemukan Git Bash. Tambahkan "onFailure": "block" sehingga kegagalan atau timeout memblokir panggilan dengan atau tanpa Git Bash. Atur juga "shell": "powershell" sehingga hook tetap berjalan di PowerShell sejak saat itu alih-alih di Git Bash

PowerShell started no program

• Untuk mencetak teks, seperti JSON: atur "shell": "powershell", dan hook keluar dengan 0
• Untuk menjalankan file .ps1, .cmd, atau .bat, atau .exe yang path-nya memiliki variabel: atur "shell": "powershell" dan letakkan & sebelum path yang diberi tanda kutip. Biarkan $HOME seperti yang tertulis, dan tuliskan environment variable seperti contoh check.ps1 menuliskan $env:CLAUDE_PROJECT_DIR
• Untuk menjalankan satu .exe pada path tanpa $: hapus tanda kutip bagian dalam dari command, lalu terapkan perbaikan untuk hook yang menjalankan satu .exe, dengan menulis "args": [] jika program tidak menerima argumen
• Untuk menjalankan skrip yang ditulis untuk Bash: terapkan perbaikan untuk hook yang ditulis untuk Bash

Perilaku exit code 2 per event

Penanganan respons HTTP

• 2xx dengan body kosong: berhasil, setara dengan exit code 0 tanpa output
• 2xx dengan body objek JSON: di-parse menggunakan skema output JSON yang sama seperti hook perintah. Body yang gagal validasi skema adalah error non-blocking
• 2xx dengan body lain, seperti teks biasa: error non-blocking, ditangani sama seperti status non-2xx. Claude Code tidak menambahkan teks tersebut ke konteks Claude
• Status non-2xx: error non-blocking
• Kegagalan koneksi: error non-blocking
• Timeout: hook dibatalkan, seperti dijelaskan di bagian Timeout

Output JSON

• Cakupan: Claude Code mengukur setiap string secara terpisah, bahkan ketika beberapa hook berjalan untuk event yang sama. Untuk output JSON, setiap field diukur secara terpisah; stdout biasa diukur secara keseluruhan.
• Melebihi batas: kecuali untuk stdout PreCompact, Claude Code menyimpan output ke file di direktori sesi. Claude Code mengganti output tersebut dengan path file serta pratinjau hingga 2.000 karakter pertama. Hasil Bash valid yang besar ditangani dengan cara yang sama, seperti dijelaskan di bagian Batas output. Tidak seperti batas atas Bash tersebut, batas ini tidak memiliki pengaturan atau environment variable untuk menaikkannya.
• Membaca file: Claude Code tidak meminta Claude untuk membaca file tersebut, jadi pastikan apa pun yang harus selalu dilihat Claude tetap berada dalam batas.

• Field universal seperti continue tercantum dalam tabel di bawah. Setiap event menerimanya, tetapi beberapa event membuangnya atau mengirimkan systemMessage ke tempat selain transkrip. Bagian setiap event menyebutkannya. terminalSequence juga berfungsi pada event tersebut, dengan pengecualian yang tercantum di bagian Memancarkan notifikasi terminal.
• decision dan reason tingkat atas digunakan oleh beberapa event untuk memblokir atau memberikan umpan balik.
• hookSpecificOutput adalah objek bersarang untuk event yang memerlukan kontrol lebih kaya. Objek ini memerlukan field hookEventName yang diatur ke nama event.

{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }

Memancarkan notifikasi terminal

• OSC 0, 1, 2: judul jendela dan ikon
• OSC 9: notifikasi iTerm2, ConEmu, Windows Terminal, dan WezTerm, termasuk progres taskbar 9;4
• OSC 99: notifikasi Kitty
• OSC 777: notifikasi urxvt, Ghostty, dan Warp
• BEL tunggal

• Claude Code menulis sequence hanya dalam sesi interaktif, dan hanya selama antarmukanya terbuka. Dalam mode non-interaktif dengan flag -p dan di Agent SDK, Claude Code mengabaikan field ini.
• Field ini hanya berfungsi dari hook yang tidak berjalan di latar belakang, jadi biarkan async dan asyncRewake nonaktif.
• Hook perintah WorktreeCreate tidak dapat mengembalikan JSON, karena Claude Code membaca stdout-nya sebagai path worktree. Hook HTTP WorktreeCreate mengembalikan JSON dan dapat menyertakan field ini.

#!/bin/bash
# Notification hook: ping the desktop when Claude Code needs attention.
input=$(cat)
title="Claude Code"
body=$(jq -r '.message // "Needs your attention"' <<<"$input")
seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

Mendapatkan notifikasi terminal di dalam tmux atau GNU screen

• tmux 3.3 atau lebih baru: tambahkan set -g allow-passthrough on ke ~/.tmux.conf, lalu jalankan tmux source-file ~/.tmux.conf dari shell. Opsi ini berlaku untuk setiap program di pane tersebut, bukan hanya Claude Code. Dengan on, hanya pane yang sedang ditampilkan tmux yang dapat mengirimkannya. Agar pane lain dalam sesi yang Anda lampirkan juga dapat mengirimkannya, gunakan all sebagai pengganti on, pada tmux 3.4 atau lebih baru.
• GNU screen: biarkan jendela Claude Code tetap ditampilkan di screen, karena sequence dari jendela latar belakang tidak sampai ke aplikasi terminal Anda

Menambahkan konteks untuk Claude

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "This file is generated. Edit src/schema.ts and run `bun generate` instead."
  }
}

• SessionStart dan SubagentStart: di awal percakapan, sebelum prompt pertama
• UserPromptSubmit dan UserPromptExpansion: bersama prompt yang dikirim
• PreToolUse, PostToolUse, PostToolUseFailure, dan PostToolBatch: di samping hasil tool
• Stop dan SubagentStop: di akhir giliran. Percakapan berlanjut sehingga Claude dapat menindaklanjuti umpan balik. Lihat Kontrol keputusan Stop
• PostModelSwitch: bersama permintaan berikutnya setelah pergantian. Lihat Kontrol keputusan PostModelSwitch untuk waktunya

• Status environment: branch saat ini, target deployment, atau feature flag yang aktif
• Aturan proyek bersyarat: perintah pengujian mana yang berlaku untuk file yang baru saja diedit, direktori mana yang read-only di worktree ini
• Data eksternal: issue terbuka yang ditugaskan kepada Anda, hasil CI terbaru, konten yang diambil dari layanan internal

Kontrol keputusan

• PreToolUse: updatedInput langsung di bawah hookSpecificOutput menggantikan argumen tool sebelum tool berjalan. Lihat Kontrol keputusan PreToolUse
• PermissionRequest: updatedInput di dalam objek decision. Lihat Kontrol keputusan PermissionRequest
• PostToolUse: updatedToolOutput menggantikan hasil tool. Dalam sesi cloud Cowork, Claude Code mengabaikan updatedToolOutput ketika tool-nya adalah AskUserQuestion atau ExitPlanMode, dan Claude membaca jawaban atau rencana aslinya. Lihat Kontrol keputusan PostToolUse
• UserPromptSubmit: tidak dapat menggantikan prompt; hanya menyisipkan additionalContext bersamanya

{
  "decision": "block",
  "reason": "Test suite must pass before proceeding"
}

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database writes are not allowed"
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {
        "command": "npm run lint"
      }
    }
  }
}

Event hook

SessionStart

Input SessionStart

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SessionStart",
  "source": "resume",
  "model": "claude-opus-5",
  "seconds_since_last_response": 5400,
  "context_tokens": 182340,
  "prompt_cache_likely_expired": true,
  "estimated_cache_write_usd": 1.1396
}

Kontrol keputusan SessionStart

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Current branch: feat/auth-refactor\nUncommitted changes: src/auth.ts, src/login.tsx\nActive issue: #4211 Migrate to OAuth2",
    "sessionTitle": "auth-refactor"
  }
}

Memuat ulang skill yang diinstal hook

#!/bin/bash

git -C ~/.claude/skills/team-skills pull --quiet 2>/dev/null || \
  git clone --quiet https://git.example.com/your-org/team-skills.git ~/.claude/skills/team-skills

echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'

Mempertahankan environment variable

#!/bin/bash

if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
  echo 'export DEBUG_LOG=true' >> "$CLAUDE_ENV_FILE"
  echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE"
fi

exit 0

#!/bin/bash

ENV_BEFORE=$(export -p | sort)

# Run your setup commands that modify the environment
source ~/.nvm/nvm.sh
nvm use 20

if [ -n "$CLAUDE_ENV_FILE" ]; then
  ENV_AFTER=$(export -p | sort)
  comm -13 <(echo "$ENV_BEFORE") <(echo "$ENV_AFTER") >> "$CLAUDE_ENV_FILE"
fi

exit 0

Variabel yang dipertahankan dalam perintah PowerShell

• Baris kosong atau komentar #
• Satu penugasan di awal baris, ditulis export NAME=value, declare -x NAME=value, atau NAME=value, dengan nilai yang akan digunakan Bash persis seperti yang ditulis, tersusun dari campuran bagian-bagian berikut: teks tanpa tanda kutip yang hanya menggunakan huruf, angka, dan karakter _ @ % + = : , . / -, teks dalam tanda kutip tunggal, dan teks dalam tanda kutip ganda yang setiap $, backtick, atau " di dalamnya di-escape dengan backslash

Setup

Input Setup

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Setup",
  "trigger": "init"
}

Kontrol keputusan Setup

InstructionsLoaded

Input InstructionsLoaded

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "InstructionsLoaded",
  "file_path": "/Users/my-project/CLAUDE.md",
  "memory_type": "Project",
  "load_reason": "session_start"
}

Kontrol keputusan InstructionsLoaded

UserPromptSubmit

• Tugas terjadwal bercakupan sesi yang dipicu, termasuk iterasi /loop
• Subagent latar belakang yang melapor kembali ke sesi yang memulainya
• Pesan yang dikirim sesi lain ke percakapan utama Anda
• Output kode Claude dalam sesi Code Mode, untuk hook command, http, dan mcp_tool, saat kode dapat berjalan di latar belakang

Esc selama pemeriksaan prompt

Input UserPromptSubmit

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "Write a function to calculate the factorial of a number"
}

Kontrol keputusan UserPromptSubmit

• Stdout teks biasa: Claude Code menambahkan stdout yang diperlakukannya sebagai teks biasa ke konteks Claude
• JSON dengan additionalContext: gunakan format JSON di bawah ini untuk kontrol yang lebih besar. Kolom additionalContext ditambahkan sebagai konteks

{
  "decision": "block",
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "My additional context here",
    "sessionTitle": "My session title",
    "suppressOriginalPrompt": true
  }
}

Jejak yang ditinggalkan prompt yang diblokir

UserPromptExpansion

Input UserPromptExpansion

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../00893aaf.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "UserPromptExpansion",
  "expansion_type": "slash_command",
  "command_name": "example-skill",
  "command_args": "arg1 arg2",
  "command_source": "plugin",
  "prompt": "/example-skill arg1 arg2"
}

Kontrol keputusan UserPromptExpansion

{
  "decision": "block",
  "reason": "This slash command is not available",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptExpansion",
    "additionalContext": "Additional context for this expansion"
  }
}

MessageDisplay

• menghapus markdown untuk tampilan minimal
• mengubah teks yang ditampilkan aplikasi Agent SDK kepada penggunanya
• menyamarkan kunci API atau hostname internal dari respons Claude

Input MessageDisplay

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "MessageDisplay",
  "turn_id": "0c9e6a2f-7d41-4f4e-9a15-3f4f7c2b8d10",
  "message_id": "5b2a9c8e-1f63-4d8a-b7c4-9e0d2a6f1c3b",
  "index": 0,
  "final": false,
  "delta": "Here is the plan:\n"
}

Output MessageDisplay

{
  "hooks": {
    "MessageDisplay": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

#!/bin/bash
jq '{hookSpecificOutput: {hookEventName: "MessageDisplay", displayContent: (.delta | gsub("\\*\\*"; "") | gsub("`"; ""))}}'

{
  "hooks": {
    "MessageDisplay": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-File",
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.ps1"
            ]
          }
        ]
      }
    ]
  }
}

$batch = [Console]::In.ReadToEnd() | ConvertFrom-Json
$text = $batch.delta -replace '\*\*', '' -replace '`', ''
@{
  hookSpecificOutput = @{
    hookEventName = "MessageDisplay"
    displayContent = $text
  }
} | ConvertTo-Json

PreToolUse

Input PreToolUse

• Claude Code memperluas ~ dan path relatif sebelum hook berjalan, sehingga hook yang mencocokkan path tidak dapat dilewati melalui ~ atau penulisan relatif dari path yang sama
• Di Windows, path tiba dengan pemisah backslash, bahkan saat hook Anda berjalan di Git Bash tempat $PWD terlihat seperti /c/project
• Perbandingan yang ditulis dengan garis miring, seperti pemeriksaan /src/, tidak pernah cocok dengan path backslash, dan panggilan tool berlanjut seolah-olah hook tidak menemukan apa pun untuk diblokir
• Normalisasikan pemisah sebelum membandingkan: FILE_PATH="${FILE_PATH//\\//}" di Bash, atau file_path.replace("\\", "/") di Python, lalu cocokkan segmen path seperti /src/ alih-alih menambatkan dengan ^, karena path-nya absolut

{
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "C:\\project\\src\\index.ts",
    "content": "..."
  },
  ...
}

Bash

PowerShell

• Di Windows, di mana pun tool PowerShell diaktifkan, Claude memperlakukan PowerShell sebagai shell utama dan mengarahkan perintah shell melaluinya.
• Di Windows tanpa Git Bash, tool tersebut diaktifkan secara otomatis dan Claude Code sama sekali tidak mendaftarkan tool Bash.
• Hook yang hanya cocok dengan Bash tidak pernah dipicu di sana.

Write

Edit

Read

Glob

Grep

WebFetch

WebSearch

Agent

AskUserQuestion

ExitPlanMode

Kontrol keputusan PreToolUse

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "My reason here",
    "updatedInput": {
      "field_to_modify": "new value"
    },
    "additionalContext": "Current environment: production. Proceed with caution."
  }
}

updatedInput PreToolUse dalam auto mode

a hook changed this call's input after auto mode reviewed it

• Hook dapat menolak panggilan atau mengirimkannya ke permintaan izin
• updatedInput apa pun yang dikembalikannya dibuang, sehingga yang dijalankan adalah apa yang ditinjau server

Keputusan ask PreToolUse di auto mode

• Panggilan yang juga ditandai oleh pemeriksaan Claude Code sendiri: ini termasuk penulisan ke path yang dilindungi dan perintah yang meminta untuk berjalan di luar sandbox. Pengklasifikasi dapat menolak salah satu panggilan ini sebelum permintaan apa pun muncul. Jika pengklasifikasi menyetujui, panggilan biasanya tetap diteruskan ke permintaan izin.
• Panggilan SubagentHandback: tool ini mengirimkan laporan subagent. Tidak ada permintaan izin yang muncul untuknya, dan panggilan tetap berjalan meskipun pengklasifikasi keberatan.

Tool yang memerlukan interaksi pengguna

1. Membaca input tool dari stdin
2. Mengumpulkan jawaban melalui UI Anda sendiri
3. Mengembalikan permissionDecision: "allow" bersama updatedInput yang berisi jawaban, sehingga tool berjalan tanpa permintaan

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "updatedInput": {
      "questions": [
        {
          "question": "Which framework?",
          "header": "Framework",
          "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}],
          "multiSelect": false
        }
      ],
      "answers": {"Which framework?": "React"}
    }
  }
}

Menangguhkan panggilan tool untuk nanti

• Dalam sesi interaktif: Claude Code mencatat peringatan ke log dan mengabaikan hasil hook
• Beberapa panggilan tool sekaligus: "defer" diabaikan dengan peringatan dan tool berjalan melalui alur izin normal

1. Claude memanggil AskUserQuestion. Hook PreToolUse dipicu.
2. Hook mengembalikan permissionDecision: "defer". Tool tidak dieksekusi. Giliran berakhir dengan hasil yang membawa stop_reason: "tool_deferred", dan panggilan tool yang tertunda tetap berada di transkrip.
3. Proses pemanggil membaca deferred_tool_use dari hasil SDK, menampilkan pertanyaan di UI-nya sendiri, dan menunggu jawaban.
4. Proses pemanggil menjalankan claude -p --resume <session-id> dengan host izin yang sama. Panggilan tool yang sama memicu PreToolUse lagi.
5. Hook mengembalikan permissionDecision: "allow" dengan jawaban di updatedInput. Tool dieksekusi dan Claude melanjutkan.

{
  "type": "result",
  "subtype": "success",
  "stop_reason": "tool_deferred",
  "session_id": "abc123",
  "deferred_tool_use": {
    "id": "toolu_01abc",
    "name": "AskUserQuestion",
    "input": { "questions": [{ "question": "Which framework?", "header": "Framework", "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}], "multiSelect": false }] }
  }
}

Melanjutkan ketika tool yang ditunda tidak tersedia

• Untuk menjalankan panggilan: buat tool tersedia dan lanjutkan lagi.
• Untuk membuang panggilan: lanjutkan dengan prompt dan CLAUDE_CODE_DROP_UNAVAILABLE_DEFERRED_TOOL diatur ke 1. Claude menerima error sebagai hasil panggilan dan menjawab prompt Anda. Saat Anda melanjutkan nanti, tidak ada panggilan yang tertunda.

PermissionRequest

Input PermissionRequest

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PermissionRequest",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf node_modules",
    "description": "Remove node_modules directory"
  },
  "permission_suggestions": [
    {
      "type": "addRules",
      "rules": [{ "toolName": "Bash", "ruleContent": "rm -rf node_modules" }],
      "behavior": "allow",
      "destination": "localSettings"
    }
  ]
}

Kontrol keputusan PermissionRequest

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {
        "command": "npm run lint"
      }
    }
  }
}

Entri pembaruan izin

• Bash(npm test): { "toolName": "Bash", "ruleContent": "npm test" }
• Bash atau Bash(*): { "toolName": "Bash" }, karena keduanya mencocokkan seluruh tool
• mcp__github__get_issue: { "toolName": "mcp__github__get_issue" }

PostToolUse

• Untuk menjalankan hook setelah tool apa pun berhasil diselesaikan, hilangkan matcher atau atur ke "*". Hook Anda kemudian dapat menemukan sendiri apa yang berubah, misalnya dengan menjalankan git status --porcelain, yang juga mencantumkan file yang tidak terlacak yang terlewat oleh git diff. Untuk panggilan tool yang gagal, tambahkan hook yang sama di bawah PostToolUseFailure.
• Untuk menjalankan hook ketika file tertentu berubah di disk, apa pun yang menulisnya, gunakan FileChanged. Claude Code tidak menjalankan hook PostToolUse yang mencocokkan Edit|Write ketika perintah Bash atau proses di luar Claude Code menulis ulang file yang sama.

PostToolUse setelah interupsi

• Ctrl+Enter: jika menekannya mengakhiri giliran saat tool sedang berjalan dan tool selesai, hook PostToolUse Anda berjalan pada hasilnya dan memiliki waktu 10 detik untuk selesai. Tombol ini berfungsi sebagai Esc jika Anda mengantrekan perintah ! sebelum pesan Anda atau tugas latar belakang dinonaktifkan, misalnya dengan CLAUDE_CODE_DISABLE_BACKGROUND_TASKS.
• Enter: pesan yang Anda antrekan dengan Enter tidak menginterupsi giliran, sehingga hook mempertahankan timeout biasanya.
• Esc: Anda langsung membatalkan hook, jadi kirim pesan dengan Enter atau Ctrl+Enter ketika hook harus berjalan.

Input PostToolUse