أحداث الهوك

كيف تُربط الهوكات#

يضيف aipager config (أو aipager setup) مدخلات aipager إلى ‎~/.claude/settings.json، ويتحقق منها aipager عند كل بدء:

• أمر aipager-hook واحد لكل حدث من الأحداث الستة عشر أدناه، مع المطابِق * على أحداث الأدوات (PreToolUse وPostToolUse وPermissionRequest)؛
• مهلة ٥ ثوانٍ لـ PreModelSwitch، ومن aipager config وaipager setup مهلة ٣٠ ثانية لـ PermissionRequest (الهوك نفسه ينتظر ٢٠ ثانية على الأكثر، يُنظر أدناه)؛ وتستخدم المدخلات الأخرى قيمة Claude Code الافتراضية؛
• أمر statusLine، وهو aipager-statusline.

يزيل aipager uninstall هذه المدخلات مجددًا (يُنظر الأوامر).

يبدأ Claude Code عملية aipager-hook جديدة (aipager.dtach.notify_hook:main) لكل حدث. تقرأ العملية JSON الحدث من stdin، وتضيف حقلين (أدناه)، ثم ترسله إلى aipager كـ datagram واحد عبر مقبس Unix. المقبس هو، بهذا الترتيب: ‎$AIPAGER_INSTANCE_DIR/aipager.sock لنسخة اختبار معزولة، أو ‎$AIPAGER_SOCKET_PATH، أو ‎$XDG_RUNTIME_DIR/aipager.sock، أو ‎/tmp/aipager.sock. الإرسال لا ينتظر أبدًا: إذا لم يكن هناك aipager يستمع، يُهمل الحدث، ويلحق مراقب الجلسات بما فات من ملفات الجلسة.

معظم الأحداث تكلّف Claude Code نحو ٢٠ إلى ٢٥ ملّي ثانية لبدء العملية. بعضها يحمّل أيضًا شيفرة القواعد في aipager: قبل استدعاء أداة (فحص الأمان، يُنظر PreToolUse) نحو ٧٠ ملّي ثانية، وعند نهاية مهمة (لمسح علامة المهمة المفتوحة) نحو ٥٥ ملّي ثانية، وUserPromptSubmit (الذي يكتب قواعد المهمة). أما PermissionRequest فينتظر ضغطتك عن قصد، حتى ٢٠ ثانية.

يحدّ الهوك ذاكرته بـ ١ غيغابايت. الهوك الذي يبلغ هذا الحد يخرج بخطأ (في PreToolUse، برمز الخروج الذي يفهمه Claude Code رفضًا) ويرسل إلى aipager رسالة hook_memory_cap_hit، تصبح إشعارًا في الدردشة، مع زر «🐞 الإبلاغ عن هذا» لمالك التثبيت (يُنظر تقارير المشكلات). ضبط AIPAGER_DEBUG=1 في بيئة الجلسة يجعل الهوك وسطر الحالة يطبعان معلومات التشخيص على stderr.

ما الذي يستقبله aipager#

الـ datagram هو JSON الهوك الخاص بـ Claude Code نفسه، مضافًا إليه حقول aipager (بعض الأحداث تحمل أكثر، ومذكورة تحت كل حدث أدناه):

تحمل أحداث الأدوات أيضًا tool_name وtool_input. كل حدث يقع داخل وكيل فرعي (subagent) يحمل agent_id (وأحداث الوكيل الفرعي تحمل agent_type)؛ أما أحداث الحلقة الرئيسية فلا، وبهذا يضع aipager استدعاءات أدوات الوكيل في سطر ذلك الوكيل.

مرجع الأحداث#

معالجات aipager موجودة في aipager/dtach/hook_receiver.py؛ وعمل الهوك نفسه في aipager/dtach/notify_hook.py.

SessionStart#

بدأت جلسة، أو استُؤنفت، أو لُخّصت محادثتها. الجلسة التي لا يتتبعها aipager بعد تُسجَّل. بعد التلخيص تعرض البطاقة 📦 name · لُخّصت المحادثة: ٨٢٪ ← ٤٪ (يُنظر PreCompact). وفي محادثة جديدة يمسح الهوك أيضًا علامة المهمة المفتوحة للمهمة السابقة.

SessionEnd#

