วิธีใช้งาน Claude Code Hooks และการตั้งค่าคำสั่ง Shell
ทำความเข้าใจการทำงานของ Claude Code Hooks ที่รันคำสั่งอัตโนมัติโดยไม่ขึ้นกับโมเดล พร้อมวิธีจัดการ exit code 2 เพื่อยกเลิก tool call และการรับส่งข้อมูลผ่าน stdin
Hook ของ Claude Code คืออะไร
Hook ของ Claude Code คือ shell command ที่ Claude Code เรียกใช้เองเมื่อถึงจุดที่กำหนดในวงจรการทำงานของตัวเอง ความแตกต่างทั้งหมดระหว่าง hook กับ rules file อยู่ตรงนี้ คำสั่งใน CLAUDE.md เป็นเพียงคำแนะนำ และ model จะนำไปพิจารณาร่วมกับข้อมูลอื่นใน context ส่วน hook คือ code และจะทำงานไม่ว่า model จะเห็นด้วยหรือไม่ หาก agent ยังคงข้าม formatter ที่คุณบอกไว้ถึง 2 ครั้ง คุณไม่จำเป็นต้องเขียนคำสั่งให้หนักแน่นขึ้น แต่ควรใช้ hook
กลไกนี้มีขนาดเล็ก คุณลงทะเบียน command ไว้ใน settings file ภายใต้ชื่อ event เมื่อ event ดังกล่าวเกิดขึ้น Claude Code จะเรียกใช้ command ของคุณ และเขียนข้อมูลของ event ลงใน standard input (stdin) ในรูป JSON (JavaScript object notation) command ของคุณจะอ่านข้อมูลนั้น ดำเนินการ แล้วส่งผลกลับด้วย exit status การคืนค่า Exit 2 จาก hook ของ PreToolUse จะยกเลิก tool call ก่อนที่ tool จะทำงาน และข้อความใดก็ตามที่ script ของคุณเขียนลงใน standard error (stderr) จะถูกส่งกลับไปยัง model ในฐานะเหตุผล เว้นแต่ hook จะพิมพ์ JSON ที่มี blocking decision ซึ่งจะทำให้เหตุผลของ decision นั้นมีลำดับความสำคัญสูงกว่า
ชื่อ event และชื่อ field ในส่วนนี้มาจาก hooks reference ของ Claude Code ซึ่งตรวจสอบเมื่อ November 12, 2026 ข้อมูลส่วนนี้มีการเปลี่ยนแปลงอย่างรวดเร็ว ดังนั้นควรตรวจสอบ reference สำหรับ version ที่คุณใช้งานก่อนคัดลอก JSON จาก blog post ใด ๆ รวมถึงบทความนี้ แสดงค่าของคุณด้วย claude --version
ตำแหน่งที่เก็บการตั้งค่า hook
Hook คือบล็อก JSON ในไฟล์การตั้งค่า โดยสามารถเก็บไว้ได้ใน 6 ตำแหน่ง ซึ่งขอบเขตของไฟล์จะเป็นตัวกำหนดขอบเขตของ hook นั้นๆ
~/.claude/settings.json: ทุกโปรเจกต์บนเครื่องของคุณ และไม่มีผลกับเครื่องอื่น.claude/settings.json: เฉพาะหนึ่งโปรเจกต์ โดยจะถูก commit ลงใน repository เพื่อให้ทุกคนที่ clone โปรเจกต์นี้ได้รับ hook ไปด้วย.claude/settings.local.json: เฉพาะหนึ่งโปรเจกต์ และมีผลเฉพาะบนเครื่องของคุณเท่านั้น- การตั้งค่าผ่านนโยบายที่จัดการโดยระบบ (Managed policy settings): มีผลทั้งองค์กร โดยกำหนดโดยผู้ดูแลระบบ
hooks/hooks.jsonภายในปลั๊กอิน: จะทำงานในขณะที่ปลั๊กอินนั้นเปิดใช้งานอยู่- ส่วนหน้า (frontmatter) ของ Skill หรือ subagent: Hook ของ Skill จะยังคงทำงานต่อไปตลอด session หลังจากที่เรียกใช้ Skill นั้น ส่วน hook ของ subagent จะทำงานในขณะที่ subagent นั้นกำลังรันอยู่
รายการ hook จากไฟล์เหล่านี้จะถูกนำมารวมกันแทนที่จะเขียนทับกัน ไฟล์การตั้งค่าโปรเจกต์จะเพิ่ม hook ของตนเข้าไปรวมกับ hook ในการตั้งค่าของผู้ใช้ แทนที่จะแทนที่รายการเดิม ดังนั้นเหตุการณ์หนึ่งเหตุการณ์จึงสามารถมี hook หลายรายการจากหลายไฟล์ได้ การตั้งค่า "disableAllHooks": true จะเป็นการปิดการทำงานของ hook ทั้งหมด ยกเว้นกรณีเดียวคือ hook ที่มาจากนโยบายที่จัดการโดยระบบจะยังคงทำงานต่อไป เว้นแต่ว่าจะมีการตั้งค่าปิดไว้ในนโยบายที่จัดการโดยระบบด้วยเช่นกัน
รัน /hooks ภายใน session เพื่อแสดงรายการ hook ทั้งหมดที่ลงทะเบียนไว้ในปัจจุบัน โดยจัดกลุ่มตามเหตุการณ์ พร้อมระบุไฟล์ต้นทางและตัวจับคู่ (matcher) ของแต่ละรายการ เมนูนี้เป็นแบบอ่านอย่างเดียว ดังนั้นคุณต้องเปลี่ยน hook โดยการแก้ไขไฟล์การตั้งค่า โดยปกติแล้วตัวเฝ้าติดตามไฟล์ (file watcher) จะตรวจพบการแก้ไขและอัปเดตให้โดยไม่ต้องรีสตาร์ทโปรแกรม
เหตุการณ์ hook ของ Claude Code มีอะไรบ้าง
เอกสารอ้างอิง hook ระบุเหตุการณ์ไว้ทั้งหมด 33 รายการ ตั้งแต่ SessionStart ไปจนถึง SessionEnd ซึ่งครอบคลุมการบีบอัดข้อมูล (compaction), ซับเอเจนต์ (subagents), worktrees และไฟล์กำหนดค่า การทำงานบนเซิร์ฟเวอร์จะใช้เหตุการณ์เหล่านี้เพียงบางส่วนเท่านั้น
PreToolUse: ทำงานก่อนที่ tool call จะเริ่มดำเนินการ ยกเว้นEndConversationนี่คือเหตุการณ์ที่สามารถบล็อกการทำงานได้PostToolUse: ทำงานหลังจาก tool call สำเร็จ ยกเว้นEndConversationส่วนPostToolUseFailureจะทำงานเมื่อเกิดความล้มเหลว ดังนั้น hook ที่ต้องการตรวจสอบทุกผลลัพธ์จำเป็นต้องใช้ทั้งสองเหตุการณ์PermissionRequest: ทำงานเมื่อ tool call ต้องการการตัดสินใจเรื่องสิทธิ์ ซึ่งเป็นจังหวะเดียวกับที่จะแสดงข้อความแจ้งเตือนให้ยืนยันUserPromptSubmit: ทำงานเมื่อคุณส่ง prompt ก่อนที่ Claude จะประมวลผล ข้อความ stdout แบบ plain-text จาก hook ที่สำเร็จจะถูกเพิ่มเข้าไปในบริบทของโมเดลSessionStartและSessionEnd: ทำงานที่จุดเริ่มต้นและจุดสิ้นสุดของเซสชัน ส่วนSessionStartจะทำงานหลังจากการบีบอัดข้อมูลด้วย โดยใช้ค่า matcher เป็นcompactStop: ทำงานเมื่อ Claude ตอบกลับเสร็จสิ้น ซึ่งจะเกิดขึ้นหนึ่งครั้งต่อรอบการสนทนา ไม่ใช่หนึ่งครั้งต่อภารกิจที่เสร็จสมบูรณ์
ในเหตุการณ์ที่รองรับ matcher กลุ่มของ hook สามารถระบุ matcher เพื่อตัดสินใจว่าจะให้ hook ทำงานในกรณีใดบ้าง สำหรับเหตุการณ์ที่เกี่ยวกับ tool ระบบจะกรองด้วยชื่อของ tool เช่น "Edit|Write" จะทำงานเฉพาะกับการแก้ไขไฟล์เท่านั้น ทั้งนี้ matcher จะคำนึงถึงตัวพิมพ์เล็ก-ใหญ่ หากปล่อยว่างไว้ hook จะทำงานในทุกกรณี สำหรับ tool ที่มาจากเซิร์ฟเวอร์ MCP (model context protocol) จะถูกตั้งชื่อเป็น mcp__<server>__<tool> ดังนั้นการใช้ matcher เป็น "mcp__github__.*" จะดักจับเฉพาะ tool ของเซิร์ฟเวอร์นั้นและไม่ยุ่งกับ tool อื่น
hook แบบ Stop มีกับดักที่ควรทราบก่อนเริ่มเขียน หาก hook แบบ Stop ทำการบล็อก ระบบจะส่งโมเดลกลับไปทำงานต่อ โดยปกติแล้ว Claude Code จะข้ามบล็อกถัดไปหลังจากมีการสั่งให้ทำงานต่อเนื่องครบ 8 ครั้ง โดยตัวนับจะถูกรีเซ็ตทุกครั้งที่ Claude เรียกใช้ tool ให้คุณอ่านฟิลด์ stop_hook_active จากข้อมูลขาเข้าของ hook และสั่ง exit 0 เมื่อเป็นจริง มิฉะนั้น hook ของคุณอาจส่ง Claude กลับไปทำงานซ้ำไม่สิ้นสุด
สิ่งที่ hook ได้รับผ่าน stdin
เมื่อ Claude กำลังจะรัน npm test ตัว hook PreToolUse บน Bash จะอ่านข้อมูลต่อไปนี้ผ่าน stdin:
{
"session_id": "abc123",
"cwd": "/home/deploy/myproject",
"hook_event_name": "PreToolUse",
"tool_name": "Bash",
"tool_input": {
"command": "npm test"
}
}ฟิลด์ข้อมูลทั่วไปประกอบด้วย session_id, cwd, transcript_path และ hook_event_name ส่วน permission_mode จะไม่ได้ถูกส่งมาในทุกเหตุการณ์ สำหรับเหตุการณ์ของเครื่องมือ (tool events) จะมีการเพิ่ม tool_name, tool_input และ tool_use_id เข้ามา เหตุการณ์อื่นๆ จะมีฟิลด์เฉพาะของตนเอง โดย UserPromptSubmit จะได้รับข้อความ prompt และ SessionStart จะได้รับ source ของ startup, resume, clear, compact หรือ fork
jq เป็นวิธีปกติที่ใช้ในการอ่านข้อมูลนี้ภายใน shell script ซึ่ง image ของเซิร์ฟเวอร์ขนาดเล็กจะไม่มีเครื่องมือนี้ติดตั้งมาให้ ให้ติดตั้งก่อนด้วยคำสั่ง sudo apt install -y jq บน Ubuntu และ Debian
ผลของ exit status ต่อการเรียกใช้เครื่องมือที่กำลังทำงานอยู่
ผลลัพธ์ที่เกิดขึ้นได้มี 3 รูปแบบดังนี้
- Exit 0 หมายถึงสำเร็จ และฟิลด์การตัดสินใจในรูปแบบ JSON ที่ถูกต้องยังคงมีผล รวมถึงการบล็อกหรือการปฏิเสธ สำหรับ
PreToolUseการ exit 0 โดยไม่มีการตัดสินใจไม่ได้หมายถึงการอนุมัติ และขั้นตอนการตรวจสอบสิทธิ์ตามปกติจะยังคงทำงานต่อไป สำหรับUserPromptSubmit,UserPromptExpansion,SessionStartและPostModelSwitchข้อความแบบ plain-text ใน stdout จะถูกเพิ่มเข้าไปในบริบทของโมเดล สำหรับเหตุการณ์ส่วนใหญ่ที่เหลือ stdout จะถูกส่งไปยัง debug log เท่านั้น - Exit 2 จะบล็อกการกระทำในเหตุการณ์ที่สามารถบล็อกได้ ซึ่งรวมถึง
PreToolUseโดย stderr จะกลายเป็นข้อความที่มาพร้อมกับการบล็อก เว้นแต่ว่าผลลัพธ์ JSON จะมีการตัดสินใจบล็อกระบุไว้ ซึ่งเหตุผลใน JSON จะมีความสำคัญสูงสุด ผู้ที่จะได้อ่านข้อความนั้นขึ้นอยู่กับเหตุการณ์ สำหรับPreToolUseและStopโมเดลจะเห็นข้อความนั้นเป็นเหตุผล สำหรับUserPromptSubmitและPreModelSwitchข้อความจะแสดงให้คุณเห็นและไม่ถูกเพิ่มเข้าไปในบริบทของโมเดล สำหรับPostToolUseและPostToolUseFailureซึ่งไม่สามารถบล็อกได้ การบล็อกจะถูกละเว้น แม้ว่า stderr จะยังคงส่งไปถึงโมเดลในฐานะ feedback ก็ตาม สำหรับเหตุการณ์ส่วนใหญ่ที่เหลือซึ่งไม่สามารถบล็อกได้ stderr จะแสดงให้คุณเห็นเท่านั้นหรือถูกละเว้น สำหรับStop,SubagentStop,TaskCompletedและ hookUserPromptSubmitของปลั๊กอิน การ exit 2 โดยที่ stdout ว่างเปล่าและมีข้อผิดพลาดไฟล์ไม่พบใน stderr จะถือว่าเป็นข้อผิดพลาดที่ไม่ใช่การบล็อก - Exit code อื่นๆ ที่มี stdout เป็น plain-text หรือว่างเปล่า โดยปกติจะเป็นข้อผิดพลาดที่ไม่ใช่การบล็อก บันทึกการทำงานจะแสดงประกาศข้อผิดพลาดของ hook พร้อมบรรทัดแรกของ stderr ต่อจากข้อความ
Failed with non-blocking status code:ข้อมูล JSON ที่ถูกต้องยังคงสามารถตัดสินผลลัพธ์ในเหตุการณ์ต่างๆ เช่นPreToolUseได้ เว้นแต่ว่าความล้มเหลวของ hook จะทำให้การกระทำนั้นถูกบล็อกWorktreeCreateจะล้มเหลวเมื่อพบ exit code ที่ไม่ใช่ศูนย์ และWorktreeRemoveจะล้มเหลวเมื่อพบ exit code ที่ไม่ใช่ศูนย์หากไดเรกทอรียังคงมีอยู่หลังจากนั้น
สำหรับการดำเนินการใดๆ นอกเหนือจากการบล็อกหรือการนิ่งเฉย ให้ใช้ exit 0 และพิมพ์ออบเจกต์ JSON ออกทาง stdout แทน hook PreToolUse จะตัดสินใจด้วย permissionDecision:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Database drops go through a migration, not through the agent."
}
}"allow" จะข้ามการโต้ตอบผ่าน prompt ในกรณีที่กฎการอนุญาตและข้อกำหนดการอนุมัติของเครื่องมือเอื้ออำนวย "deny" จะยกเลิกการเรียกใช้และส่งเหตุผลไปยังโมเดล และ "ask" จะร้องขอการยืนยัน ให้เลือกรูปแบบการทำงานเพียงหนึ่งอย่างต่อหนึ่ง hook การใช้ exit 2 ร่วมกับการตัดสินใจผ่าน JSON ใน stdout จะยังคงผลการบล็อกไว้ แม้ว่า JSON จะระบุเป็น "allow" ก็ตาม
เมื่อมีหลาย hook ตรงกับเหตุการณ์เดียวกัน พวกมันจะทำงานแบบขนาน โดยที่ prompt hook และ agent hook จะถูกจำกัดให้ทำงานพร้อมกันได้สูงสุด 12 รายการ deny จาก hook หนึ่งจะไม่หยุดการทำงานของ hook อื่นๆ ดังนั้น logging hook จะยังคงเขียนบรรทัดของมันในขณะที่ guardrail hook ปฏิเสธการเรียกใช้เดียวกัน สำหรับ PreToolUse ตัว Claude Code จะรวมคำตอบเข้าด้วยกันและเลือกผลลัพธ์ที่เข้มงวดที่สุด โดยเรียงลำดับจาก ปฏิเสธ (deny), เลื่อนการตัดสินใจ (defer), ถาม (ask), และ อนุญาต (allow)
ตัวอย่างที่ 1: การบล็อกคำสั่งที่เป็นอันตรายก่อนเริ่มทำงาน
บันทึกไฟล์นี้เป็น .claude/hooks/block-destructive.sh ในโปรเจกต์ของคุณ:
#!/bin/bash
# Deny a Bash tool call whose command matches a banned pattern.
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
for pattern in 'rm -rf /' 'mkfs' 'dd if=' 'DROP TABLE'; do
if printf '%s' "$COMMAND" | grep -qiF -- "$pattern"; then
echo "Blocked by policy: the command matches '$pattern'. A human runs this one." >&2
exit 2
fi
done
exit 0กำหนดให้ไฟล์รันได้ จากนั้นลงทะเบียนใน PreToolUse ภายใน .claude/settings.json:
chmod +x .claude/hooks/block-destructive.sh{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.sh",
"timeout": 10,
"statusMessage": "Checking the command against policy"
}
]
}
]
}
}ทดสอบสคริปต์ด้วยตนเองก่อนใช้งานจริง เพราะ hook ที่ทำงานผิดพลาดเมื่อได้รับ input จะปล่อยให้คำสั่งผ่านไปได้หากไม่ได้ตั้งค่า onFailure ไว้ สำหรับ Windows ที่ไม่มี Git Bash การใช้ shell-form ของ hook ในคำสั่ง PreToolUse หรือ PermissionRequest ที่ทำงานผิดพลาดอาจส่งผลให้การเรียกใช้เครื่องมือถูกบล็อกแทน:
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /var/lib/postgresql"}}' \
| .claude/hooks/block-destructive.sh
echo $?คุณควรเห็นบรรทัด Blocked by policy: บน stderr และ exit code เป็น 2 ลองทดสอบด้วยคำสั่งที่ไม่เป็นอันตราย เช่น ls -la ซึ่งคุณไม่ควรเห็นผลลัพธ์ใดๆ และควรได้ exit code เป็น 0 ในระหว่างเซสชัน การเรียกใช้ที่ถูกปฏิเสธจะปรากฏใน transcript พร้อมข้อความเหตุผลที่คุณระบุไว้ ซึ่งโมเดลจะอ่านข้อความนั้นและปรับเปลี่ยนพฤติกรรม
คุณสมบัติประการหนึ่งที่ทำให้การทำเช่นนี้คุ้มค่าคือ hook PreToolUse จะทำงานก่อนการตรวจสอบ permission-mode และทำงานในทุกโหมด ดังนั้นการปฏิเสธคำสั่งจึงยังคงมีผลแม้จะอยู่ภายใต้ bypassPermissions นี่คือสิ่งที่ทำให้ hook มีประโยชน์เมื่อใช้งานร่วมกับ โหมดอัตโนมัติของ Claude Code และการตั้งค่าสิทธิ์ ซึ่งแม้จะมีการลดระดับการแจ้งเตือนลง แต่ hook ก็ยังคงทำงานอยู่
โปรดเข้าใจข้อจำกัดของวิธีนี้ การใช้ pattern matching กับสตริงคำสั่งเป็นเพียงมาตรการป้องกันความประมาทของเอเจนต์เท่านั้น ไม่ใช่การป้องกันเอเจนต์ที่พยายามหลบเลี่ยง เนื่องจากคำสั่งเดียวกันสามารถเขียนในรูปแบบที่ grep ของคุณตรวจไม่พบ กฎที่เข้มงวดควรอยู่ในระบบจัดการสิทธิ์และในบัญชีผู้ใช้ที่กระบวนการนั้นทำงานอยู่เท่านั้น
ตัวอย่างที่ 2: การจัดรูปแบบและตรวจสอบ lint หลังการแก้ไขทุกครั้ง
PostToolUse ที่ใช้ตัวจับคู่ Edit|Write จะทำงานหลังจากเครื่องมือแก้ไขไฟล์ตัวใดตัวหนึ่งทำงานสำเร็จ ให้บันทึกไฟล์นี้เป็น .claude/hooks/after-edit.sh:
#!/bin/bash
# Format the edited file, then report lint failures back to the model.
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
[ -z "$FILE" ] && exit 0
case "$FILE" in
*.py)
ruff format "$FILE" >/dev/null 2>&1
if ! ruff check "$FILE" >&2; then
exit 2
fi
;;
*.sh)
if ! shellcheck "$FILE" >&2; then
exit 2
fi
;;
esac
exit 0{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/after-edit.sh",
"timeout": 60
}
]
}
]
}
}ลองให้ Claude เพิ่มฟังก์ชันที่มีการย่อหน้าผิดพลาดลงในไฟล์ Python จากนั้นเปิดไฟล์นั้นขึ้นมา คุณจะพบว่าไฟล์ถูกจัดรูปแบบใหม่แล้ว นั่นคือการตรวจสอบว่า hook ทำงานจริง เพราะหาก hook ทำงานสำเร็จ จะไม่มีข้อความใดปรากฏในบทสนทนา
การใช้ exit 2 ในที่นี้ไม่ได้เป็นการย้อนกลับการเปลี่ยนแปลงใดๆ เนื่องจาก PostToolUse จะทำงานหลังจากที่เครื่องมือทำงานเสร็จสิ้นไปแล้ว ดังนั้นการแก้ไขจึงถูกบันทึกลงในดิสก์ไม่ว่ากรณีใดก็ตาม สิ่งที่ exit 2 มอบให้คุณคือการทำให้ผลลัพธ์ของ ruff check ส่งกลับไปยังโมเดลในฐานะข้อมูลป้อนกลับ เพื่อให้โมเดลแก้ไขข้อผิดพลาดที่เพิ่งเกิดขึ้นแทนที่จะดำเนินการต่อไป นี่คือความแตกต่างระหว่างความล้มเหลวของ lint ที่คุณพบในขั้นตอน commit กับความล้มเหลวที่ agent ซ่อมแซมได้ในรอบการทำงานเดียวกัน
มีข้อจำกัดของตัวจับคู่สองประการที่สำคัญในที่นี้ Edit|Write จะไม่ตรวจพบไฟล์ที่ถูกเปลี่ยนแปลงโดยคำสั่ง shell และ Claude มักจะเขียนไฟล์ผ่าน Bash บ่อยครั้งจนช่องว่างนี้เป็นปัญหาจริง สำหรับการครอบคลุมในระดับต่อการเรียกใช้งาน ให้จับคู่ Bash เพิ่มเติมและใช้สคริปต์แสดงรายการไฟล์ที่เปลี่ยนแปลงด้วย git status --porcelain สำหรับการครอบคลุมในระดับต่อรอบการทำงาน ให้ใส่การสแกนไว้ใน hook Stop แทน
ตัวอย่างที่ 3: บันทึกทุกการเรียกใช้เครื่องมือเพื่อการตรวจสอบ
ตัวจับคู่ (matcher) ที่ว่างเปล่าใน PostToolUse จะทำงานเมื่อมีการเรียกใช้เครื่องมือสำเร็จทุกครั้ง ยกเว้น EndConversation การส่งบันทึกไปยัง system journal แทนที่จะเก็บไว้ในไฟล์ใน home directory ไม่ได้ช่วยป้องกันไม่ให้ agent เข้าถึงข้อมูลดังกล่าวได้ เนื่องจากสิทธิ์การเข้าถึงขึ้นอยู่กับสิทธิ์ของบัญชีผู้ใช้นั้นๆ ผู้ใช้สามารถอ่าน journal ส่วนตัวของตนเองได้ ส่วน root และสมาชิกของ systemd-journal, adm หรือ wheel สามารถอ่านไฟล์ journal ทั้งหมดได้:
{
"hooks": {
"PostToolUse": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "jq -c '{time: now|todate, session: .session_id, cwd: .cwd, tool: .tool_name, input: .tool_input}' | logger -t claude-code -p local0.info"
}
]
}
]
}
}อ่านข้อมูลกลับมาด้วย journalctl -t claude-code -o cat | tail -n 5 หากคุณมีสิทธิ์อ่านบันทึก คุณควรจะเห็นข้อมูล JSON หนึ่งบรรทัดต่อการเรียกใช้เครื่องมือที่สำเร็จหนึ่งครั้ง (ยกเว้น EndConversation) โดยเรียงลำดับจากรายการล่าสุด หากไม่มีข้อมูลปรากฏขึ้น ให้ตรวจสอบสิทธิ์การเข้าถึง journal และตรวจสอบว่า hook ทำงานหรือไม่ ส่วนการแก้ไขปัญหาด้านล่างนี้จะครอบคลุมเรื่องการทำงานของ hook
ให้เพิ่มบล็อกเดียวกันภายใต้ PostToolUseFailure เพื่อบันทึกการเรียกใช้ที่ล้มเหลว เนื่องจาก PostToolUse จะทำงานเฉพาะเมื่อการเรียกใช้สำเร็จเท่านั้น แต่คำสั่งที่ล้มเหลวมักเป็นสิ่งที่น่าสนใจกว่า เหตุผลที่ใช้ logger แทนการเพิ่มข้อมูลลงในไฟล์ใน home directory คือเรื่องความเป็นเจ้าของ (ownership) เนื่องจาก hook ทำงานในฐานะผู้ใช้เดียวกับ shell ของ agent ดังนั้นผู้ใช้คนใดที่สามารถเพิ่มข้อมูลลงในไฟล์ได้ ก็สามารถลบข้อมูลในไฟล์นั้นได้เช่นกัน ในขณะที่ journal ถูกเขียนโดย systemd-journald การป้องกันไม่ให้ถูกลบยังคงขึ้นอยู่กับสิทธิ์ของบัญชีผู้ใช้ที่รัน agent อยู่ดี
ระยะเวลาที่ hook สามารถทำงานได้
ข้อมูลเบื้องหลังแผนภูมินี้
[
{
"label": "command, http or mcp_tool hook",
"default_timeout_seconds": 600
},
{
"label": "agent hook",
"default_timeout_seconds": 60
},
{
"label": "prompt hook",
"default_timeout_seconds": 30
},
{
"label": "command, http or mcp_tool on UserPromptSubmit, PreModelSwitch or PostModelSwitch",
"default_timeout_seconds": 30
},
{
"label": "command, http or mcp_tool on MessageDisplay",
"default_timeout_seconds": 10
},
{
"label": "any hook on SessionEnd",
"default_timeout_seconds": 1.5
}
]โดยปกติแล้ว command hook จะได้รับเวลาทำงานเริ่มต้นที่ 600 วินาที หรือเท่ากับ 10 นาที อย่างไรก็ตาม บางเหตุการณ์จะจำกัดเวลาลงอย่างมาก โดย hook ประเภท SessionEnd จะต้องใช้เวลาทำงานรวมกันทั้งหมดไม่เกิน 1.5 วินาที ดังนั้นการล้างข้อมูลเมื่อจบเซสชันจึงต้องทำอย่างรวดเร็ว แม้ว่าการตั้งค่า timeout ให้ยาวขึ้นในไฟล์ตั้งค่าของคุณจะช่วยขยายงบประมาณเวลารวมดังกล่าวได้สูงสุดถึง 60 วินาทีก็ตาม
หาก command, HTTP หรือ MCP tool hook แบบ synchronous ทำงานเกินเวลาที่กำหนด ระบบจะยกเลิกการทำงานและโดยปกติจะไม่ส่งผลต่อการตัดสินใจใดๆ แต่สำหรับ PreModelSwitch การหมดเวลาจะส่งผลให้การสลับถูกบล็อก สำหรับ guardrail ประเภท PreToolUse โดยปกติแล้วการหมดเวลาจะปล่อยให้การเรียกใช้เครื่องมือดำเนินต่อไปตามขั้นตอนการอนุญาตตามปกติ ยกเว้นในกรณีของ Windows ที่กล่าวถึงข้างต้นเมื่อไม่ได้ตั้งค่า onFailure ด้วยเหตุนี้จึงควรเขียนสคริปต์ guardrail ให้มีขนาดเล็ก ตั้งแต่รุ่น 2.1.295 เป็นต้นไป คุณสามารถเปลี่ยนค่าเริ่มต้นดังกล่าวสำหรับ hook ประเภท command หรือ http ได้ด้วย "onFailure": "block" ซึ่งจะทำให้การหมดเวลา การขัดข้อง หรือการได้รับ exit code ที่ไม่คาดคิดกลายเป็นการบล็อกการทำงาน อย่างไรก็ตาม การตั้งค่านี้จะไม่มีผลกับ Stop, SubagentStop, TaskCompleted, TeammateIdle หรือ command hook ที่ทำงานในเบื้องหลัง สำหรับงานที่ใช้เวลานานและไม่มีใครรอผลลัพธ์ เช่น การส่ง log ไปยังปลายทาง ให้ตั้งค่า "async": true เพื่อให้ hook ทำงานในเบื้องหลังโดยไม่ขัดจังหวะการเรียกใช้เครื่องมือ
Hooks, rules files, skills และ MCP servers
มีสี่สิ่งที่มักสับสนกันเพราะทั้งหมดล้วนเปลี่ยนพฤติกรรมของ agent แต่มีเพียงสิ่งเดียวเท่านั้นที่ไม่ใช่แค่คำแนะนำ
Rules file (CLAUDE.md หรือไฟล์ภายใต้ .claude/rules/) คือข้อความที่ถูกโหลดเข้าสู่บริบทของโมเดล มันช่วยกำหนดพฤติกรรมแต่ไม่ได้บังคับให้เกิดผลใดๆ เมื่อเทียบกับบทสนทนาที่ยาวเหยียด, diff ขนาดใหญ่ และคำขอใหม่จากผู้ใช้ ข้อความเพียงบรรทัดเดียวในไฟล์อาจถูกละเลยได้ นี่คือกลไกปกติที่อยู่เบื้องหลัง การที่ agent เพิกเฉยต่อคำสั่งที่คุณเขียนไว้
Skill คือโฟลเดอร์ที่เก็บคำสั่งและสคริปต์ซึ่งโมเดลจะโหลดขึ้นมาเมื่อพิจารณาว่า skill นั้นเกี่ยวข้อง การตัดสินใจดังกล่าวคือหัวใจสำคัญของ skill และในขณะเดียวกันก็เป็นข้อจำกัด เพราะโมเดลยังคงเป็นผู้ตัดสินใจเอง คุณสามารถเห็นทั้งสองด้านได้ใน skill อย่าง Ponytail ซึ่งผลักดันให้ agent เลือกการเปลี่ยนแปลงที่เล็กที่สุดที่ใช้งานได้ เพราะมันช่วยกำหนดแนวทางในการจัดการงานทั้งหมดในแบบที่ hook ทำไม่ได้ และจะทำงานก็ต่อเมื่อโมเดลเลือกที่จะโหลดมันเท่านั้น
MCP (model context protocol) server มอบเครื่องมือใหม่ให้โมเดลเรียกใช้ มันช่วยขยายขอบเขตสิ่งที่ agent สามารถเข้าถึงได้ แต่มันไม่ได้บังคับให้ agent ต้องเรียกใช้สิ่งใด และมันเป็นกระบวนการแยกต่างหากที่คุณต้องดูแล ซึ่งเป็นงานเฉพาะทาง: ดูที่ การรัน MCP servers บน VPS
Hook เป็นสิ่งเดียวในสี่อย่างนี้ที่ทำงานโดยที่โมเดลไม่ต้องเป็นผู้เลือก ให้ใช้ rules file สำหรับความต้องการทั่วไป และใช้ skill สำหรับขั้นตอนที่โมเดลควรปฏิบัติตามเมื่อถึงเวลาที่เหมาะสม ส่วน hook ให้ใช้สำหรับขั้นตอนที่ต้องเกิดขึ้นทุกครั้ง หรือสิ่งที่ต้องไม่เกิดขึ้นเด็ดขาด การเปรียบเทียบเชิงลึก รวมถึงกรณีที่ skill มีประสิทธิภาพเหนือกว่า rules file อยู่ใน การเปรียบเทียบระหว่าง skills, MCP และ rules files
Plugin เป็นเพียงรูปแบบการบรรจุภัณฑ์ไม่ใช่กลไกที่ห้า มันทำหน้าที่รวม hook เข้ากับ skill ให้เป็นหน่วยเดียวที่ติดตั้งได้ ซึ่งเป็นวิธีที่ทีมงานใช้ในการส่งมอบ guardrail เดียวกันไปยังทุกเครื่อง: ดูที่ วิธีการทำงานของ Claude Code plugins
การตัดสินใจด้านความปลอดภัยบน VPS ที่ใช้งานร่วมกัน
Hook คือ code ที่ agent เรียกใช้ และจะทำงานด้วยสิทธิ์ของ user ที่เริ่ม Claude Code Hook จะสืบทอด file permissions และ environment ของ user คนนั้น บน laptop นี่เป็นเพียงประเด็นด้าน workflow แต่บน VPS ที่มี agent ทำงานโดยไม่ต้องมีผู้ดูแล นี่เป็นประเด็นด้านความปลอดภัยที่มี 4 ส่วนในทางปฏิบัติ
Hook ใน repository คือ code ที่คุณไม่ได้เขียนเอง .claude/settings.json ถูก commit ไว้ ดังนั้นการ clone repository และเริ่ม session ภายใน repository อาจลงทะเบียน hook ที่มาพร้อมกับ repository ได้ ใน interactive session, Claude Code จะให้ project hook ทำงานได้ก็ต่อเมื่อผ่าน workspace trust dialog สำหรับ folder นั้น ซึ่งหมายความว่าการยอมรับ trust คือช่วงเวลาที่คุณตัดสินใจให้ hook ทำงาน อ่าน block hooks ก่อน claude -p หรือ SDK session ซึ่งเป็นวิธีที่ agent แบบ unattended มักใช้ จะไม่แสดง dialog ดังกล่าว และจะถือว่า folder นั้น trusted ดังนั้น hook ของ repository จะทำงานโดยไม่ถาม ตรวจสอบ file .claude/ ก่อนเขียน script เพื่อใช้งานกับ repository หรือเรียกใช้ด้วย --settings '{"disableAllHooks": true}'
Hook มองเห็น tool input ทั้งหมด Audit hook ที่บันทึก tool_input จะเขียน argument ของ command ทุกคำสั่งลงใน log รวมถึง token ใด ๆ ที่บังเอิญอยู่บน command line จากนั้น log ดังกล่าวต้องได้รับการป้องกันในระดับเดียวกับ secret ซึ่งเป็นส่วนหนึ่งของปัญหาที่กว้างกว่าคือ การเก็บ secret ให้พ้นจากการเข้าถึงของ AI agent
Hook สามารถเขียนข้อมูลลงใน context ของ model ได้ stdout แบบ plain text จาก hook SessionStart หรือ UserPromptSubmit ที่ทำงานสำเร็จจะถูกเพิ่มลงใน conversation Hook ที่ส่งต่อข้อความจากภายนอก issue tracker หรือ log file เข้ามา กำลังส่งข้อความที่ไม่น่าเชื่อถือให้ model ราวกับว่าคุณเป็นผู้พิมพ์ข้อความนั้นเอง Hook ที่ส่งต่อข้อความจาก Claude Code session อื่นบน VPS เดียวกัน ก็ทำเช่นเดียวกัน และ output ของ agent หนึ่งไม่ได้มีสิทธิ์ได้รับความไว้วางใจมากกว่า issue tracker ให้ถือว่า stdout นี้เป็น input ไม่ใช่ output
สิทธิ์คือกลไกควบคุมที่แท้จริง ให้ agent ทำงานด้วย dedicated unprivileged user ซึ่งมีเฉพาะกฎ sudo ที่จำเป็นต้องใช้ PreToolUse deny มีประโยชน์ และการทำงานของมันเป็นแบบ best effort ตามการออกแบบ: reference ระบุเช่นเดียวกันเกี่ยวกับ filter if และแนะนำให้ใช้ permission system เมื่อต้องการ hard deny สิ่งที่ยังคงมีผลเมื่ออยู่ภายใต้แรงกดดันคือ permission rules และ account ที่ process ใช้งานอยู่
มีคุณสมบัติหนึ่งที่เป็นจริงในทุก permission mode PreToolUse hook จะทำงานก่อนการตรวจสอบ permission-mode ในทุก permission mode ดังนั้น hook ที่คืนค่า deny จะ block tool แม้ใช้ bypassPermissions Hook สามารถเพิ่มความเข้มงวดให้สิ่งที่ permission rules อนุญาตได้ แต่ไม่สามารถผ่อนคลายกฎดังกล่าวได้ ข้อยกเว้นคือ mod บนเครื่องที่ไม่มี managed settings และไม่มี file managed-mcp.json ใน session ที่ไม่ได้ sign in ผ่าน /login ไปยัง Team หรือ Enterprise plan, mod ที่ติดตั้งและจัดการ tool.check สามารถ approve call ที่ hook PreToolUse ของคุณ block ไว้ได้ หากมี managed settings, file managed-mcp.json หรือมี Team หรือ Enterprise /login เป็น credential ของ session, call ที่ hook PreToolUse block ไว้จะยังคงถูก block โดยค่าเริ่มต้น ไม่ว่า hook จะมาจาก settings file ใดก็ตาม session ที่ทำงานด้วย API key หรือ CLAUDE_CODE_OAUTH_TOKEN แบบ long-lived ซึ่งเป็นวิธีที่ server จำนวนมากใช้ จะถือว่ายังไม่ได้ sign in แม้จะมีการเก็บ login ไว้ก็ตาม ตรวจสอบว่า Claude Code mods สามารถเปลี่ยนแปลงอะไรได้บ้าง ก่อนติดตั้ง mod บน server
เหตุใด hook ของฉันจึงไม่ทำงาน
ให้ดำเนินการตามลำดับดังนี้ แต่ละขั้นตอนจะระบุถึงอาการที่คุณจะพบจริง
- รัน
/hooksแล้วตรวจสอบว่า hook ปรากฏอยู่ภายใต้เหตุการณ์ที่คุณคาดหวังหรือไม่ หาก hook หายไปจากเมนู มักหมายความว่าไฟล์การตั้งค่ามีข้อผิดพลาดทางไวยากรณ์ JSON เนื่องจากไม่อนุญาตให้มีเครื่องหมายจุลภาคปิดท้าย (trailing comma) หรือความคิดเห็น (comment) หรือไฟล์ไม่ได้อยู่ในหนึ่งในหกตำแหน่งที่ระบุไว้ข้างต้น - เปรียบเทียบตัวจับคู่ (matcher) กับชื่อเครื่องมือให้ตรงกันทุกประการ ตัวจับคู่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ ดังนั้น
"bash"จะไม่ตรงกับเครื่องมือBash - รันสคริปต์ด้วยตนเองโดยใช้ข้อมูลตัวอย่างตามตัวอย่างที่ 1 ด้านบน หากได้รับ exit code ที่ไม่คาดคิด แสดงว่าเป็นบั๊กในสคริปต์ของคุณ ให้ตรวจสอบ stdout ของสคริปต์ด้วย เนื่องจาก JSON ที่ถูกต้องยังคงสามารถส่งผลการตัดสินใจในเหตุการณ์ต่างๆ เช่น
PreToolUseได้ - การแจ้งเตือนที่ระบุว่า
jq: command not foundหมายความว่าjqไม่มีอยู่บนเครื่องนั้น หากเกิดcommand not foundสำหรับสคริปต์ของคุณเอง หมายความว่า path ไม่สามารถระบุตำแหน่งได้ ดังนั้นให้ใช้${CLAUDE_PROJECT_DIR}หรือใช้ absolute path หากสคริปต์ไม่ทำงานเลย เป็นไปได้ว่าสคริปต์นั้นไม่ได้ถูกตั้งค่าให้เป็น executable - hook พิมพ์ JSON ที่ถูกต้องแต่ไม่มีอะไรเกิดขึ้น บน macOS และ Linux hook รูปแบบ shell จะรันผ่าน
sh -cใน non-interactive shell แต่การตั้งค่าบางอย่างอาจยังคงเรียกใช้ profile ของคุณ เช่นBASH_ENVที่ชี้ไปยัง~/.bashrcหาก profile นั้นพิมพ์ข้อความ banner ออกมา ข้อความดังกล่าวจะถูกแทรกไว้หน้า JSON ของคุณ ทำให้ stdout ไม่ได้เริ่มต้นด้วย{อีกต่อไป ส่งผลให้ Claude Code อ่านข้อมูลทั้งหมดเป็นข้อความธรรมดาและเพิกเฉยต่อการตัดสินใจนั้น เนื่องจาก hook จบการทำงานด้วยสถานะ 0 บันทึกการสนทนาจึงไม่แสดงข้อผิดพลาด ในเหตุการณ์ส่วนใหญ่ ข้อความนั้นจะถูกส่งไปยัง debug log เท่านั้น ในขณะที่เหตุการณ์UserPromptSubmit,UserPromptExpansion,SessionStartและPostModelSwitchข้อความดังกล่าวจะถูกเพิ่มเข้าไปในบริบทของโมเดลรวมถึง banner ด้วย ให้ครอบechoใดๆ ใน profile ของคุณเพื่อให้ทำงานเฉพาะใน interactive shell เท่านั้น - หากยังติดปัญหา: ให้เริ่มเซสชันด้วย
claude --debug-file /tmp/claude.logและรันtail -f /tmp/claude.logในเทอร์มินัลที่สอง บันทึก debug log จะบันทึกว่า hook ใดบ้างที่ตรงกัน, แต่ละ hook ส่งคืน exit code ใด, และทุกสิ่งที่เขียนไปยัง stdout และ stderr
FAQ
ความแตกต่างระหว่าง hook ของ Claude Code กับคำสั่งใน CLAUDE.md คืออะไร?
คำสั่งใน CLAUDE.md เป็นข้อความที่อยู่ในบริบทของโมเดล จึงต้องแบ่งความสนใจไปพร้อมกับบทสนทนาและคำขอปัจจุบัน ซึ่งโมเดลสามารถนำไปพิจารณาเปรียบเทียบกันได้ ส่วน hook คือคำสั่ง shell ที่ Claude Code จะเรียกทำงาน ณ จุดที่กำหนดไว้ในวงจรการทำงานของมัน ดังนั้นมันจะทำงานทุกครั้งที่เกิดเหตุการณ์นั้นโดยไม่ขึ้นอยู่กับการตัดสินใจของโมเดล ให้ใช้คำสั่งใน CLAUDE.md สำหรับการตั้งค่าความชอบส่วนตัว และใช้ hook สำหรับขั้นตอนที่ต้องเกิดขึ้นเสมอหรือการกระทำที่ต้องห้ามเกิดขึ้นเด็ดขาด
ฉันจะหยุดไม่ให้ Claude Code เรียกใช้คำสั่ง shell บางอย่างได้อย่างไร?
ให้ลงทะเบียน hook ประเภท PreToolUse พร้อมกับตัวจับคู่ Bash ที่อ่านคำสั่งจาก .tool_input.command จากนั้นเขียนเหตุผลลงใน stderr แล้ว exit 2 ออกมา Claude Code จะยกเลิกการเรียกนั้นและแสดงเหตุผลของคุณให้โมเดลเห็น ซึ่งกระบวนการนี้เกิดขึ้นก่อนการตรวจสอบในโหมด permission-mode ดังนั้นการปฏิเสธจะมีผลแม้ในโหมด bypassPermissions การจับคู่รูปแบบ (pattern matching) บนสตริงคำสั่งเป็นเพียงมาตรการป้องกันเบื้องต้น ไม่ใช่ขอบเขตความปลอดภัยที่สมบูรณ์ เพราะคำสั่งเดียวกันสามารถเขียนในรูปแบบที่ตัวจับคู่มองไม่เห็นได้ ดังนั้นควรเสริมด้วยกฎการอนุญาต (permission rules) และการใช้งานผ่านบัญชีผู้ใช้ที่ไม่มีสิทธิ์ระดับสูง
hook ของฉันพิมพ์ JSON ที่ถูกต้องแล้ว แต่ไม่มีอะไรเกิดขึ้น เพราะเหตุใด?
ให้ตรวจสอบไฟล์ profile ของ shell ว่ามีการพิมพ์ข้อความออกมาก่อนหน้า JSON หรือไม่ บน macOS และ Linux นั้น hook ที่ไม่มีฟิลด์ args จะทำงานผ่าน sh -c และในสภาพแวดล้อมที่ยังคงโหลดไฟล์ profile ของคุณ เช่น BASH_ENV ที่ชี้ไปยัง ~/.bashrc หาก profile มีการพิมพ์ข้อความต้อนรับ (banner) ข้อความนั้นจะถูกส่งออกไปยัง stdout ก่อนหน้า JSON ของคุณ เนื่องจากผลลัพธ์ไม่ได้ขึ้นต้นด้วย { อีกต่อไป Claude Code จึงมองว่าทั้งหมดเป็นข้อความธรรมดาและเพิกเฉยต่อการตัดสินใจนั้น และเนื่องจาก hook จบการทำงานด้วย exit 0 ในบันทึกการทำงานจึงไม่แสดงข้อผิดพลาด ให้ป้องกันการพิมพ์ echo ใน profile ของคุณด้วยการตรวจสอบว่าเป็น interactive shell หรือไม่ จากนั้นยืนยันการแก้ไขโดยการอ่าน debug log จาก claude --debug-file /tmp/claude.log
การรัน hook ของ Claude Code บนเซิร์ฟเวอร์ที่ใช้งานร่วมกันมีความปลอดภัยหรือไม่?
hook จะทำงานในฐานะผู้ใช้ที่เริ่ม Claude Code โดยใช้สิทธิ์ไฟล์ของผู้ใช้นั้น ดังนั้น hook สามารถทำทุกอย่างที่บัญชีนั้นทำได้ นิสัยสองประการที่ช่วยลดความเสี่ยงส่วนใหญ่คือ: รัน agent ด้วยบัญชีผู้ใช้เฉพาะที่ไม่มีสิทธิ์ระดับสูงและมีนโยบาย sudo ที่จำกัด และอ่านบล็อก hooks ของ repository ใดๆ ก่อนที่คุณจะยอมรับกล่องโต้ตอบความเชื่อมั่นใน workspace หรือรัน claude -p ในนั้น เพราะ project hook จะมาพร้อมกับ .claude/settings.json และโหมด -p จะไม่แสดงกล่องโต้ตอบดังกล่าว ให้ตั้งค่า "disableAllHooks": true ในไฟล์ตั้งค่าของคุณเพื่อปิดการใช้งาน hook ยกเว้น hook ที่มีการจัดการซึ่งต้องการการตั้งค่าในระดับที่จัดการไว้ โดยการตั้งค่าระดับโปรเจกต์เป็น false สามารถเขียนทับการตั้งค่าของผู้ใช้ที่เป็น true ได้