Notification hook في Claude Code: متى يُطلَق وكيف تستخدمه

01أنواع الإشعارات

الـ matcher في hook من نوع Notification هو نوع الإشعار. اتركه فارغًا ليعمل مع جميع الأنواع، أو اذكر الأنواع التي تريدها مفصولة بـ |. الأنواع التي ستستخدمها على الأرجح:

هناك أنواع أخرى، مثل agent_needs_input وagent_completed للجلسات الخلفية في عرض الوكلاء، ومجموعة من أنواع quota_auto_resume_* لفترات انتظار حدود الاستخدام. تجد القائمة الكاملة والمحدّثة في مرجع الـ hooks.

02قواعد التوقيت

هذا هو الجزء الذي يُربك كثيرين. يشترك hook Notification في توقيته مع إشعارات سطح المكتب الخاصة بـ Claude Code، لذا لا يعمل في جلسة الـ terminal إلا حين تنصرف عن الشاشة:

• permission_prompt يبدأ مؤقتًا مدته ست ثوانٍ تقريبًا عند ظهور الـ prompt، وتعيد كل ضغطة مفتاح ضبطه. إذا أجبت بسرعة فلن يعمل أبدًا.
• idle_prompt يعمل بعد نحو 60 ثانية من انتهاء Claude، بشرط ألا تكون قد كتبت شيئًا منذ ذلك الحين وألا يكون هناك agent يعمل في الخلفية. ولا يعمل أثناء انتظار Claude Code لإعادة ضبط حد الاستخدام.
• الطلب الذي يصل أثناء فتح نافذة حوار أخرى يُحسب توقيته من لحظة وصوله، لذا قد يصلك إشعاره وهو لا يزال ينتظر خلف النافذة المفتوحة.

البيئات المضيفة التي تجيب على الأذونات عبر Agent SDK، مثل Claude Desktop وإضافة VS Code، تحسب توقيت permission_prompt بطريقة مختلفة: بعد نحو ست ثوانٍ من الطلب، دون تأجيل بسبب الكتابة، ويُتخطى إذا أجبت أنت أو أجاب hook PermissionRequest أولًا.

إذا أردت إشارة فورية بلا تأخير، فاستخدم حدثًا آخر:

03ما يتلقاه الـ hook

إضافةً إلى الحقول المشتركة (session_id وtranscript_path وcwd وhook_event_name)، يتلقى hook Notification نص الإشعار في message، وtitle اختياريًا، وnotification_type:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Notification",
  "message": "Claude needs your permission",
  "title": "Permission needed",
  "notification_type": "permission_prompt"
}

الحقل message بصياغة Claude Code نفسه، لذا يمكن عرضه كما هو بأمان. ويفيد cwd حين تشغّل عدة جلسات وتريد معرفة المشروع الذي يطلب.

04ما يستطيع الـ hook فعله وما لا يستطيع

لا يستطيع hook Notification منع الإشعار أو تأخيره أو تغييره. يُتجاهل رمز الخروج وstderr، ويُهمل Claude Code الحقلين systemMessage وcontinue من مخرجات JSON. فهو مخصص للتأثيرات الجانبية فقط.

هناك حقل إخراج واحد يمكنه استخدامه: terminalSequence. تعمل الـ hooks دون terminal، فلا يمكنها كتابة escape sequences بنفسها، لكن يمكنها تمرير واحدة إلى Claude Code ليُصدرها. يتيح ذلك للـ hook إطلاق إشعار أصلي من الـ terminal في iTerm2 وGhostty وKitty وWezTerm وWindows Terminal وغيرها، حتى داخل tmux. ولا يعمل إلا في جلسة تفاعلية تكون فيها واجهة Claude Code ظاهرة على الشاشة.

ولا يوقف الإعداد preferredNotifChannel الـ hook أيضًا. فحتى مع تعطيل الإشعارات المدمجة، يظل حدث Notification يعمل. هذا الإعداد يغيّر فقط طريقة تنبيه Claude Code لك؛ راجع دليل جرس الـ terminal.

05أمثلة

معالجات مختلفة لكل نوع

شغّل سكربتًا منفصلًا لطلبات الإذن وآخر لتذكيرات الخمول:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/permission-alert.sh" }]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/idle-alert.sh" }]
      }
    ]
  }
}

اجعل كل سكربت قابلًا للتنفيذ باستخدام chmod +x. أوامر إشعارات سطح المكتب لأنظمة Mac وWindows وLinux موجودة في كيف تتلقى إشعارًا عند انتهاء Claude Code، لذا لن نكررها هنا.

عرض الرسالة الفعلية والمشروع

يضع هذا السكربت (macOS وLinux) رسالة Claude Code ومجلد المشروع في الإشعار بدلًا من نص ثابت:

#!/bin/bash
# ~/.claude/hooks/notify.sh
input=$(cat)
msg=$(jq -r '.message // "Claude Code needs your attention"' <<<"$input")
project=$(basename "$(jq -r '.cwd // "."' <<<"$input")")

if command -v osascript >/dev/null 2>&1; then
  osascript -e 'on run argv' \
            -e 'display notification (item 1 of argv) with title (item 2 of argv)' \
            -e 'end run' "$msg" "Claude Code: $project"
elif command -v notify-send >/dev/null 2>&1; then
  notify-send "Claude Code: $project" "$msg"
fi
exit 0

تمرير النص كوسائط (on run argv) يمنع تعطل AppleScript عندما تحتوي الرسالة على علامات اقتباس. ويتطلب تثبيت jq.

إشعار أصلي من الـ terminal

يستخدم مثال Anthropic نفسها terminalSequence مع OSC 777، الذي تفهمه Ghostty وWarp وurxvt:

#!/bin/bash
input=$(cat)
title="Claude Code"
body=$(jq -r '.message // "Needs your attention"' <<<"$input")
seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

أما في iTerm2 أو Windows Terminal أو WezTerm فاستخدم OSC 9، وفي Kitty استخدم OSC 99. يُتجاهل أي شيء خارج التسلسلات المسموح بها.

06أين يأتي دور Claude Code Notifier

hook Notification يستدعي خدمة push يوصل التنبيه إلى هاتفك، وهذا يكفي كثيرين. يشرح دليل ntfy هذه الطريقة.

الثغرة هي الرد. فحين يعمل permission_prompt، يكون Claude منتظرًا نافذة حوار لا يستطيع hook Notification الإجابة عليها. يتعامل Claude Code Notifier مع ذلك عبر الـ hooks القادرة على ذلك: PermissionRequest لإعادة قرارك، وPreToolUse على AskUserQuestion لإعادة إجابتك. أداة سطر الأوامر المجانية الخاصة به، ccn، تعمل على Mac وWindows وLinux وتعرض إشعارات سطح المكتب بمفردها. وبعد ربط تطبيق iPhone أو Android، يمكنك السماح مرة واحدة أو السماح طوال الجلسة أو الرفض من الهاتف. وإذا كتبت شيئًا خلال آخر 30 ثانية، فلا شيء ينتظر الهاتف ويسألك الـ terminal كالمعتاد. الأداة مستقلة وليست من صنع Anthropic. تجد طريقة التثبيت في صفحة ccn.

07الأسئلة الشائعة