انتهت الجلسة. تُعلَّم بأنها GONE: تغادر شريط الحالة المثبّت وتنتقل إلى الجلسات المنتهية، حيث يستطيع ‎/resume إعادتها. يبدأ aipager session <name>‎ أو ‎/new <name>‎ جلسة جديدة.

UserPromptSubmit#

أخذ Claude رسالة، مكتوبة في الطرفية أو مرسلة من Telegram.

يطابق الهوك أولًا الرسالة مع ملاحظات الإذن الخاصة بالجلسة (‎/tmp/claude-notes-<session>/‎، واحدة لكل رسالة Telegram كتبها aipager) ويكتب قواعد المهمة في ‎/tmp/claude-policy-<session>.json، الذي يقرؤه فحص PreToolUse (يُنظر الأمان ← تطبيق القواعد في وضع الفريق). ويخبر aipager بالرسائل التي أخذها Claude (رسالة queue_pickup) قبل أن يمرّر الحدث. ثم يطبع سياقًا إضافيًا لـ Claude حين يوجد: أسلوب الإجابة المختار في ‎/settings، وعند الرد على رسالة أقدم، ما قالته تلك الرسالة ومتى. رسالة ‎<task-notification>‎ (عندما يوقظ Claude نفسه لأن وكيلًا في الخلفية أو أمرًا في الخلفية انتهى) هي استمرار للعمل نفسه: لا تطابق أي ملاحظة وتُبقي قواعد المهمة.

يعلّم aipager الجلسة بأنها تعمل، ويفتح بطاقة العمل إن لم تكن موجودة (الرسالة المرسلة من Telegram لها بطاقة سلفًا)، ويحوّل 👀 على الرسائل التي أخذها Claude إلى 👍. والرسالة المرسلة أثناء مهمة جارية تحصل على 👍 عندما يضمها Claude إلى تلك المهمة أو يبدأ بها المهمة التالية.

PreToolUse#

أداة على وشك العمل. هنا يعمل فحص الأمان الخاص بـ aipager، داخل الهوك، قبل أن ينظر Claude Code في قواعد الأذونات الخاصة به:

• المهمة التي بدأت من Telegram تخضع لقواعد دور مرسلها وللحد الأدنى للأمان (المسارات المحمية، وأنماط الأوامر)، ولا يتجاوزه إلا الدور owner؛ والمهمة التي لا يستطيع aipager نسبتها إلى أحد تحصل على الحد الأدنى؛ والرسالة المكتوبة في الطرفية لا قيود عليها. القواعد مشروحة في المجموعات والأمان.
• عندما ترفض قاعدةٌ الاستدعاء، يطبع الهوك قرار deny، فيرفض Claude Code الأداة دون أن يسأل، ويُبلَّغ aipager (safety_blocked): تتوقف المهمة مع 🛑 x1 · منعتها قاعدة الأمان: ... (أُوقفت)، ويُرفض كل استدعاء أداة لاحق في تلك المهمة أيضًا.
• يُفحص استدعاء SendUserFile (إرسال Claude ملفات إلى الدردشة) لكل مهمة، بما فيها مهام المالك والرسالة المكتوبة في الطرفية: الحد الأدنى للإرسال وفحوص الملف وقواعد المهمة نفسها (الأمان). يحصل الاستدعاء المرفوض على deny بلا علامة «aipager safety policy»: يقرأ Claude السبب ويُخبرك به، وتستمر المهمة، ويرسل الهوك إلى aipager رسالة send_files_refused تذكر كل ملف، لسجل التدقيق.
• الفحص الذي يتعطل يرفض، ما لم تكن قواعد الجلسة مقروءة وتمنح استثناء المالك.

من جهة aipager، يصبح الاستدعاء سطرًا في بطاقة العمل (استدعاء الوكيل الفرعي يذهب إلى سطر ذلك الوكيل)، ويعرض Write أو Edit معاينة للتغييرات عندما يكون ‎/settings ← معاينة التغييرات (diff) مفعّلًا (معطّل افتراضيًا). استدعاء AskUserQuestion يصبح السؤال مع زر لكل خيار؛ والسؤال الذي يطرحه وكيل مساعد في Claude Code حين لا تجري أي مهمة لا يُعرض (ليس Claude من يسألك). استدعاء Agent الخاص بـ Claude يترك subagent_type وdescription للوكيل الذي يبدؤه، واستدعاء الوكيل الفرعي هو آخر نشاط لذلك الوكيل: كلاهما يظهر في الحالة تحت الإجابة ما دام الوكيل يعمل في الخلفية.

