الخطّافات
معالِجات أحداث الأدوات التي تنطلق عند SessionStart وPreToolUse وStop، وتُحمِّل سياقات الرسائل التي تفرض عزل git وانضباط الخطط.
تنطلق الخطّافات عند أحداث الأدوات وتُحمِّل سياقات رسائل يعاملها المساعِد بوصفها
مُوجِّهات نظام إضافيّة. يعيش التوصيل في كتلة خطّافات settings.json
الخاصّة بـ Claude Code، وملف خطّافات hooks.json الخاصّ بـ
Codex، وخريطة خطّافات settings.json الخاصّة بـ
Qwen Code.
| الحدث | المُهلة | الغرض |
|---|---|---|
| SessionStart | 30 ثانية | قراءة الذاكرة، فحص حالة الخطّة، الإبلاغ عن الجاهزيّة |
| PreCompact | 30 ثانية | التحقّق من أنّ الحالة قد أُخرِجت خارجيًّا قبل الضغط |
| PostCompact | 30 ثانية | استعادة حالة العمل بعد الضغط |
| Stop | 60 ثانية | الإخراج الخارجيّ عند انتهاء الجلسة |
| PreToolUse (Bash) | 10 ثوانٍ | التحقّق من Bash — عزل مُخرَجات git |
| PreToolUse (Write/Edit/NotebookEdit/apply_patch) | 10 ثوانٍ | عزل مراجع الخطط، فحوص frontmatter |
المُوزِّع
تستدعي مدخلات الخطّافات المثبَّتة المُوزِّع عبر مسار السكربت المطلق. تحمل قوالب
الإعدادات الرمز ${HARNESS_ROOT} —
python "${HARNESS_ROOT}/apothem/hooks/dispatch.py" <event> [<message-name>]
— الذي يرسمه المُثبِّت إلى المسار الحقيقيّ لجذر الـ harness وقت التثبيت
(يُجسِّد Claude Code وQwen Code المُوزِّع تحت
<harness-root>/apothem/hooks/؛ وCodex تحت
<harness-root>/hooks/). المُوزِّع سكربت مستقلّ من المكتبة القياسيّة:
فهو يُمهِّد sys.path الخاصّ به، فلا حاجة إلى حزمة apothem
قابلة للاستيراد على المضيف. من سحب مصدريّ، يُشغِّل الشكل الوحدويّ
python -m apothem.hooks.dispatch <event> (مع PYTHONPATH=src)
الشيفرة نفسها للتطوير. يُحمِّل المُوزِّع hooks/lib/resolve_root.py لحلّ
جذر المنظومة، ويفوِّض إلى hooks/emit_hook_context.py و
hooks/session_start_bootstrap.py.
سياقات الرسائل
تعيش سياقات Markdown لكلّ حدث تحت src/apothem/hooks/messages/:
postcompact.md،precompact.md،stop.mdpretooluse-bash.md،pretooluse-write.md،pretooluse-edit.md،pretooluse-notebookedit.md
يُحمِّل المُوزِّع كلّ ملفّ سياق عندما ينطلق حدثه وتكون وسيطة سياقه مُسجَّلة في ملفّ الإعدادات.
جرد رسائل الخطّافات المُولَّد
| Name | Description | Source |
|---|---|---|
postcompact | Post-compaction Blind Bootstrap (CM-24 §6.2). Restore working state from durable files; conversation context is now compressed. | src/apothem/hooks/messages/postcompact.md |
posttooluse-proactive-compaction | Proactive-compaction tracker for PostToolUse tool calls. | src/apothem/hooks/messages/posttooluse-proactive-compaction.md |
precompact | Pre-compaction protocol (CM-24 §2.3). Externalize all in-conversation state BEFORE the harness compresses context. | src/apothem/hooks/messages/precompact.md |
pretooluse-askuserquestion-recommended | Call-time (Recommended)-marker guard for AskUserQuestion tool calls. | src/apothem/hooks/messages/pretooluse-askuserquestion-recommended.md |
pretooluse-bash-plan-guard | Plans-Discipline write guard for Bash tool calls (companion to pretooluse-write-plan-guard.md). | src/apothem/hooks/messages/pretooluse-bash-plan-guard.md |
pretooluse-bash | CM-7 git-artifact isolation + M12 numeric-prefix discipline + M15 human-only authorship. | src/apothem/hooks/messages/pretooluse-bash.md |
pretooluse-conformity | > Advisory: this hook reports; it does not block. Mechanical enforcement runs in CI. | src/apothem/hooks/messages/pretooluse-conformity.md |
pretooluse-dependency-guard | Dependency-manifest supply-chain guard (advisory). | src/apothem/hooks/messages/pretooluse-dependency-guard.md |
pretooluse-edit-header-guard | SPDX-header inject guard for Edit tool calls. | src/apothem/hooks/messages/pretooluse-edit-header-guard.md |
pretooluse-edit | Codebase isolation (Edit scope). | src/apothem/hooks/messages/pretooluse-edit.md |
pretooluse-eval-guard | Dynamic-eval / unsafe-deserialization guard — advisory prompt-injection defense. | src/apothem/hooks/messages/pretooluse-eval-guard.md |
pretooluse-notebookedit | Codebase isolation (notebook scope). | src/apothem/hooks/messages/pretooluse-notebookedit.md |
pretooluse-write-header-guard | SPDX-header inject guard for Write tool calls. | src/apothem/hooks/messages/pretooluse-write-header-guard.md |
pretooluse-write-plan-guard | Plans-Discipline write guard for Write / Edit / NotebookEdit tool calls. | src/apothem/hooks/messages/pretooluse-write-plan-guard.md |
pretooluse-write | Codebase isolation + frontmatter compliance. | src/apothem/hooks/messages/pretooluse-write.md |
sessionstart | Session-start conformity posture. | src/apothem/hooks/messages/sessionstart.md |
stop | Session-end protocol (CM-14 + CM-24 §2.5 + CM-26 + CM-22 §2/§4). | src/apothem/hooks/messages/stop.md |