agent-usage-guard: Tiện ích chặn Claude Code "đốt sạch" hạn mức 5 giờ trong 10 phút

Cộng đồng phát triển phần mềm đang chú ý tới agent-usage-guard, một tiện ích mở rộng (mod) chạy bên trong Claude Code nhằm ngăn tình trạng tiêu tốn hạn mức sử dụng một cách mất kiểm soát. Công cụ này đọc hạn mức thực tế của gói đăng ký, giới hạn số tác nhân con được khởi chạy song song và chặn các vòng lặp thử lại vô tận — tất cả trước khi chi phí thực sự phát sinh.

Bản demo agent-usage-guard hoạt động trong giao diện Claude Code

Vấn đề xuất phát từ một buổi chiều "cháy" hạn mức

Tác giả của tiện ích kể lại rằng ông từng giao cho Claude Code một bài toán nghiên cứu ở mức nỗ lực tối đa. Kết quả: 394 lượt gọi tác nhân con, trong đó 341 lượt chạy cùng lúc, đẩy 84 triệu token ngữ cảnh qua API chỉ trong vòng 10 phút. Phiên làm việc kết thúc bằng thông báo "Claude usage limit reached" — và người dùng bị khóa cho tới khi cửa sổ hạn mức được làm mới.

Đây không phải sự cố cá biệt. Theo nhật ký 60 ngày của chính tác giả, đã có 12 lần bị khóa và 166 cửa sổ 10 phút ghi nhận các đợt bùng nổ tác nhân. Cơ chế thất bại mang tính nhân lên: ngữ cảnh lớn × vòng lặp công cụ nhanh × tác nhân song song × thử lại mù quáng. Mỗi biện pháp bảo vệ trong công cụ này nhằm loại bỏ một yếu tố trong chuỗi đó.

"Nó can thiệp trước khi chi phí phát sinh, chứ không phải sau đó: trước khi một tác nhân khởi chạy, một prompt được gửi đi, hay một lệnh công cụ được thực thi."

Cách thức hoạt động

Tiện ích áp dụng một loạt quy tắc mặc định khá chặt:

• Tác nhân mới cần phê duyệt khi cửa sổ hạn mức của gói đã dùng tới 80%, và bị từ chối khi chạm 95%.
• Tối đa 4 tác nhân chạy cùng lúc trên toàn máy, bất kể phiên làm việc nào.
• 12 lượt khởi chạy hoặc khôi phục tác nhân trong 10 phút, và 10 triệu token do tác nhân con xử lý trong 10 phút.
• Tác nhân con không được tự sinh thêm tác nhân (giới hạn độ sâu 1).
• Ngữ cảnh vượt 300 nghìn token sẽ kèm ghi chú nhắc Claude giữ lượt trả lời trong phạm vi hợp lý; vượt 500 nghìn token thì prompt phải được người dùng xác nhận.
• Ba lần thất bại giống hệt nhau liên tiếp sẽ khiến lần thử lại y hệt đó bị từ chối.

Khi người dùng đang ngồi trước bàn phím, công cụ đặt câu hỏi ngay trong hộp thoại quen thuộc của Claude Code. Nếu không ai trả lời — chẳng hạn khi chạy claude -p, Agent SDK hay chế độ dontAsk — nó sẽ từ chối và giải thích lý do cho mô hình, để Claude biết cách chờ, gộp việc hoặc dừng lại.

Riêng tư và an toàn

Tiện ích được thiết kế theo hướng cục bộ và tối giản về dữ liệu:

• Không gửi yêu cầu mạng, không khởi tạo tiến trình nào.
• Không lưu nội dung prompt, dữ liệu đầu vào của công cụ hay kết quả của mô hình. Mỗi lệnh gọi công cụ chỉ được rút gọn thành một mã vân tay gồm 13 ký tự.
• Chỉ ghi lại số liệu đếm và các nhóm ngưỡng thô (ví dụ 400–500 nghìn token).
• Cơ chế "fails open": nếu một móc nối (hook) gặp lỗi, sự kiện vẫn được thực hiện — một tiện ích hỏng sẽ không làm hỏng phiên làm việc của bạn.

Mã nguồn khoảng 2.400 dòng TypeScript, không có thư viện phụ thuộc, phát hành theo giấy phép MIT. Người dùng có thể kiểm tra toàn bộ API và biến môi trường mà công cụ sử dụng bằng lệnh claude plugin validate ..

Cài đặt và cấu hình

Để dùng thử, chạy các lệnh sau bên trong Claude Code phiên bản 2.1.287 trở lên:

/plugin marketplace add rbartoli/agent-usage-guard
/plugin install agent-usage-guard@agent-usage-guard
/reload-plugins

Sau đó, lệnh /agent-guard sẽ hiển thị trạng thái hiện tại, /agent-guard report cho biết công cụ đã can thiệp những gì trong 7 ngày gần nhất, còn /agent-guard allow tạm nới lỏng giới hạn trong 10 phút. Đáng chú ý, lệnh này chạy trực tiếp và không bao giờ khởi tạo một lượt gọi mô hình, nên Claude không thể diễn giải việc nới lỏng như một sự cho phép chung.

Mọi tham số đều có thể tinh chỉnh qua biến môi trường hoặc trong ~/.claude/settings.json, chẳng hạn AGENT_GUARD_AGENT_MAX cho số tác nhân tối đa hay AGENT_GUARD_LIMIT_DENY_PERCENT cho ngưỡng từ chối.

Giới hạn cần biết

Công cụ không nhìn thấy tất cả. Các tác nhân chạy trong cửa sổ terminal riêng, hay các phiên trên máy khác, đều nằm ngoài tầm kiểm soát. Lệnh /subtask và một số đường dẫn khởi chạy không có sự kiện báo trước nên chỉ được đếm mà không bị chặn. Với người dùng khóa API thay vì gói đăng ký, phần trăm hạn mức cửa sổ sẽ không được báo cáo, nên chỉ còn giới hạn token và số lượt có hiệu lực.

Dù vậy, với những ai thường xuyên dùng Claude Code cho các tác vụ nặng và từng một lần ngồi nhìn thông báo hết hạn mức giữa chừng công việc, đây là một tiện ích đáng để thử — nhất là khi toàn bộ mã nguồn mở và có thể kiểm tra trước khi cài. Người dùng tại Việt Nam đang trả phí theo gói Pro hoặc Max sẽ đặc biệt được hưởng lợi, bởi mỗi cửa sổ hạn mức bị đốt oan đều đồng nghĩa với thời gian chờ đợi không thể làm việc.