PermissionRequest#

‏Claude Code على وشك طلب إذن. تصبح بطاقة العمل هي الطلب، مع الأمر أو المسار الحقيقي تحت وصف Claude له (يُنظر الأوامر ← طلبات الإذن): السماح، والرفض، والإيقاف، والسماح دائمًا فقط عندما يقدّم Claude Code قاعدة حقيقية لتذكّرها.

يجيب الهوك عن الطلب بنفسه حين يستطيع. يفتح مقبس رد قصير العمر، ويرسل عنوانه مع الحدث، وينتظر ضغطتك حتى ٢٠ ثانية. الضغطة التي تصل في الوقت تعود كقرار PermissionRequest (سماح، أو سماح مع القاعدة، أو رفض)، فلا يعرض Claude Code مربع الحوار الخاص به أبدًا. إذا لم تأتِ ضغطة في الوقت، يخبر الهوك aipager بأن الانتظار انتهى (permission_reply_timeout) ولا يطبع شيئًا؛ ولا يطبع شيئًا أيضًا عندما يتعذر الوصول إلى aipager أو يفشل أي شيء في هذا المسار. عندها يعرض Claude Code مربع الحوار الخاص به في الطرفية، والضغطة اللاحقة تجيب عنه بكتابة المفاتيح. يسجّل سجل التدقيق (‎~/.claude/aipager-audit.jsonl) الطريقة التي أجابت بها كل ضغطة، ‎"via": "hook_decision"‎ أو ‎"via": "keystroke_fallback"‎.

ويظهر أيضًا PermissionRequest يصل وطلب آخر مفتوح، رسالةً مستقلة تحت بطاقة العمل. ومربع الحوار نفسه إذا وصل مرة أخرى (الطالب نفسه والأداة والاستدعاء نفسها، أو الإدخال نفسه) يظهر مرة واحدة. ويشغّل Claude Code هذا الهوك لـ AskUserQuestion أيضًا؛ وذلك السؤال ظاهر أصلًا من PreToolUse الخاص به، فلا يُعرض مرة ثانية أبدًا. ولا يظهر مربع حوار وكيل في الخلفية في الطرفية إلا بعد أن يتوقف هوكه عن الانتظار، تحت أي مربع حوار مفتوح هناك، ولهذا لا تكتب الضغطة مفاتيح إلا في الطلب الذي يعرضه Claude Code أولًا (يُنظر الأوامر ← طلبات الإذن).

PostToolUse / PostToolUseFailure#

انتهت أداة، أو فشلت. يستقر سطرها في بطاقة العمل (ويُعلَّم الفشل على السطر)، وتُلاحظ الإجابة عن طلب مفتوح: زر سماح أو رفض قديم لذلك الطلب لا يكتب شيئًا بعد ذلك. تحتفظ الجلسة بأحدث ٢٠٠ سطر أدوات.

استدعاء Bash نقله Claude Code إلى الخلفية يبلّغ عن backgroundTaskId. يتتبعه aipager عندئذٍ كأمر في الخلفية (للحلقة الرئيسية فقط: الاستدعاء الذي يحمل agent_id يخص ذلك الوكيل الفرعي) حتى يرى نهايته: ‎<task-notification>‎ فيه ‎<status>‎ (في الرسالة التي توقظ Claude، أو في سجل المحادثة عندما يصل في منتصف مهمة)، أو TaskStop أو KillShell بمعرّفه، أو انتهاء الجلسة، أو ساعتان (AIPAGER_BG_SHELL_MAX_TRACK، بالثواني، الافتراضي 7200). يُنظر الأوامر لسطره في البطاقة.

استدعاء Agent (أو Task) الذي يجري داخل وكيل فرعي (يحمل حدثه agent_id) يذكر معرّف الوكيل الذي بدأه. ويتذكر aipager أي وكيل بدأ أي وكيل، فيميّز الوكيل الذي توقف لينتظر وكيله الخاص من الوكيل الذي انتهى (يُنظر SubagentStart /‏ SubagentStop أدناه).

