บทที่ 13 — Hooks

บทที่ 13 · English

Hooks คือคำสั่งเชลล์ที่ทำงานเมื่อเกิดเหตุการณ์ในวงจรชีวิตของ agent ซึ่งเป็น ช่องทางให้คุณเชื่อม thClaws เข้ากับเครื่องมือที่มีอยู่ เช่น บันทึกทุกการเรียก tool ส่งการแจ้งเตือนเมื่อ session จบ หรือบล็อกการ commit จนกว่า test จะผ่าน

เหตุการณ์ (Events)

Event	เกิดขึ้นเมื่อ	Env vars ที่เปิดให้ใช้
`pre_tool_use`	ก่อนที่ tool จะทำงาน	`THCLAWS_TOOL_NAME`, `THCLAWS_TOOL_INPUT`
`post_tool_use`	หลังจาก tool คืนค่าสำเร็จ	`THCLAWS_TOOL_NAME`, `THCLAWS_TOOL_OUTPUT`
`post_tool_use_failure`	หลังจาก tool เกิดข้อผิดพลาด	`THCLAWS_TOOL_NAME`, `THCLAWS_TOOL_ERROR`
`permission_denied`	ผู้ใช้พิมพ์ `n` ที่ prompt ขออนุญาตใช้ tool	`THCLAWS_TOOL_NAME`
`session_start`	เมื่อ session เริ่มต้น	`THCLAWS_SESSION_ID`, `THCLAWS_MODEL`
`session_end`	เมื่อ `/quit` หรือปิดหน้าต่าง	`THCLAWS_SESSION_ID`, `THCLAWS_MODEL`
`pre_compact`	ก่อนการบีบอัดประวัติ	—
`post_compact`	หลังการบีบอัดเสร็จสิ้น	—

การตั้งค่า hooks

ใน .thclaws/settings.json (ระดับโปรเจกต์) หรือ ~/.config/thclaws/settings.json (ระดับผู้ใช้):

{
  "hooks": {
    "pre_tool_use":  "echo \"tool: $THCLAWS_TOOL_NAME\" >> /tmp/thclaws.log",
    "post_tool_use": "echo \"done: $THCLAWS_TOOL_NAME\" >> /tmp/thclaws.log",
    "session_start": "osascript -e 'display notification \"thClaws started\"'",
    "session_end":   "osascript -e 'display notification \"thClaws ended\"'"
  }
}

แต่ละค่าคือ shell snippet ที่รันผ่าน /bin/sh -c โดยตัวแปรสภาพแวดล้อม จะพร้อมให้ใช้งานตามที่ระบุไว้ในตารางด้านบน

สูตรการใช้งานจริง

บันทึกทุกคำสั่ง bash ลงไฟล์

{
  "hooks": {
    "pre_tool_use": "[ \"$THCLAWS_TOOL_NAME\" = Bash ] && echo \"[$(date)] $THCLAWS_TOOL_INPUT\" >> ~/.thclaws-bash.log"
  }
}

แจ้งเตือนบนเดสก์ท็อปเมื่อ turn เสร็จ

{
  "hooks": {
    "session_end": "notify-send 'thClaws' 'Session done'"
  }
}

สำหรับ macOS: ให้เปลี่ยนเป็น osascript -e 'display notification "Session done" with title "thClaws"'

Auto-commit ทุกครั้งที่ edit สำเร็จ

{
  "hooks": {
    "post_tool_use": "[ \"$THCLAWS_TOOL_NAME\" = Edit -o \"$THCLAWS_TOOL_NAME\" = Write ] && git add -A && git commit -m 'thclaws: edit' --no-verify"
  }
}

(ใช้ --no-verify อย่างระมัดระวัง เพราะจะข้าม pre-commit hooks ไปด้วย)

Ping webhook เมื่อถูกปฏิเสธสิทธิ์

{
  "hooks": {
    "permission_denied": "curl -s -X POST -H 'Content-Type: application/json' -d \"{\\\"tool\\\": \\\"$THCLAWS_TOOL_NAME\\\"}\" https://hooks.example.com/denied"
  }
}

การจัดการความล้มเหลว

Hooks ที่จบด้วย exit status ไม่เป็น 0 จะพิมพ์ warning ไปที่ stderr แต่จะไม่หยุดการทำงานของ agent โดย hook จะรันใน cwd เดียวกับ thClaws ดังนั้น path ของไฟล์ในสคริปต์จะอิงจากรากของ sandbox ส่วน hooks ที่รันนาน จะบล็อก turn จึงควรทำให้เร็วหรือสั่งรันเป็น background (command &)

การดีบัก

thclaws --cli --verbose

โหมด verbose จะพิมพ์รายละเอียดของทุก hook ออกมาก่อนจะสั่งรันจริง

สิ่งที่ hooks ไม่ใช่

Hooks ไม่สามารถเปลี่ยนแปลง การเรียก tool ได้ เพราะทำหน้าที่เป็นเพียง observer เท่านั้น หากต้องการบล็อก tool ให้ใช้รายการ permissions.deny (บทที่ 5) ส่วนการแก้ไข input ของ tool ต้องให้ตัวโมเดลเป็นผู้ทำเอง