‏به دستور اکتفا نکن؛ با Agent Hooks گاردریل بذار

نویسنده این پست رو برای توسعه‌دهنده‌هایی نوشته که با AGENTS.md یا CLAUDE.md برای کدِ تولیدشده توسط ایجنت گاردریل می‌ذارن، ولی می‌بینن ایجنت گاهی قانون‌ها رو نادیده می‌گیره. راه‌حلی که پیشنهاد می‌ده Agent Hooks ه؛ یه چکِ قطعی که به گفتهٔ او صددرصد مواقع کار می‌کنه، برخلاف دستورهای متنی که ایجنت ممکنه ردشون کنه.

اول یه تفکیک مهم: نویسنده تأکید می‌کنه Agent Hooks با git hooks (مثل هوکِ pre-commit که خیلی از برنامه‌نویس‌ها می‌شناسن) فرق داره. محدودیت pre-commit اینه که خیلی دیر، درست موقع کامیت و بعد از تولید کد اجرا می‌شه. ولی Agent Hookها وسط کارِ ایجنت (مثلاً Claude Code) فراخوانی می‌شن و می‌ذارن وسط گردش‌کار دخالت کنی، نه بعد از تموم‌شدن کار. هر هوک یه JSON روی ورودی استاندارد می‌گیره که شکلش به نوع رویداد بستگی داره.

مثال اول یه هوک PreToolUse ه که دقیقاً قبل از اجرای یه ابزار فایر می‌شه و تنها جاییه که واقعاً می‌تونی جلوی خودِ اجرای ابزار رو بگیری. نویسنده اون رو با matcher روی "Write|Edit" تنظیم می‌کنه؛ دستورِ هوک محتوای در حال نوشته‌شدن رو با jq می‌خونه (از مسیر .tool_input.content، و برای ادیت از .tool_input.new_string) و اگه یه تگِ خامِ input توش باشه، با exit 2 نوشتن رو رد می‌کنه. نکتهٔ کلیدی اینه که هرچی با exit 2 به stderr نوشته بشه، ایجنت اون رو به‌عنوان بازخورد می‌بینه؛ پس همون‌جا بهش گفته می‌شه به‌جای تگ خام از کامپوننت طراحیِ خودش استفاده کنه.

مثال دوم یه هوک Stop ه که همون لحظه‌ای فایر می‌شه که ایجنت تصمیم می‌گیره کارش تمومه. این برعکس PreToolUse ه: به‌جای بلاک‌کردن یه اکشن، اصلاً نمی‌ذاره نوبت تموم بشه، و این‌جا exit 2 یعنی «نه، کار رو ادامه بده». نویسنده باهاش یه «ratchet test» مخصوص طراحی‌سیستم رو گِیت می‌کنه، چون بیشترین چیزی که اذیتش کرده این بوده که ایجنت وسط قرمزبودنِ همین تست، اعلام کنه کارش تمومه.

نویسنده دو تله رو هم گوشزد می‌کنه. اول اینکه چک stop_hook_active سرِ هوک Stop اختیاری نیست: بعد از اینکه یه بار ادامه اجباری شد، این فلگ دفعهٔ بعد true برمی‌گرده و اگه بهش بی‌توجه باشی، یه تستِ همیشه‌قرمز ایجنت رو تو یه حلقهٔ بی‌نهایتِ «تلاش ← توقف ← بلاک» گیر می‌ندازه. دوم اینکه اگه مسیرِ jq رو اشتباه بدی، بی‌صدا null برمی‌گردونه و گِیت در حالی که سالم به نظر می‌رسه، عملاً هیچ کاری نمی‌کنه؛ پس هر هوک رو باید روی یه payload واقعی تست کنی.

نکات کلیدی:

• Agent Hooks یه گاردریلِ قطعی‌ان که وسط کار ایجنت اجرا می‌شن، نه یه توصیهٔ متنی که نادیده گرفته بشه
• هوک PreToolUse قبل از اجرای ابزار فایر می‌شه و با exit 2 می‌تونه جلوی اکشن رو بگیره و بازخورد بده
• هوک Stop نمی‌ذاره ایجنت کارش رو تموم اعلام کنه تا یه شرط (مثلاً یه تست) برقرار بشه
• حتماً stop_hook_active رو چک کن تا تو حلقهٔ بی‌نهایت گیر نکنی، و مسیرهای jq رو تست کن