ينسخ aipager ملفات SendUserFile الذي اكتمل فورًا، مرة واحدة لكل استدعاء وفقط خلال مهمة بدأت بموجّه، من القائمة التي أظهرها PreToolUse الخاص به (لا من نتيجة الأداة أبدًا)، ويفحص كل ملف من جديد؛ وتُرسل النسخ بعد إجابة المهمة، حين يُعثر على الاستدعاء في سجل المحادثة الذي سجّله aipager للمهمة مكتوبًا خلال تلك المهمة (الأمان، الأوامر). المهمة التي يبدؤها Claude Code دون hook (رسالة يأخذها بعد ذلك، أو ردّ hook من نوع Stop) تُحتسب بمجرد أن يُظهر سجل المحادثة أنها بدأت.

Notification#

يقرأ aipager حقل notification_type من Claude Code:

• ‏permission_prompt: إشارة أبطأ وأقدم لطلب إذن. ولا تعرض الطلب إلا عندما لا يكون أي طلب مفتوحًا: فإذا كان طلب مفتوحًا، فهو مربع الحوار الذي عرضه PermissionRequest بالفعل.
• ‏idle_prompt بينما ينتظر طلب إذن أو سؤال: تبقى الجلسة في حالة الانتظار، وتتلقى الدردشة ⬆️ jim · لا تزال بانتظار إجابتك في الأعلى، مرة واحدة لكل انتظار.
• ‏idle_prompt في غير ذلك: يُعامل مثل Stop (أدناه). يلتقط مهمة ضاع حدث Stop الخاص بها؛ والإجابة التي سُلّمت لا تُرسل مرة أخرى أبدًا.

Stop#

انتهت المهمة. تصبح الجلسة جاهزة، وتستقر بطاقة العمل حسب الشكل الذي اخترته، وتُرسل إجابة Claude (من last_assistant_message في الحدث، وإلا من سجل المحادثة). ثم تُرسل الرسائل التي احتُجزت حتى انتهاء المهمة. الوكلاء والأوامر في الخلفية التي ما زالت تعمل تُبقي العمل مفتوحًا: تبقى البطاقة حالةً للعمل، وتنتهي الإجابة بحالة حية لذلك العمل: ما يفعله كل وكيل وكم أمرًا في الخلفية من أوامر العمل يعمل (يُنظر الأوامر ← وكلاء ما زالوا يعملون). يمسح الهوك علامة المهمة المفتوحة أولًا، ما لم يكن لدى Claude رسالة في قائمة الانتظار تصبح المهمة التالية فورًا.

StopFailure#

انتهت المهمة بخطأ في الواجهة البرمجية. تصبح الجلسة جاهزة وتُسلَّم الإجابة، إن وُجدت، كما في Stop؛ ويُعرض الخطأ المعروف (ازدحام، حد عدد الطلبات، ...) بكلمات بسيطة.

SubagentStart / SubagentStop#

بدأ وكيل فرعي أو انتهى. لكل واحد سطره الخاص في بطاقة العمل، ‎🤖 <type> · <activity> · <elapsed>‎، واستدعاءات أدواته مطوية تحته، ويستقر على ✅ 🤖 <type> · استخدم N أدوات · <elapsed> عندما يتوقف. لا يقول SubagentStart أي وكيل بدأه: يطابقه aipager مع استدعاء Agent (PreToolUse) المنتظر من النوع نفسه. إذا جاءت كل هذه الاستدعاءات من وكيل واحد، يُربط الوكيل الجديد بذلك الوكيل فورًا (يصبح سطره في البطاقة ‎🤖 pipeline-runner › ship-tester، وينضم إلى الوكلاء تحته في الحالة أسفل الإجابة)؛ وإذا جاءت من وكلاء مختلفين، لا يُربط شيء حتى يذكره PostToolUse الخاص بالوكيل الذي بدأه. لا يُستخدم وصف الاستدعاء إلا إذا كان استدعاء واحد بالضبط من ذلك النوع ينتظر. الوكيل الفرعي الذي لا يصل SubagentStop الخاص به أبدًا يُحذف بعد صمت ٣٠ دقيقة (AIPAGER_SUBAGENT_SILENCE، بالثواني؛ لا حدث من أي نوع يحمل معرّفه). الوكيل الذي يعمل يرسل أحداث أدوات كل بضع ثوانٍ، لذا لا يجمع هذا إلا وكيلًا فات توقفه (إعادة تشغيل، datagram ضائع)؛ واستدعاء أداة واحد يعمل ٣٠ دقيقة دون أي حدث تحت معرّف ذلك الوكيل يجمعه أيضًا. يُقبل AIPAGER_SUBAGENT_TTL اسمًا قديمًا للإعداد نفسه.

