‏Agent Hooks: کنترل قطعی روی رفتار ایجنت‌های هوش مصنوعی

اگه تا حالا پیش اومده که به یه ایجنت هوش مصنوعی بگی «فایل‌های generated رو دست نزن» یا «قبل از اتمام کار تست بزن» و بعد ببینی که باز همون اشتباه تکرار شده، مشکل از پرامپت نیست — مشکل اینه که پرامپت‌ها راهنمایی می‌کنن، اما کنترل قطعی نیستن. Agent Hooks برای همین طراحی شدن: اتصال هندلرهای قابل برنامه‌ریزی به نقاط مشخصی از چرخه‌ی کاری ایجنت.

مدل ذهنی ساده‌ست: event → optional matcher → handler → outcome. یه رویداد (event) یه لحظه‌ی مشخصه مثل شروع سشن یا قبل از اجرای ابزار. یه فیلتر اختیاری تعیین می‌کنه هوک فقط برای چه نوع رویدادی اجرا بشه. یه هندلر اقدام می‌کنه — مثلاً یه اسکریپت پایتون — و یه نتیجه برمی‌گردونه: بلاک کردن، لاگ‌نویسی، یا اضافه کردن کانتکست.

شش نقطه‌ی اصلی وجود داره که اکثر تیم‌ها باهاشون شروع می‌کنن: SessionStart برای لود کردن قوانین پروژه قبل از شروع کار، UserPromptSubmit برای بررسی و غنی‌سازی پرامپت کاربر قبل از اینکه مدل ببینتش، PreToolUse برای بلاک کردن اقدامات خطرناک قبل از اجرا، PostToolUse برای اجرای تست و اعتبارسنجی بعد از تغییر، Stop برای جلوگیری از اتمام زودهنگام کار، و SessionEnd برای نوشتن لاگ نهایی.

یه مثال کاربردی از PreToolUse اینه که مسیر فایل مقصد رو بررسی کنه و اگه داخل پوشه‌های حفاظت‌شده مثل generated/ یا fixtures/sensitive/ بود، قبل از اینکه ویرایش انجام بشه، بلاکش کنه:

protected_prefixes = ("generated/", "fixtures/sensitive/", ".git/")
protected_exact = {".env", ".env.local"}
if rel in protected_exact or any(rel.startswith(p) for p in protected_prefixes):
    block(f"{rel} is protected. Use application code or tests instead.")

برای PostToolUse هم می‌شه بعد از هر ویرایش فایل پایتون، تست‌ها رو اجرا کرد و نتیجه رو در .hook-state/last_quality_gate.json ذخیره کرد. بعد هوک Stop همین فایل رو می‌خونه؛ اگه آخرین تست ناموفق بوده، ایجنت اجازه نداره اعلام کنه کارش تمومه:

state = json.loads(state_file.read_text())
if state.get("status") == "failed":
    print("Quality gate failed. Fix the tests before saying the task is complete.", file=sys.stderr)
    sys.exit(2)

مهمه بدونی که هوک‌ها کل رفتار ایجنت رو قطعی نمی‌کنن — مدل هنوز می‌تونه آزادانه برنامه‌ریزی و استدلال کنه. چیزی که هوک‌ها قطعی می‌کنن اینه که وقتی یه رویداد مشخص اتفاق می‌افته، هندلر تو حتماً اجرا می‌شه؛ صرف نظر از اینکه مدل یادش هست یا نه. این جداسازی خوبه: استدلال باز رو به مدل بده، قوانین قابل‌بیان رو بده به هوک‌ها.

نکات کلیدی:

• هوک‌ها رفتار قابل تکرار رو از حافظه‌ی مدل بیرون می‌کشن و به کد تبدیل می‌کنن
• شش نقطه‌ی اصلی: SessionStart، UserPromptSubmit، PreToolUse، PostToolUse، Stop، SessionEnd
• بهترین نقطه‌ی شروع: یه هوک PreToolUse برای حفاظت از فایل‌های حساس
• هوک‌ها جایگزین پرامپت نمی‌شن — پرامپت برای راهنمایی، هوک برای کنترل
• پیاده‌سازی با یه قانون ساده شروع می‌شه، نه یه سیستم حاکمیتی کامل