{ name, preToolCall?, postToolCall?, preGenerate?, postGenerate? } يعمل داخل الـ agent loop، حول كل tool call وكل model call. استخدمه لكتابة audit log، أو لرفض tool، أو لحجب نتيجة أو قصّها، أو لحقن context قبل الـ model call، أو لتغيير الـ request الذي سيُرسَل (header أو temperature).
الـ hooks كود تكتبه أنت، وليست policy ولا قرارًا بشريًا: للقواعد التي تسمح أو ترفض أو تسأل على مستوى كل tool، ولموافقة شخص على call معيّن، استخدم permissions وneedsApproval (الموافقات). الـ listeners مثل onEvent تراقب الـ run فقط ولا تستطيع تغييره (Streaming)؛ أما الـ hook فيستطيع.
أول hook لك
مرّر الـ hooks إلىcreateAgent({ hooks }). هذا الـ hook يسجّل كل tool call والنتيجة التي أعادها:
ctx.args أو ctx.messages أو ctx.request في مكانه يغيّر الـ run أيضًا.
نقاط الـ hook الأربع
الحقول المشتركة في كل context هي
agentId وagentName وsessionId وmessages (سجل المحادثة الـ live) وmetadata (مساحة حرة تضع فيها ما تريد) وsubagent (تُملأ داخل sub-agent). سياقات الـ tool call تحمل أيضًا resumedAfterApproval: تكون true فقط عندما يعمل الـ hook على call يُعاد تشغيله بعد أن وافق شخص على إيقافه، لكي يستطيع hook لديه state (مثل loop guard أو عدّاد audit) تخطي إعادة التشغيل بـ if (ctx.resumedAfterApproval) return;. ويوجد ctx.emit عندما يكون للـ run listeners (createAgent({ onEvent }) أو onAgentEvent) أو عندما يكون هناك streaming، ويضيف حدثَي compaction.start وcompaction.done إلى أحداث الـ run. وداخل run الـ executor، يحصل preGenerate أيضًا على ctx.generate(provider, request, purpose): model call جانبي (يستخدمه الـ summarizer الخاص بالـ compaction) له chat span خاص به موسوم بـ lousho.call.purpose، ويُحسب ضمن usage الخاص بالـ run وضمن الـ budgets.
Hook outcomes
الـ tool-call hook يستطيع أن يغيّر ما يحدث، لا أن يراقبه فقط. الـpreToolCall hook يستطيع أن يعيد:
- لا شيء: يستمر الـ call دون تغيير (وتعديل
ctx.argsفي مكانه يعمل أيضًا). { deny: reason }: لا يعمل الـ call. يصل إلى الـ model خطأ الـ tool نفسهkind: 'denied'الذي ينتج عن رفضneedsApproval(انظر الموافقات)، وترى الـ streamstool.error، وonPermissionDecisionيسجّلdecision: 'deny'معhookوreason.{ result: value }: لا يعمل الـ call وتصبحvalueنتيجته. حدثtool.doneورسالةtoolفي الـ transcript (metadata) يحملانreplacedByHook: '<hook name>'.{ input: args }: يعمل الـ call بـargs. يُجرى عليها validation مرة أخرى مقابل الـ input schema الخاصة بالـ tool؛ وإذا لم تطابقها تصبح خطأ tool من النوعkind: 'validation'تذكر رسالته اسم الـ hook، ولا يعمل الـ tool.
postToolCall hook يستطيع أن يعيد { result: value } لاستبدال النتيجة التي
يراها الـ model (يحجبها أو يقصّها)؛ وإعادة لا شيء تُبقي النتيجة الأصلية. الـ hooks
تعمل بترتيب تسجيلها: أول deny أو result من pre-hook يتخطى الـ pre-hooks التي تليه،
وقيم input تتسلسل (كل hook يرى قيمة الذي قبله في
ctx.args)، وكل post-hook يرى النتيجة التي استبدلها hook قبله. والـ hook
الذي يرمي error يُفشل الـ run كما كان من قبل. والـ sub-agents ترث hooks
الـ agent الرئيسي ونتائجها.
أمثلة
كل مثال برنامج كامل. جميعها تعمل علىmockModel، فلا يحتاج أيٌّ منها إلى API key ولا إلى model call حقيقي؛ والنمط نفسه يختبر الـ hooks التي كتبتها offline (Testing). كل مثال يجهّز turn للـ model فيه tool call، تليه إجابة نهائية.
أوقف run لا يتقدّم
createProgressGuard() يوقف run ينفق الـ budget الخاص به على calls لا تؤدي إلى شيء. وهو معطّل ما لم تُضِفه:
- ابتداءً من الفشل الثاني لـ tool بالخطأ نفسه، يضيف
hintإلى النتيجة، فيه نصيحة بحسب نوع الفشل (classifyToolFailure(): input خاطئ، أو timeout، أو قدرة ناقصة، أو صلاحية، أو غير معروف). - بعد
maxFailuresمن حالات الفشل بالخطأ نفسه (الافتراضي 3)، يرفض هذا الـ tool لبقية الـ run. الأرقام في الرسالة لا تجعل الخطأ مختلفًا. - بعد
maxRepeatsمن الـ calls المتطابقة التي تعيد النتيجة نفسها (الافتراضي 3)، يرفض هذا الـ call. الـ call الذي تتغيّر نتيجته ليس تكرارًا. - بعد أن تعيد
maxSameResultsمن الـ calls لـ tool النتيجة نفسها (الافتراضي 5)، يرفض هذا الـ tool، حتى لو اختلفت الـ arguments في كل call. هذا يكشف الـ model عندما يعيد صياغة بحث يظل يجد الشيء نفسه. - بعد
maxDenialsمن حالات الرفض (الافتراضي 3)، يوقف الرفض التالي الـ run بـLOUSHO_RUN_NO_PROGRESS، ولا يعيدagent.recover()محاولته.
heal.action. النتيجة التي استبدلها تُعلَّم على الـ span الخاص بالـ tool بـ lousho.tool.replaced_by_hook، ويُسجَّل الرفض كخطأ في الـ span. الـ guard يعدّ من سجل محادثة الـ run، فيحتفظ الـ run المستأنَف بتاريخه. الـ calls الموجودة في batch واحدة لا تُعدّ إلا بعد أن تنتهي الـ batch، وقد يُزيل ضغط السياق (compaction) calls قديمة من العدّ.
افحص ما أخرجته الـ tool
الكتابة الناجحة لا تثبت أن الـ output صالح للاستخدام.createOutputCheck() يشغّل الفحص الخاص بك بعد أن تنجح الـ tool. إذا أعاد مشكلة، أو رمى خطأً، يراها الـ model كـ outputCheckFailed على النتيجة ويستطيع إصلاح الـ output. الفحص هو كودك، فاجعله مستقلًا عما كتبه الـ model.
امنع tool بالاسم
أضف argument افتراضي
أعِد{ input } لكي تشغّل الـ tool بـ arguments مختلفة. يُجرى عليها validation مرة أخرى مقابل الـ schema الخاصة بالـ tool.
قصّ النتيجة أو احجبها
الـpostToolCall يستلم النتيجة المستقرة، ويستطيع أن يعيد { result } لكي يستبدل ما يراه الـ model. الـ tool نفسه عمل دون تغيير.
احقن context قبل الـ model call
الـpreGenerate يرى ctx.messages وctx.request الـ live. نفّذ push لرسالة لكي تضيف context، أو غيّر حقلًا في الـ request.
الترتيب والتفاعل
للـ tool call الواحد، الترتيب هو: validation على الـ arguments، ثمpreToolCall hooks،
ثم قواعد الـ permissions (permissions)، ثم الـ tool guardrails، ثم needsApproval الخاص بالـ tool،
ثم إيقاف الموافقة، ثم التنفيذ، ثم postToolCall hooks. الـ hooks تعمل قبل كل
قرار موافقة، فالقواعد وneedsApproval والشخص جميعهم يرون
الـ input الذي أنتجه الـ hook ويوافقون عليه؛ وargs في الموافقة المعلّقة تُظهره. وعندما يُستأنف
call موافَق عليه، تعمل الـ pre-hooks مرة أخرى: تظل قادرة على رفضه أو
تقديم نتيجته، لكن { input } المختلف عن الـ input الموافَق عليه يُرفض
بخطأ tool بدلًا من أن يعمل. انظر الموافقات للإيقاف والاستئناف.
- أكثر من hook تعمل بترتيب مصفوفة
hooks، واحدًا تلو الآخر: يُنتظر كل واحد بـawaitقبل الذي يليه، فيرى الـ hook اللاحق ما غيّره السابق. - hook يرمي error يُفشل الـ run. الـ hooks كود موثوق: لا يتحوّل الـ error إلى tool result يراه الـ model.
- Compaction.
createAgent({ hooks })يشغّل الـ hooks التي كتبتها أولًا، ثم الـ compaction hook، فيرى الـ compaction ما أضافته (Context compaction). - Sub-agents ترث hooks الـ agent الرئيسي.
ctx.subagentتُملأ عندما يعمل الـ hook داخل أحدها، فيستطيع الـ hook أن يعود مبكرًا لكي يرى الـ run الأعلى فقط (الـ hooks داخل الـ sub-agents).
HookRegistry
createAgent({ hooks }) يقبل array عاديًا. الكود الذي يستخدم الـ executor API (executor API) يمرّر HookRegistry: مجموعة مرتّبة فيها register وregisterMany وget وhas وlist وunregister وclear وsize() — انتبه، size هي method (hooks.size())، وليست property بنمط Map. تسجيل hook ثانٍ بالـ name نفسه يستبدل الأول ويطبع warning.
HookRegistry وAgentHook وأنواع الـ context موجودة في جذر الـ package وفي الـ subpath lousho/hooks. الـ hooks التي تُكتب في محرر الـ canvas الخاص بـ Agent Forge تُترجَم إلى HookRegistry وتعمل داخل sandbox بدلًا من الـ host process: انظر Agent Forge.