الوكيل في الخلفية الذي يتوقف بينما وكيل بدأه ما زال يعمل يتلقى SubagentStop أيضًا. ويعدّ aipager ذلك توقفًا مؤقتًا لا نهاية: يبقى الوكيل قيد العمل (سطره، والعمل، والحالة تحت الإجابات، والشريط المثبّت). وSubagentStart التالي له بالمعرّف نفسه هو استئنافه ولا يضيف سطرًا ثانيًا؛ وأي استدعاء أداة يجريه هو نفسه يُعدّ استئنافًا كذلك. وينتهي حين يتوقف دون أن يكون أي من وكلائه الخاصين قيد العمل. وإذا لم يستأنف بعد دقيقتين من انتهاء آخرهم، لا يُعدّ قيد العمل بعد ذلك، لكنه لا يُعرض منتهيًا أبدًا. ويُحتفظ بالوكلاء العاملين، ومنهم المنتظرون، عبر إعادة تشغيل aipager. أحداث SubagentStop بلا نوع وبمعرّف غير معروف تصل كثيرًا وتُتجاهل.

PreCompact / PostCompact#

يلخّص Claude سياقه (trigger قيمته auto أو manual). تعرض بطاقة العمل 🔄 name · يجري تلخيص المحادثة (رسالة جديدة إن لم تكن هناك بطاقة)، حتى لا يبدو التوقف كأنه تعطّل. ينهي PostCompact تلك الحالة؛ ويأتي السطر 📦 name · لُخّصت المحادثة: X٪ ← Y٪ من SessionStart الذي يليه، أو من سطر الحالة إن فات ذلك. ويعطي سطر الحالة أيضًا التحذير ⚠️ name · امتلأ السياق بنسبة ٨٢٪ - سيُلخَّص تلقائيًا قريبًا (مع زر «تلخيص الآن») عندما يبلغ السياق ٨٠٪، مرة واحدة في كل محادثة: التلخيص لا يكرّره، والمحادثة الجديدة (بعد ‎/clear مثلًا) تتلقاه من جديد.

MessageDisplay#

نص Claude نفسه لحظة وصوله إلى الشاشة. لا يُكتب سجل المحادثة إلا بعد كل جولة من استدعاءات الأدوات، لذا فهذا هو المصدر الحالي الوحيد لما يقوله Claude، وهو ما ينقل تعليقاته إلى بطاقة العمل. نص الوكيل الفرعي (أي حدث يحمل agent_id الخاص به) لا يُعدّ أبدًا نصًا لـ Claude: لا يصل أبدًا إلى تعليقات بطاقة العمل، ولا إلى Mini App، ولا إلى سجل المهمة، ويصبح آخر نشاط لذلك الوكيل في الحالة تحت الإجابة. لا يضيف الهوك بيانات سطر الحالة إلى هذا الحدث: Claude Code ينتظره أثناء الرسم، وهو يقع عدة مرات لكل رسالة.

PreModelSwitch#

يطلق Claude Code 2.1.251 وما بعده هذا الحدث قبل تبديل النموذج. تحمل البيانات from_model وto_model وrequested_model وsource (command لأمر ‎/model مكتوب، أو picker أو sdk). عادةً يسأل Claude Code «Switch model?» قبل التبديل، لأن الإجابة التالية يجب أن تعيد قراءة المحادثة كلها. الهوك الذي يجيب permissionDecision: "allow"‎ يسمح بالتبديل دون ذلك السؤال.

لا يجيب aipager-hook بـ allow إلا لتبديل كتبه aipager نفسه، من عنصر النموذج في Mini App أو من لوحة مفاتيح النماذج. كل تبديل آخر لا يحصل على إجابة، فيسأل Claude Code كعادته. ويشمل ذلك أمر ‎/model الذي يكتبه مالك البوت بنفسه في الطرفية، والمنتقي، والتبديل عبر SDK.

