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 hook event untuk merespons, seperti PreToolUse atau Stop
2. Tambahkan matcher group untuk memfilter kapan dijalankan, seperti “hanya untuk tool Bash”
3. Tentukan satu atau lebih hook handlers untuk dijalankan saat cocok

​

Lokasi hook

• Hooks pengguna, proyek, lokal, dan plugin Anda diblokir. Hooks dari plugins yang dipaksa-aktifkan dalam pengaturan terkelola enabledPlugins dikecualikan
• Claude Code juga mempersempit pengaturan statusLine, fileSuggestion, dan subagentStatusLine Anda ke pengaturan terkelola
• Claude Code juga menonaktifkan plugins dengan sumber command, termasuk plugins yang dipaksa-aktifkan dalam pengaturan terkelola enabledPlugins, kecuali disableCommandPluginSources secara eksplisit diatur ke false. Sumber command memerlukan Claude Code v2.1.229 atau lebih baru
• Claude Code juga memblokir perintah headersHelper marketplace kecuali disableCommandPluginSources secara eksplisit diatur ke false, kecuali untuk marketplace yang pengaturan terkelola sendiri deklarasikan

• allowedHttpHookUrls: ketika didefinisikan di tingkat pengaturan apa pun, Claude Code menjalankan HTTP hook handler hanya jika URL-nya cocok dengan allowlist yang digabungkan
• httpHookAllowedEnvVars: ketika didefinisikan, Claude Code menginterpolasi hanya variabel lingkungan pada daftar itu ke dalam header hook

​

Pola matcher

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

​

Cocokkan MCP tools

• mcp__memory__create_entities: tool create entities dari Memory server
• mcp__filesystem__read_file: tool read file dari Filesystem server
• mcp__github__search_repositories: tool search dari GitHub server

• mcp__memory__.* cocok dengan semua tools dari server memory
• mcp__brave-search__.* cocok dengan semua tools dari server yang namanya berisi tanda hubung
• mcp__.*__write.* cocok dengan tool apa pun yang namanya dimulai dengan write dari server apa 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"
          }
        ]
      }
    ]
  }
}

​

Bidang hook handler

• Command hooks (type: "command"): jalankan perintah shell. Skrip Anda menerima JSON input event di stdin dan mengkomunikasikan hasil kembali melalui kode keluar dan stdout.
• HTTP hooks (type: "http"): kirimkan JSON input event sebagai permintaan HTTP POST ke URL. Endpoint mengkomunikasikan hasil kembali melalui badan respons menggunakan format JSON output yang sama seperti command hooks.
• MCP tool hooks (type: "mcp_tool"): panggil tool pada server MCP yang dikonfigurasi. Output teks tool diperlakukan seperti command-hook stdout.
• Prompt hooks (type: "prompt"): kirimkan prompt ke model Claude untuk evaluasi single-turn. Model mengembalikan keputusannya sebagai JSON. Lihat Prompt-based hooks.
• Agent hooks (type: "agent"): spawn subagent yang dapat menggunakan tools seperti Read, Grep, dan Glob untuk memverifikasi kondisi sebelum mengembalikan keputusan. Agent hooks adalah eksperimental dan mungkin berubah. Lihat Agent-based hooks.

​

Bidang umum

​

Bagaimana pola if mencocokkan perintah Bash

​

Bidang command hook

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

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

​

Bidang HTTP hook

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

​

Bidang MCP tool hook

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

​

Bidang prompt dan agent hook

​

Referensi skrip berdasarkan path

• ${CLAUDE_PROJECT_DIR}: akar proyek tempat sesi dimulai. Claude Code juga menetapkan variabel ini dalam lingkungan stdio MCP servers dan plugin LSP servers.
• ${CLAUDE_PLUGIN_ROOT}: direktori instalasi plugin, untuk skrip yang dibundel dengan plugin. Lihat plugin environment variables untuk bagaimana path berperilaku di seluruh pembaruan.
• ${CLAUDE_PLUGIN_DATA}: direktori data persisten plugin, untuk dependensi dan status yang harus bertahan 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
          }
        ]
      }
    ]
  }
}

​

Hooks dalam skills dan agents

• Subagent hooks: Claude Code menjalankannya hanya saat subagent itu berjalan dan menghapusnya saat selesai. Claude Code mengkonversi hook Stop di sini menjadi SubagentStop, event yang dijalankan saat subagent selesai.
• Skill hooks: Claude Code mendaftarkannya ketika Anda atau Claude memanggil skill dan terus menjalankannya untuk sisa sesi, pada turns setelah turn skill sendiri juga. Untuk membuat Claude Code menghapus hook setelah run pertamanya yang berhasil, atur once: true padanya.

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

​

Menu /hooks

​

Nonaktifkan atau hapus hooks

​

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, dan pada event seperti PreToolUse Anda melihat pemberitahuan <hook name> hook error di transkrip. Jika Anda ingin hook yang gagal memblokir tindakan, atur onFailure: "block".

• 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

• Satu objek JSON, dalam satu baris atau beberapa baris: di-parse sebagai output JSON.
• 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, dan kegagalan parse ketika ada baris yang demikian.
• Apa pun lainnya yang diawali dengan { dan diakhiri dengan } tetapi bukan JSON yang valid: kegagalan parse.

​

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

​

Timeout

• Hook command, http, atau mcp_tool yang mengalami timeout tidak memblokir panggilan tool. Panggilan berlanjut melalui alur izin normal, jadi jangan mengandalkan hook yang macet untuk berfungsi sebagai gerbang. Untuk memblokir panggilan ketika hook command atau http mengalami timeout, atur onFailure: "block".
• Callback hook Agent SDK yang melebihi timeout-nya memblokir panggilan tool.

​

Hook yang memulai proses latar belakang

#!/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

​

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, eksekusi berlanjut
• Kegagalan koneksi: error non-blocking, eksekusi berlanjut
• 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: Claude Code menyimpan output ke file di direktori sesi dan menggantinya 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 ada di layar. Dalam mode non-interaktif dengan flag -p dan di Agent SDK, Claude Code mengabaikan field ini.
• 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}'

​

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. 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

• 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 yang dipicu, termasuk iterasi /loop
• Subagent latar belakang yang melapor kembali ke sesi yang memulainya
• Pesan yang dikirim sesi lain ke percakapan utama Anda

​

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": "..."
  },
  ...
}

• 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.

​

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."
  }
}

​

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

1. Claude memanggil AskUserQuestion. Hook PreToolUse dipicu.
2. Hook mengembalikan permissionDecision: "defer". Tool tidak dieksekusi. Proses keluar dengan stop_reason: "tool_deferred" dan panggilan tool yang tertunda dipertahankan dalam 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 }] }
  }
}

​

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

​

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.