อ้างอิง Hooks

ภาพรวม

Hooks คือ shell command, HTTP endpoint หรือ LLM prompt ที่ผู้ใช้กำหนดซึ่งรันอัตโนมัติที่จุดเฉพาะใน lifecycle ของ Claude Code ช่วยให้สามารถทำงานอัตโนมัติ ตรวจสอบ และผสานรวมพฤติกรรมแบบกำหนดเองตลอด workflow การพัฒนา

Hook Lifecycle

Hooks ทำงานที่จุดเฉพาะระหว่างเซสชัน Claude Code โดยมีสามจังหวะ:

• ครั้งเดียวต่อเซสชัน: SessionStart, SessionEnd
• ครั้งเดียวต่อ turn: UserPromptSubmit, Stop, StopFailure
• ทุก tool call: PreToolUse, PostToolUse

การกำหนดค่า

Hooks ถูกกำหนดในไฟล์ settings JSON ที่มีสามระดับการซ้อน:

1. Hook event (เช่น PreToolUse, Stop)
2. Matcher group เพื่อกรองเมื่อไรที่จะทำงาน (เช่น "เฉพาะสำหรับ Bash tool")
3. Hook handlers ที่รันเมื่อตรงกัน

ตำแหน่งและ Scope ของ Hook

ตำแหน่ง	Scope	แชร์ได้
~/.claude/settings.json	ทุกโปรเจกต์	ไม่
.claude/settings.json	โปรเจกต์เดียว	ใช่
.claude/settings.local.json	โปรเจกต์เดียว	ไม่
Managed policy settings	ทั่วทั้งองค์กร	ใช่
Plugin hooks/hooks.json	เมื่อเปิดใช้ plugin	ใช่
Skill/agent frontmatter	ช่วงชีวิตของ component	ใช่

Matcher Patterns

ค่า Matcher	การประเมิน	ตัวอย่าง
"*", "" หรือไม่ระบุ	ตรงกับทั้งหมด	ทำงานทุกครั้ง
ตัวอักษร ตัวเลข _, |	String หรือรายการที่ตรงกันทั้งหมด	Bash หรือ Edit|Write
อักขระอื่น	JavaScript regex	^Notebook หรือ mcp__memory__.*

ประเภท Hook Handler

มี handler ห้าประเภทที่รองรับ:

1. Command hooks (type: "command"): Shell command ที่รับ JSON ผ่าน stdin
2. HTTP hooks (type: "http"): POST request ไปยัง URL
3. MCP tool hooks (type: "mcp_tool"): เรียกใช้ tool บน MCP server
4. Prompt hooks (type: "prompt"): ส่ง prompt ไปยัง Claude เพื่อตัดสิน yes/no
5. Agent hooks (type: "agent"): Spawn subagent สำหรับการตรวจสอบ

ฟิลด์ Handler ทั่วไป

ฟิลด์	จำเป็น	คำอธิบาย
type	ใช่	ประเภท handler: "command", "http", "mcp_tool", "prompt" หรือ "agent"
if	ไม่	Permission rule syntax เพื่อกรองเมื่อไร hook รัน
timeout	ไม่	วินาทีก่อนยกเลิก (ค่าเริ่มต้น: 600 สำหรับ command/http/mcp_tool, 30 สำหรับ prompt, 60 สำหรับ agent)
statusMessage	ไม่	ข้อความ spinner แบบกำหนดเองขณะ hook รัน

Hook Input และ Output

ฟิลด์ Input ทั่วไป

ฟิลด์	คำอธิบาย
session_id	ตัวระบุเซสชันปัจจุบัน
transcript_path	Path ไปยัง conversation JSON
cwd	Current working directory
permission_mode	Permission mode ปัจจุบัน
hook_event_name	ชื่อ event ที่ทำงาน

Exit Code Output

Code	ความหมาย
0	สำเร็จ; stdout ถูก parse สำหรับ JSON output
2	ข้อผิดพลาดที่ blocking; stderr แสดงให้ Claude และ action ถูก block
อื่น	ข้อผิดพลาดที่ไม่ blocking; stderr แสดงใน transcript การรันดำเนินต่อ