يتعرف aipager على تبديلاته عبر ملف علامة. قبل أن يكتب ‎/model <name>‎ مباشرة، يكتب aipager الملف aipager-modelswitch-<session>.json:

• يوضع في المجلد الذي يحتوي مقبس التحكم (عادةً ‎$XDG_RUNTIME_DIR)؛
• يُكتب بشكل ذري، بالصلاحية 0600؛
• يذكر النموذج ومعرّف جلسة Claude؛
• تنتهي صلاحيته بعد ٣٠ ثانية.

لا يجيب الهوك بـ allow إلا إذا تحقق كل ما يلي:

• العلامة ملف مملوك لك، وليست رابطًا رمزيًا (symlink)؛
• لم تنتهِ صلاحيتها؛
• هي لجلسة aipager نفسها ولمعرّف جلسة Claude نفسه؛
• نموذجها يساوي requested_model أو to_model، دون اعتبار لحالة الأحرف؛
• قيمة source هي command.

ثم يأخذ الهوك العلامة بإعادة تسمية ذرية، فتُستخدم مرة واحدة بالضبط. يقرأ الفحص ملفًا محليًا واحدًا، بلا مقبس وبلا انتظار. ولا يُمرَّر الحدث إلى aipager.

يتجاهل Claude Code 2.1.101 وما بعده أحداث الهوك التي لا يعرفها، فلا تتأثر الإصدارات الأقدم التي لا تعرف PreModelSwitch. تبقى حالة واحدة قد يظهر فيها السؤال: التبديل إلى opusplan أو منه قد يجعل Claude Code يسأل الهوك مرتين، ولا يجد العلامة إلا السؤال الأول، فيسأل Claude Code «Switch model?» في الطرفية.

سطر الحالة#

ليس حدث هوك: يشغّل Claude Code أمر statusLine، وهو aipager-statusline (aipager.dtach.statusline_notify:main)، كلما أعاد رسم سطر الحالة الخاص به. هذا الأمر:

• يكتب JSON الحالة من Claude Code في ‎/tmp/claude-status-<session>.json (يقرؤه الهوك من أجل sl_tokens، ويقرؤه aipager status وaipager)؛
• يرسل إلى aipager رسالة statusline فيها النموذج، ونسبة السياق، والتكلفة، وأعداد التوكنات، والأسطر المضافة والمحذوفة، وهي ما يغذّي بطاقة العمل، و‎/status، وMini App، والتحقق من نجاح تبديل النموذج، وتحذير السياق؛
• يطبع سطر حالة الطرفية: ‎[name] Opus 5.5 | 42% ctx | $1.23.

رسائل aipager الخاصة#

إلى جانب أحداث الهوك، ترسل البرامج المساعدة إلى aipager بضع رسائل خاصة بها عبر المقبس نفسه:

مسار طلب الإذن#

claude              aipager-hook             aipager daemon          Telegram
  |                      |                         |                     |
  | PermissionRequest    |                         |                     |
  |--------------------->| opens a reply socket    |                     |
  |                      |------------------------>| busy card becomes   |
  |                      |                         | the prompt          |
  |                      |                         |-------------------->|
  |                      |                         |   you tap Allow     |
  |                      |                         |<--------------------|
  |                      |   allow (reply socket)  | audit log           |
  |                      |<------------------------|                     |
  |  decision: allow     |                         |                     |
  |<---------------------|                         |                     |
  | tool runs            |                         |                     |

إذا لم تأتِ ضغطة خلال ٢٠ ثانية، لا يطبع الهوك شيئًا ويعرض Claude Code مربع الحوار الخاص به؛ والضغطة اللاحقة تكتب الإجابة في ذلك المربع عبر طرفية الجلسة (dtach -p). في الحالتين تُسجَّل الضغطة في سجل التدقيق وتُنشر تحت البطاقة (✅ jim · مسموح · @alice · Bash: ls -la /tmp).

صفحات ذات صلة#

• البنية: أين يقع مستقبِل الهوك.
• أوامر البوت ← طلبات الإذن: الجانب الظاهر لك.
• نموذج الأمان: ما يغطيه فحص الأمان وما لا يغطيه.