Skip to content
ตอนคุยกับทีม dev ลูกค้าที่กรุงเทพฯ เมื่อสัปดาห์ก่อน มีคนถามผมว่า “พี่อาร์ตี้ครับ Claude Code hooks มีกี่ event กันแน่? ผมเปิดเอกสารแล้วงงเลย” 555 คือผมเข้าใจเลยล่ะครับ เพราะตอน Anthropic เปิดตัว hooks ครั้งแรกมีแค่ 7 event แต่พอเข้าปี 2026 ขยายไปเป็น 21 ตัว แล้วล่าสุดที่ผมเช็คใน official docs รอบนี้ขึ้นไป 27 event เรียบร้อย
ที่หนักกว่านั้นคือถ้าคุณยังจำได้แค่ PreToolUse กับ PostToolUse เหมือนเมื่อกลางปีที่แล้ว คุณจะพลาดของใหม่อย่าง CwdChanged, FileChanged, PermissionDenied ที่เพิ่มเข้ามาในรอบหลัง ซึ่งเอาจริงๆ มันแก้ปัญหาให้ทีม dev ผมไปหลายเคสแล้ว
โพสต์นี้ผมเลยทำ reference table ของ Claude Code hooks events ทั้ง 27 ตัวสำหรับปี 2026 ไว้ในที่เดียว พร้อมบอกว่าตัวไหน block ได้ ตัวไหนรับ matcher ตัวไหนเพิ่งมาใหม่ — เปิดทิ้งไว้แท็บนึงเวลา config ~/.claude/settings.json ครับ
ใครยังใหม่กับ Claude Code ลองอ่าน Claude Code คืออะไร? คู่มือทีม Dev ไทย ปี 2026 ก่อนได้ครับ
TL;DR สรุปสั้นๆ
- Claude Code hooks มีทั้งหมด 27 events ในปี 2026 (ขยายจาก 21 event ตามที่ smartscope.blog รายงานเมื่อเดือนมีนาคม)
- แบ่งเป็น 7 กลุ่ม: Session lifecycle, User prompt, Tool execution, Subagents/Tasks, Context compaction, MCP elicitation, Environment & worktrees
- Block ได้ 9 event (PreToolUse, UserPromptSubmit, UserPromptExpansion, PermissionRequest, Stop, SubagentStop, TaskCompleted, ConfigChange, Elicitation, ElicitationResult) — ที่เหลือ “fire-and-forget”
- 4 hook handler types:
command,http,prompt,agent - ของใหม่ปี 2026 ที่ทีม dev ไทยยังไม่ค่อยรู้:
PermissionDenied,CwdChanged,FileChanged,PostToolBatch,InstructionsLoaded
ทำไม events list มันสำคัญ (และทำไมจำผิดทำงานพัง)
Hook ใน Claude Code คือ “middleware” ที่ยิง shell command, HTTP request หรือ prompt-based LLM call ตอนเกิด lifecycle event โดยไม่ต้องไปแก้ตัว binary ของ Claude Code เอง ที่ official guide ใช้คำว่า “format files after edits, block commands before they execute, send notifications when Claude needs input, inject context at session start”
ปัญหาคือ — ถ้าคุณตั้ง hook ผิด event มัน “ดู” เหมือนทำงาน แต่จริงๆ ไม่ยิง 55 ผมเคยเจอเคสจริงในทีม คือ dev คนนึงตั้ง hook Stop เพื่อรัน prettier หลัง Claude จบ task แต่จริงๆ เขาควรใช้ PostToolUse + matcher Edit|Write|MultiEdit ผลคือ format ทำงานช้าไป 1 turn เสมอ debug กันเป็นชั่วโมง
💡 Lesson learned: “จำชื่อ event ให้ครบ + รู้ว่าตัวไหน block ได้” คือ 80% ของการใช้ hooks ให้คุ้ม
ตารางสรุป Claude Code Hooks Events ทั้ง 27 ตัว (ปี 2026)
ตารางนี้ผมรวบรวมจาก official hooks reference ของ Anthropic ตามสถานะวันที่ผมเขียน (พฤษภาคม 2026) เรียงตาม lifecycle เพื่อให้เห็นภาพรวม ตัวเลขในวงเล็บคือ “เพิ่มเข้ามาเมื่อ”
| # | Event | เกิดตอนไหน | Block ได้? | Matcher |
|---|---|---|---|---|
| 1 | Setup |
เปิดด้วย --init-only / --init / --maintenance |
— | ไม่มี |
| 2 | SessionStart |
เปิด session หรือ resume | — | startup / resume / clear / compact |
| 3 | InstructionsLoaded (new 2026) |
โหลด CLAUDE.md หรือ .claude/rules/*.md |
— | ไม่มี |
| 4 | UserPromptSubmit |
ตอน user กด enter ก่อน Claude เห็น prompt | ✅ | ไม่มี |
| 5 | UserPromptExpansion (new 2026) |
ตอน slash command ถูก expand เป็น prompt | ✅ | ชื่อ command |
| 6 | PreToolUse |
ก่อนเรียก tool ทุกครั้ง | ✅ | ชื่อ tool (เช่น Bash, Edit|Write, mcp__.*) |
| 7 | PermissionRequest |
ตอน permission dialog เด้ง | ✅ | ชื่อ tool |
| 8 | PermissionDenied (new 2026) |
ตอน auto-mode classifier ปฏิเสธ tool call | — | ชื่อ tool |
| 9 | PostToolUse |
หลัง tool รันสำเร็จ | — | ชื่อ tool |
| 10 | PostToolUseFailure |
หลัง tool รัน fail | — | ชื่อ tool |
| 11 | PostToolBatch (new 2026) |
หลัง parallel tool batch จบ ก่อน Claude เรียก model รอบถัดไป | — | ไม่มี |
| 12 | Notification |
ตอน Claude Code ส่ง notification (permission_prompt, idle_prompt, auth_success) | — | ชนิด notification |
| 13 | SubagentStart |
ตอน subagent ถูก spawn ผ่าน Task tool | — | ชื่อ subagent |
| 14 | SubagentStop |
ตอน subagent ทำงานเสร็จ | ✅ | ชื่อ subagent |
| 15 | TaskCreated |
ตอนใช้ TaskCreate สร้าง task |
— | ไม่มี |
| 16 | TaskCompleted |
ตอน task ถูก mark เป็น complete | ✅ | ไม่มี |
| 17 | TeammateIdle |
Agent Teams teammate กำลังจะ idle | ✅ | ไม่มี |
| 18 | Stop |
Claude เขียนตอบเสร็จ จบ turn | ✅ | ไม่มี |
| 19 | StopFailure |
Turn จบเพราะ API error (output/exit ถูก ignore) | — | ไม่มี |
| 20 | PreCompact |
ก่อน context compaction | — | manual / auto |
| 21 | PostCompact |
หลัง compaction เสร็จ | — | ไม่มี |
| 22 | Elicitation |
MCP server ขอ input จาก user ระหว่าง tool call | ✅ | ชื่อ MCP server |
| 23 | ElicitationResult |
หลัง user ตอบกลับ MCP elicitation ก่อนส่งกลับ server | ✅ | ชื่อ MCP server |
| 24 | ConfigChange (new 2026) |
Config file ถูกแก้ระหว่าง session | ✅ | path |
| 25 | CwdChanged (new 2026) |
Working directory เปลี่ยน (เช่น Claude รัน cd) |
— | ไม่มี |
| 26 | FileChanged (new 2026) |
Watched file ถูกแก้บน disk | — | filename pattern |
| 27 | WorktreeCreate / WorktreeRemove (new 2026) |
Git worktree ถูกสร้าง/ลบ ผ่าน --worktree หรือ isolation: "worktree" |
— | ไม่มี |
| 28 | SessionEnd |
Session terminate | — | clear / logout |
(หมายเหตุ: WorktreeCreate กับ WorktreeRemove นับเป็น event แยกกันคู่หนึ่งใน table official รวมแล้ว 27 event — ผมรวมเป็นแถวเดียวเพื่อกระชับ)
กลุ่มที่ 1 — Session Lifecycle (4 events)
Setup → SessionStart → InstructionsLoaded → SessionEnd
กลุ่มนี้ใช้ทำ “session bootstrap” — โหลด env, inject context, log timing
💡 ของที่ผมใช้บ่อย: ตั้ง SessionStart hook ให้รัน git status แล้ว pipe ผ่าน stdout เข้า Claude (เพราะ exit 0 + เขียน stdout ของ event นี้จะถูก append เข้า context อัตโนมัติ — ตามที่ระบุใน official hooks-guide) ทำให้ Claude เริ่ม session ปุ๊ปก็รู้เลยว่า branch ไหน มี uncommitted อะไรบ้าง ไม่ต้องบอกซ้ำๆ ทุกครั้ง
InstructionsLoaded เพิ่งเพิ่มมาปี 2026 — เอาไว้ audit ว่า rules file ตัวไหนถูกโหลดเข้า context บ้าง ไม่ block แค่ observe
กลุ่มที่ 2 — User Prompt Lifecycle (2 events)
UserPromptSubmit → UserPromptExpansion
UserPromptSubmit ยิงตอนคุณพิมพ์ enter ก่อน Claude เห็น prompt — block ได้ ใช้ทำ security filter (เช่น regex จับ secret ไม่ให้หลุดออก context) หรือ inject prompt template อัตโนมัติ
UserPromptExpansion เป็นของใหม่ ยิงตอน slash command (เช่น /init, /clear) ถูก expand เป็น prompt — ใช้ block หรือแก้ command ของ user ก่อนไปถึง model
เคสจริง: ลูกค้า enterprise คนนึงตั้ง UserPromptSubmit hook เพื่อ block prompt ที่มีคำว่า “ลบ” หรือ “drop database” — exit code 2 + เขียน error ลง stderr Claude ก็จะเห็น feedback เลย
กลุ่มที่ 3 — Tool Execution Lifecycle (7 events)
PreToolUse → PermissionRequest → PermissionDenied → PostToolUse / PostToolUseFailure → PostToolBatch
กลุ่มนี้คือกลุ่มที่คนใช้บ่อยที่สุด — ในตัวอย่าง claude-code-hooks-mastery repo บน GitHub ก็เน้นกลุ่มนี้เป็นหลัก
Pattern ที่ผมใช้ในทีมจริงๆ:
PreToolUse+ matcherBash— blockrm -rf,chmod 777, การแตะ.envdirectPostToolUse+ matcherEdit|Write|MultiEdit— รันprettier/biome/ruffauto-formatPostToolUseFailure— log failure ลง~/.claude/failures.jsonlสำหรับ retro ทีมPostToolBatch(ใหม่ปี 2026) — ยิงตอน parallel tool batch จบทั้ง batch ก่อน model รอบถัดไป ใช้ทำ “post-batch validation” เช่น เช็คว่าทุกไฟล์ที่แก้ใน batch นั้น passtsc --noEmitก่อน Claude คิดต่อ
ส่วน PermissionDenied เพิ่งเพิ่มปี 2026 — ยิงตอน auto-mode classifier ปฏิเสธ tool call ถ้า hook return {retry: true} Claude จะ retry อีกครั้ง เคสที่ผมเจอ: ใช้กับ MCP tool ที่ classifier เข้าใจผิดบ่อย เราเขียน hook judge เพิ่มอีกชั้นว่าควร retry หรือไม่
กลุ่มที่ 4 — Subagents & Agent Teams (5 events)
SubagentStart → SubagentStop → TaskCreated → TaskCompleted → TeammateIdle
กลุ่มนี้เพิ่งสำคัญขึ้นมาเยอะตอน Anthropic ปล่อย Agent Teams ปี 2026 ครับ ใครยังไม่รู้จัก subagents ลองอ่าน คู่มือ Claude Code Subagents ของผม ก่อน
ความต่าง:
SubagentStart/SubagentStop— ยิงตอน Task tool spawn subagent (instance ใหม่ของ Claude)TaskCreated/TaskCompleted— ยิงตอน task object ถูกสร้าง/mark complete (อาจไม่ใช่ subagent ก็ได้)TeammateIdle— ใหม่ ยิงตอน Agent Teams teammate กำลังจะเข้า idle state ใช้ reassign งานก่อนเข้าหลับ
💡 ของที่ผมแนะนำ: ใช้ SubagentStop + exit 2 เพื่อ บังคับ subagent ให้ทำต่อถ้าผลลัพธ์ไม่ครบ — เช่นถ้า subagent ทำ test แล้ว fail ให้ block stop ไม่ให้กลับมา parent agent จนกว่าจะ pass
กลุ่มที่ 5 — Context Compaction (2 events)
PreCompact → PostCompact
Context compaction คือตอน Claude Code “ย่อ” transcript เพื่อให้พอดี context window — เป็นเรื่องสำคัญมากในการทำ long-running agent ครับ ใครยังไม่ familiar ลองอ่าน Context Engineering สำหรับ Claude Code 2026 ก่อน
PreCompact matcher รับ manual หรือ auto — ผมตั้ง hook backup transcript ลง ~/.claude/backups/ ทุกครั้งก่อน compact เพราะข้อมูลก่อน compact มันจะหายไปจริงๆ recover ไม่ได้
PostCompact ใช้ inject context กลับเข้ามาหลัง compact เสร็จ (กันหลงๆ ลืมๆ project state)
กลุ่มที่ 6 — MCP Elicitation (2 events)
Elicitation → ElicitationResult
ใหม่ในปี 2026 รองรับ MCP elicitation flow (เช่น MCP server ขอข้อมูล credential หรือ confirmation จาก user ก่อนทำงานต่อ)
Elicitation block ได้ (decline request เลย) ส่วน ElicitationResult ยิงหลัง user ตอบกลับก่อน response ถูกส่งกลับ MCP server — แก้ไข response ได้ด้วย (เช่น redact ข้อมูล sensitive ออกก่อนส่งกลับ)
กลุ่มที่ 7 — Environment & Worktrees (5 events)
Notification, ConfigChange, CwdChanged, FileChanged, WorktreeCreate/WorktreeRemove
กลุ่มนี้เป็น “async event” — ยิงตามสภาพแวดล้อมเปลี่ยน ไม่ได้อยู่ใน main loop
Notification— เก่า ยังใช้บ่อย ผม map กับnotify-send(Linux) หรือosascript display notification(macOS) ตามที่ official docs แนะนำCwdChanged— ใหม่ปี 2026 ยิงเวลา working directory เปลี่ยน เหมาะกับdirenvreactive env managementFileChanged— ใหม่ ใช้ watch file นอก scope ที่ Claude เห็น (เช่นpackage.jsonของ project อื่น) — matcher รับ pattern แบบ globConfigChange— ใหม่ block ได้ ใช้ป้องกัน Claude แก้.claude/settings.jsonเอง (หรือ audit ทุก change)WorktreeCreate/WorktreeRemove— ใหม่ สำหรับ--worktreeisolation pattern ของ Claude Code ปี 2026
4 Hook Handler Types (อย่าใช้ผิดประเภท)
นอกจากชื่อ event แล้วต้องเลือก handler type ให้ถูกด้วย ตามที่ smartscope.blog สรุปไว้:
command— shell command (ใช้ 90% ของ use case)http— POST event payload ไป HTTP endpoint (สำหรับ centralized audit log ทีม)prompt— single-turn LLM evaluation (ใช้กับ event ที่ต้อง judgment เช่นPreToolUse,Stop,TaskCompleted)agent— multi-turn LLM ที่มี tool access (สำหรับ decision ซับซ้อนที่ต้องอ่าน file)
💡 ของที่ผมเห็นทีม dev ไทยทำพลาดบ่อย: ใช้ command กับ Stop hook แล้วเขียน bash logic ซับซ้อน 100 บรรทัด — จริงๆ ควรใช้ prompt handler ให้ LLM ตัดสินใจจะ short และ maintainable กว่า
Async Execution (ปี 2026)
ตั้งแต่ Anthropic ปล่อย async hooks ในเดือนมกราคม 2026 hook ทุกชนิดเพิ่ม flag async: true เข้ามาได้ — รันใน background ไม่ block Claude เหมาะกับ logging, analytics, backup และ notification
ข้อควรระวัง: async hook block ไม่ได้ — ถ้าใส่ async: true กับ PreToolUse hook ที่ตั้งใจจะ block exit code 2 จะถูก ignore
3 Gotcha ที่ทีม dev ไทยเจอบ่อย
1) Matcher case-sensitive และไม่ใช่ทุก event ใช้ matcher ได้ — UserPromptSubmit, PostToolBatch, Stop, TeammateIdle, TaskCreated, TaskCompleted, WorktreeCreate, WorktreeRemove, CwdChanged ไม่รับ matcher ถ้าใส่ไป มันจะถูก ignore เงียบๆ ไม่ error
2) Exit code 2 behavior ต่างกันต่อ event — บาง event block ได้จริง (PreToolUse, UserPromptSubmit, PermissionRequest, Stop, SubagentStop, TaskCompleted, ConfigChange, Elicitation) บาง event แค่แสดง stderr ให้ user เห็น (PostToolUse, Notification, SessionStart, PreCompact) อย่าจำสลับ
3) Stdout ของ exit 0 hook ถูก append เข้า context เฉพาะ 3 event เท่านั้น — UserPromptSubmit, UserPromptExpansion, SessionStart ตามที่ระบุใน official hooks-guide ถ้าคุณ echo stdout ใน PostToolUse หวังให้ Claude เห็น จะไม่เกิดอะไรขึ้น
เปรียบเทียบกับ Claude Code Hooks ของปี 2025
ใครยังจำได้ปี 2025 Claude Code hooks มีแค่ 7 event (PreToolUse, PostToolUse, UserPromptSubmit, Notification, Stop, SubagentStop, PreCompact, SessionStart) — รอบมีนาคม 2026 ขยายไปเป็น 21 event แล้วล่าสุดที่ผมเช็คเข้าใกล้ 27 event เรียบร้อย
เทรนด์ชัดเจน: Anthropic กำลังเปิดให้ทีม dev มี fine-grained control ทุกจุดของ agent loop — โดยเฉพาะกลุ่ม Agent Teams, MCP, และ Worktrees ที่เพิ่มมาทั้งกลุ่ม
FAQ
Claude Code hooks events มีกี่ตัวในปี 2026?
ตามที่ผมเช็คจาก official docs ของ Anthropic เดือนพฤษภาคม 2026 มีทั้งหมด 27 event แบ่งเป็น 7 กลุ่ม: Session lifecycle, User prompt, Tool execution, Subagents/Tasks, Context compaction, MCP elicitation, และ Environment & worktrees ครับ
Hook event ไหนบ้างที่ block การทำงานของ Claude ได้?
มี 10 event ที่ block ได้ด้วย exit code 2 ได้แก่ PreToolUse, UserPromptSubmit, UserPromptExpansion, PermissionRequest, Stop, SubagentStop, TaskCompleted, TeammateIdle, ConfigChange, Elicitation, ElicitationResult ส่วน event ที่เหลือเขียน stderr ได้แต่ไม่หยุดการทำงานครับ
Hook event ไหนใหม่ในปี 2026 บ้าง?
ของใหม่ที่ผมแนะนำให้ทีม dev ไทยรู้จัก: PermissionDenied, PostToolBatch, UserPromptExpansion, InstructionsLoaded, ConfigChange, CwdChanged, FileChanged, WorktreeCreate/WorktreeRemove, TeammateIdle, PostCompact, Elicitation/ElicitationResult รวมๆ ประมาณ 12 event ใหม่ขยายจาก base ปี 2025
ใช้ async hook กับ PreToolUse เพื่อ block ได้ไหม?
ไม่ได้ครับ ถ้าตั้ง async: true hook จะรันใน background และ exit code จะถูก ignore — ใช้ async กับ logging, analytics, notification เท่านั้น สำหรับ blocking ต้อง sync hook
ตั้ง hook ที่ไหน global vs project?
มี 3 ระดับ: ~/.claude/settings.json (global user), .claude/settings.json (per-project commit เข้า git ได้), .claude/settings.local.json (per-project ไม่ commit) — รัน /hooks ใน Claude Code เพื่อดูว่า hook ไหน active อยู่
#สรุป
Claude Code hooks เข้าปี 2026 ขยายจาก 7 event เป็น 27 event — เปลี่ยนจาก “format ไฟล์หลัง edit” ไปเป็น “lifecycle middleware ครอบทั้ง agent loop, MCP, Agent Teams, worktree”
ถ้าจะใช้ให้คุ้ม: จำชื่อ event ให้ครบ + รู้ว่าตัวไหน block ได้ + เลือก handler type ให้ถูก ไม่ต้องใช้ทุกตัวพร้อมกัน แต่ต้องรู้ว่ามีอะไรให้เลือก เพราะใช้ผิด event เสียเวลา debug มากกว่าเขียน config ใหม่ครับ
ใครยังไม่ได้ลอง hook เลย แนะนำเริ่มที่ 5 Recipes Claude Code Hooks สำหรับทีม Dev ไทย ที่ผมเขียนไว้ก่อน แล้วค่อยกลับมาที่ตารางนี้เวลา reference ครับ
การเลือก hook event ให้ถูก ก็เหมือนการตั้งกล้องวงจรปิดในร้าน — ตั้งถูกมุม ดูภาพรวมได้ทันที ตั้งผิดมุม เห็นแต่กำแพง 55
รับคู่มือ Claude AI + บทความใหม่ก่อนใคร
สมัครรับจดหมายจากอาร์ตี้ — ไม่สแปม ไม่เกิน 1–2 ฉบับ/สัปดาห์