Session Hooks: Điều khiển vòng đời session - Khởi tạo, Ép hoàn thành và Ghi log lỗi

Định nghĩa

Session Hooks là ba "cửa khẩu" kiểm soát vòng đời của Claude Code: SessionStart khi mở app để chuẩn bị ngữ cảnh, Stop khi Claude định nghỉ để ép hoàn thành task, và StopFailure khi hệ thống crash để ghi log. Ba hook này biến agent loop từ chế độ "mở" (Claude tự do làm rồi dừng) sang chế độ "đóng" (có kiểm soát chất lượng và khởi tạo nhất quán).

Giải thích chi tiết

SessionStart: Chuẩn bị sân khấu cho Claude

SessionStart chạy mỗi khi session bắt đầu hoặc resume, đóng vai trò như lệnh setup() trong codebase của bạn. Hook nhận thông tin qua stdin gồm session_id, project_path, và transcript_path.

Điểm mạnh nằm ở hai thứ hook có thể trả về: additionalContext (đoạn text được bơm thẳng vào context window như thể là lịch sử trò chuyện) và setEnvironmentVariables (thiết lập biến môi trường cho cả session).

Ví dụ thực chiến: Khi mở project Python tại ~/work/giaohang-tiet-kiem-api, hook tự động detect file CLAUDE.md trong thư mục, đọc rule "Luôn dùng timezone Asia/Ho_Chi_Minh, format tiền VND có dấu chấm phân cách, và tuân thủ PEP 8" rồi inject vào context. Developer không cần gõ tay # Nhớ dùng VND mỗi lần mở Claude.

Stop: Chặn Claude "nghỉ sớm"

Đây là hook quyền lực nhất cho automation. Claude Code có thói quen tuyên bố chiến thắng sớm — nói "đã xong" khi test chưa chạy, còn lỗi compile, hoặc bỏ quên edge cases.

Stop hook kích hoạt ở cuối mỗi response turn, nhận flag stop_hook_active (boolean). Nếu return {"decision": "block", "reason": "Tests chưa pass"}, Claude buộc phải tiếp tục làm việc thay vì kết thúc turn.

Cơ chế chống vòng lặp vô hạn: stop_hook_active sẽ là true nếu Claude đã bị block ở turn trước và đang cố tiếp tục. Hook cần check flag này — nếu đã active thì phải exit 0 để tránh cảnh Claude bị ép làm việc mãi mãi không ngừng nghỉ.

StopFailure: Hộp đen ghi lỗi hệ thống

Khi turn kết thúc do lỗi API (rate limit, timeout, context window exceeded), StopFailure kích hoạt. Lưu ý quan trọng: hook này bị bỏ qua hoàn toàn — không thể can thiệp flow, không xem được exit code. Chỉ dùng để ghi log lỗi hoặc gửi notification qua Telegram/Slack cho DevOps. Nó giống như hộp đen máy bay, ghi lại trạng thái crash để debug sau.

Agent Loop: Từ mở sang đóng

Không có hooks, Claude Code là hệ thống mở: Prompt → Response → (Tool) → Stop → Repeat, nhưng không có cơ chế kiểm tra chất lượng hay khởi tạo nhất quán.

Session Hooks đóng vòng lặp lại (closed-loop) bằng cách thêm:

• Khởi tạo (SessionStart): Đảm bảo mọi session bắt đầu với đúng context và môi trường
• Validation (Stop): Ngăn chặn output kém chất lượng trước khi kết thúc
• Quan sát (StopFailure): Ghi nhận lỗi hệ thống để cải thiện

Ví dụ thực tế

Tự động nạp "tribal knowledge" cho team startup Việt

Dùng SessionStart để đồng bộ quy tắc nội bộ. Khi developer mở project tại ~/work/vn-fintech-app, hook detect file .claude/team-rules.md chứa: "API trả về số tiền phải là integer VND, không dùng float. Mọi response phải có X-Request-ID cho tracking. Tuân thủ OWASP Top 10 cho input validation."

Hook trả về additionalContext chứa nội dung này, đảm bảo dù developer mới onboard hay senior remote đều tuân thủ cùng một bộ quy tắc bảo mật và định dạng dữ liệu Việt Nam.

Ép buộc hoàn thành task khi vibe coding landing page

Khi dùng Claude để build landing page bán hàng Tết, Claude hay nghĩ "đã xong" khi chỉ mới viết HTML nhưng chưa link CSS, chưa test responsive mobile, hoặc quên thêm meta tag SEO.

Cấu hình Stop hook để validate: trước khi được phép stop, phải chạy npm run build và npm run test:ui. Nếu build fail, hook return decision: "block" với reason "Còn lỗi hydration ở component Header, cần fix trước khi kết thúc". Điều này ép Claude phải tự sửa lỗi đến cùng, tránh để lại technical debt khi bạn đang "vibe coding" và không để ý Claude đã bỏ dở công việc.

Gửi cảnh báo real-time qua Zalo khi API Anthropic lỗi

Cấu hình StopFailure để gửi message vào nhóm Zalo "DevOps Alerts" khi Claude gặp API error (ví dụ: "Context window exceeded" hoặc "Rate limit hit" sau 10 lần retry).

Hook đọc transcript_path để biết session nào crash, gửi kèm link để team lead có thể resume session ngay lập tức bằng claude -r <session_id> mà không mất context công việc đang dở. Khác với email notification thông thường, cách này giúp team phản ứng trong vài giây thay vì vài phút.

Ứng dụng

Freelancer/Vibe Coder: Dùng Stop hook như "supervisor" để đảm bảo code thực sự chạy được trước khi Claude nghỉ. Tránh tình trạng Claude tuyên bố "hoàn thành chức năng thanh toán VietQR" nhưng quên chưa validate số tài khoản hoặc chưa test với ngân hàng Techcombank.

Team Lead/Tech Lead: Dùng SessionStart để enforce coding standards trên toàn team. Mỗi developer mở project đều tự động load cùng một bộ rules (naming conventions, security guidelines) từ centralized CLAUDE.md, đảm bảo consistency giữa các thành viên làm việc remote từ Hà Nội đến TP.HCM.

DevOps/SRE: Dùng StopFailure để integrate Claude Code vào monitoring stack. Khi automation pipeline dùng claude -p gặp lỗi, notification được gửi đến PagerDuty hoặc Datadog, giúp phát hiện lỗi hệ thống ngay lập tức thay vì pipeline chạy "im lặng thất bại".

So sánh

Kết luận: SessionStart giống như khởi động máy với đúng cấu hình, Stop giống như kiểm tra chất lượng trước khi xuất xưởng, còn StopFailure là camera giám sát khi máy bị lỗi đột ngột.

Bài viết liên quan

Cùng cụm (Hooks):

• Hooks là gì? 25 events và 4 loại hook — Tổng quan kiến trúc event-driven và 4 loại hook chính
• PreToolUse Hook — Chặn lệnh nguy hiểm trước khi chạy bằng exit code 2
• PostToolUse Hook — Auto-format code và logging sau mỗi action
• PermissionRequest Hook — Tự động approve hoặc route request đến WhatsApp/Slack
• Prompt Hook và Agent Hook — LLM-powered automation với semantic triggers
• 8 hook thực tế — Ví dụ cụ thể: format-code, security-scan, context-tracker

Đọc tiếp:

• Tự động Code Review với /loop và GitHub Actions — Ứng dụng Session Hooks để ép buộc test pass trước khi tạo PR trong CI/CD pipeline
• Session Management: Resume, fork, rename, export — Kiểm soát session lifecycle nâng cao với resume và fork strategies