ฟิลด์ JSON Output

ฟิลด์	ค่าเริ่มต้น	คำอธิบาย
continue	true	ถ้า false Claude หยุดประมวลผล
stopReason	ไม่มี	ข้อความที่แสดงเมื่อ continue: false
suppressOutput	false	ถ้า true ซ่อน hook stdout
systemMessage	ไม่มี	ข้อความเตือนที่แสดงให้ผู้ใช้
additionalContext	ไม่มี	String ที่เพิ่มเข้าสู่ context ของ Claude

Hook Events สำคัญ

SessionStart

ทำงานเมื่อเซสชันเริ่มหรือ resume มีประโยชน์สำหรับโหลด development context

ค่า Matcher: startup, resume, clear, compact

ฟิลด์ output เพิ่มเติม:

• additionalContext: Context ที่เพิ่มก่อน prompt แรก
• sessionTitle: ตั้งชื่อเซสชัน
• watchPaths: Array ของ path ที่ดูสำหรับ FileChanged events

PreToolUse

ทำงานก่อน tool call รัน สามารถ block หรือแก้ไข tool call

ค่า Matcher: ชื่อ tool เช่น Bash, Edit หรือ mcp__memory__.*

ฟิลด์พิเศษ:

• permissionDecision: "allow", "deny", "ask" หรือ "defer"
• updatedInput: Arguments ของ tool ที่แก้ไขก่อนการรัน

PostToolUse

ทำงานหลังจาก tool call สำเร็จ

ฟิลด์พิเศษ:

• updatedToolOutput: แทนที่ผลลัพธ์ของ tool

Stop

ทำงานเมื่อ Claude ตอบสนองเสร็จ สามารถ block หรือให้ feedback

ฟิลด์พิเศษ:

• decision: "block" เพื่อป้องกันการสิ้นสุด
• additionalContext สำหรับ feedback ที่ไม่ใช่ข้อผิดพลาดที่ต่อ conversation

UserPromptSubmit

ทำงานเมื่อผู้ใช้ submit prompt ก่อนที่ Claude จะประมวลผล

ค่าเริ่มต้น timeout: 30 วินาที (สั้นกว่า event อื่น)

ฟิลด์ Command Hook

ฟิลด์	จำเป็น	คำอธิบาย
command	ใช่	Shell command หรือ executable path
args	ไม่	Argument list สำหรับ exec form
async	ไม่	ถ้า true รันในเบื้องหลังโดยไม่ blocking
shell	ไม่	"bash" (ค่าเริ่มต้น) หรือ "powershell"

ฟิลด์ HTTP Hook

ฟิลด์	จำเป็น	คำอธิบาย
url	ใช่	URL สำหรับ POST request
headers	ไม่	HTTP header เพิ่มเติมเป็น key-value pairs

ฟิลด์ MCP Tool Hook

ฟิลด์	จำเป็น	คำอธิบาย
server	ใช่	ชื่อ MCP server ที่กำหนดค่า
tool	ใช่	ชื่อ tool ที่จะเรียก
input	ไม่	Arguments ที่ส่งไปยัง tool

อ้างอิง Script ด้วย Path

ใช้ placeholder เหล่านี้ในคำสั่ง hook:

• ${CLAUDE_PROJECT_DIR}: Project root
• ${CLAUDE_PLUGIN_ROOT}: Plugin installation directory
• ${CLAUDE_PLUGIN_DATA}: Plugin persistent data directory

ใช้ exec form สำหรับ path placeholder เพื่อหลีกเลี่ยงปัญหา shell quoting:

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

เมนู /hooks

พิมพ์ /hooks ใน Claude Code เพื่อดู hooks ที่กำหนดค่า แสดง hook events, matchers และรายละเอียด handler ทั้งหมด เป็น interface แบบอ่านอย่างเดียว แก้ไข settings JSON โดยตรงเพื่อเพิ่ม แก้ไข หรือลบ hooks

ปิดใช้ Hooks

เพื่อลบ hook: ลบรายการออกจาก settings JSON

เพื่อปิดใช้ hooks ทั้งหมด: ตั้งค่า "disableAllHooks": true ในไฟล์ settings