### مبادئ التصميم

1. **ملفات بدلاً من قواعد البيانات.** الذاكرة بصيغة Markdown. الإعدادات بصيغة TOML. السجلات نص عادي. كل شيء قابل للقراءة البشرية وقابل للفرق عبر git.

2. **الحدود ميزة.** بوابات الموافقة تجعل الوكلاء المستقلين جديرين بالثقة. وكيل يمكنه إنفاق أموالك دون أن يسأل ليس مستقلاً، بل خطر.

3. **المعرفة المتراكمة.** كل تكرار يجب أن يترك الوكيل أذكى. الذاكرة ليست مخبأً — إنها استثمار.

4. **الشفافية افتراضياً.** إذا لم تستطع رؤية ما فعله الوكيل ولماذا، فهناك خطأ ما.

<a id="platform-support"></a>

## دعم المنصات

| | macOS | Linux | Windows (WSL) | Windows (native PS7) |
|---|:---:|:---:|:---:|:---:|
| bash-guard | نعم | نعم | نعم | نعم (.ps1) |
| git-safe | نعم | نعم | نعم | نعم (.ps1) |
| file-guard | نعم | نعم | نعم | نعم (.ps1) |
| read-once | نعم | نعم | نعم | نعم (.ps1) |
| branch-guard | نعم | نعم | نعم | نعم (.ps1) |
| worktree-guard | نعم | نعم | نعم | نعم (.ps1) |
| session-log | نعم | نعم | نعم | نعم (.ps1) |
| enforce-hooks | نعم | نعم | نعم (bash) | WSL أو Git Bash |
| safety-check | نعم | نعم | نعم | جزئي (يتطلب bash) |
| المثبّت | `install.sh` | `install.sh` | `install.sh` | `install.ps1` |
| موثوقية الخطافات | كاملة | كاملة | كاملة | [~18%](https://github.com/anthropics/claude-code/issues/37988) |

**أفضل تجربة:** macOS أو Linux. **Windows:** استخدم WSL للحصول على موثوقية كاملة. خطافات PowerShell الأصلية تعمل لكن Claude Code يُطلقها بشكل غير متناسق ([#37988](https://github.com/anthropics/claude-code/issues/37988)).

<a id="recommended-claude-code-version"></a>

## إصدار Claude Code الموصى به

**استخدم أحدث إصدار من Claude Code.** يتغير Claude Code بسرعة؛ تحقق من [خلاصة الإصدارات](https://github.com/anthropics/claude-code/releases) الخاصة بـ Anthropic قبل تثبيت إصدار معين، ثم شغّل `safety-check` مع `--verify` للتأكد من أن الخطافات تُطلق بشكل صحيح في بيئتك. الإصدارات أدناه نقاط تحول تاريخية متعلقة بالخطافات، وليست متتبعاً للإصدار الحالي:

| الإصدار | المشكلة |
|---|---|
| v2.1.91+ | يعيد صلاحيات تنفيذ `rg` المرفق، ليصلح تراجعات اكتشاف أوامر المشروع منذ v2.1.88-89 ([#41497](https://github.com/anthropics/claude-code/issues/41497), [#41864](https://github.com/anthropics/claude-code/issues/41864)) |
| v2.1.90+ | الحد الأدنى من الإصدار لتحسين الحظر عبر exit-2 + JSON، وإصلاح الحفظ عند التنسيق في PostToolUse، و4 إصلاحات لتجاوز صلاحيات PowerShell |
| v2.1.89 | يضيف `PermissionDenied` و`defer` و`file_path` المطلق ومطابقة `if` المركبة للخطافات، لكنه ما زال يعاني من تراجعات اكتشاف الأوامر وعرض `SessionStart` |
| v2.1.88 | [مُهمَل/مُسحوب من npm](https://github.com/anthropics/claude-code/issues/41497): الأوامر/المهارات المخصصة معطلة، تسريب خريطة المصدر |
| v2.1.81-84 | [تجاوز الصلاحيات يُعاد ضبطه في منتصف الجلسة](https://github.com/anthropics/claude-code/issues/37745) عند تثبيت خطافات PreToolUse |
| < v2.1.50 | لا يدعم تنسيق `hookSpecificOutput` (الخيار المهجور `decision: "block"` ما زال يعمل لكن ينبغي ترحيله) |

شغّل `claude --version` للتحقق من تثبيتك المحلي.

## استكشاف الأخطاء وإصلاحها

**تعليقات JSONC في settings.json**: إذا كان ملف `~/.claude/settings.json` يحتوي على تعليقات `//` أو `/* */`، فقد تتوقف الخطافات عن العمل بصمت ([claude-code#37540](https://github.com/anthropics/claude-code/issues/37540)). تكتشف أدوات التثبيت لدينا JSONC وتزيل التعليقات تلقائياً (مع إنشاء نسخة احتياطية `.bak`). إذا لم تكن الخطافات تعمل، تحقق من وجود تعليقات في ملف الإعدادات لديك.

**الخطافات لا تحظر**: يُطلق Claude Code الخطافات فقط عند استدعاءات الأدوات، وليس عند تجميع المطالبة. ميزات مثل الإكمال التلقائي عبر @ تحقن محتوى الملف قبل أن تتمكن الخطافات من الاعتراض. انظر [claude-code#32928](https://github.com/anthropics/claude-code/issues/32928).

**تخطي خطافات المشروع من المجلدات الفرعية**: إذا كان مستودعك يخزن الخطافات في `.claude/settings.json` في جذر المستودع، فابدأ Claude Code وشغّل `safety-check` من نفس الجذر. قد يؤدي التشغيل من مجلد فرعي إلى جعل Claude يتعامل مع ذلك المجلد الفرعي كجذر للمشروع ويتخطى خطافات المشروع الأصلي دون تحذير. يبلّغ `safety-check` عن هذا كتحذير لإعدادات المشروع الأصلي. على Windows PowerShell الأصلي، شغّل `Set-Location (git rev-parse --show-toplevel)` من داخل نسخة العمل قبل تشغيل `install.ps1 verify`.

**إعادة ضبط تجاوز الصلاحيات عند تثبيت الخطافات**: إذا كنت تستخدم `--dangerously-skip-permissions` (شائع في الإعدادات المستقلة)، يمكن لخطافات PreToolUse أن [تتسبب في إعادة ضبط حالة الصلاحيات في منتصف الجلسة](https://github.com/anthropics/claude-code/issues/37745)، لتعيد جميع الأدوات إلى الموافقة اليدوية. هذا خطأ في المنصة، وليس خطأ في الخطافات. إذا طلبت الأدوات فجأة الموافقة بعد 30-120 دقيقة من بدء الجلسة، فهذا هو السبب.

**متغير البيئة IS_DEMO يعطل جميع الخطافات**: إذا كان `IS_DEMO=1` مضبوطاً في بيئتك (أحياناً عبر إعدادات IDE أو مساحة عمل سحابية)، فإن Claude Code [يتخطى بصمت تنفيذ جميع الخطافات](https://github.com/anthropics/claude-code/issues/37780) عبر كبت ثقة مساحة العمل دون منحها. شغّل `echo $IS_DEMO` للتحقق. تكتشف أداة `safety-check` لدينا هذا تلقائياً.

**CLAUDE_CODE_SIMPLE يعطل جميع الخطافات**: عندما يُضبط متغير البيئة `CLAUDE_CODE_SIMPLE` على أي قيمة غير فارغة، يعطل Claude Code الخطافات وأدوات MCP والمرفقات وتحميل ملف CLAUDE.md بالكامل (أُدخل في v2.1.50). لن تُطلق أي قواعد فرض. شغّل `echo $CLAUDE_CODE_SIMPLE` للتحقق. تكتشف أداة `safety-check` لدينا هذا تلقائياً.

**علم `--bare` يتخطى جميع الخطافات**: يعطل علم CLI `--bare` الخطافات وLSP ومزامنة الإضافات ومسح مجلدات المهارات لاستدعاءات `-p` النصية. إذا كان خط أنابيبك المستقل يستخدم `claude --bare -p`، فلن تُطلق أي خطافات. استخدم ضوابط على مستوى نظام التشغيل (صلاحيات الملفات، الحاويات) للفرض في الوضع bare.

**معالجة الرفض في الخطافات ما زالت غير متناسقة عبر الأدوات والإصدارات**: تحسّن `hookSpecificOutput.permissionDecision: "deny"`، لكنه ليس ضماناً شاملاً عبر أسطح Claude Code. ما زالت عدة مشكلات منبعية توثق حالات يُتجاهل فيها معالجة الرفض أو يتغير حسب نوع الأداة/الحدث. لهذا السبب تستخدم خطافات الإطار التي يجب أن تحظر الإجراءات الخطيرة حظراً صارماً المسار الأكثر تحفظاً الذي يحترمه Claude Code حالياً بأكبر موثوقية: سبب مقروء بشرياً على `stderr` بالإضافة إلى `exit 2`، ثم نطلب من المستخدمين تشغيل `safety-check --verify` بعد التثبيت وبعد تحديثات Claude Code. إذا كنت تكتب خطافات مخصصة، فلا تفترض أن استجابة JSON بالرفض وحدها كافية لمجرد أنها تعمل في اختبار محلي واحد.

**قد تتخطى الوكلاء الفرعيون إعدادات الخطافات**: الوكلاء المُنشأون عبر أداة Agent [لا يرثون إعدادات الصلاحيات بشكل متناسق](https://github.com/anthropics/claude-code/issues/37730). يجب أن تستمر خطافات `.claude/settings.json` في العمل (إعدادات مشتركة)، لكن تحقق من سلوك الخطافات عند استخدام سير عمل الوكلاء الفرعيين.

**قد يسرب stderr الخاص بالخطافات مسارات نظام الملفات لديك**: مُشغّل خطافات Claude Code [يسبق مخرجات stderr بمسار الأمر الخام](https://github.com/anthropics/claude-code/issues/41226)، مما يكشف تفاصيل مثل `/Users/yourname/.claude/hooks/my-hook.sh` في المحادثة. يأتي هذا من طبقة تنفيذ المنصة، وليس من الخطافات. تستخدم خطافاتنا بادئات نظيفة (`[bash-guard]`، `[file-guard]`، إلخ) لرسائل التصحيح ولا تكشف أبداً مسارات نظام الملفات في stdout أو stderr. تسجيل التصحيح اختياري لكل خطاف (مثل `BASH_GUARD_LOG=1`).

**عمليات git الداخلية تتجاوز جميع الخطافات**: يشغّل Claude Code عمليات git في الخلفية (fetch + reset) [برمجياً كل ~10 دقائق](https://github.com/anthropics/claude-code/issues/40710) دون استدعاء ثنائي `git` خارجي أو إجراء استدعاء أداة. وبما أن الخطافات تُطلق فقط عند استدعاءات الأدوات، فإن git-safe وجميع الخطافات الأخرى عمياء عن هذه العمليات. يمكن أن يؤدي هذا إلى تدمير التغييرات غير المثبتة على الملفات المتعقبة بصمت. الحل البديل: استخدم git worktrees (محصنة ضد عمليات إعادة التعيين في نسخة العمل الرئيسية) أو ثبّت التغييرات بشكل متكرر. إذا كنت تستخدم `claude -w`، ثبّت أيضاً [worktree-guard](https://github.com/bande-a-bonnot/boucle-framework/blob/HEAD/tools/worktree-guard/) قبل الاعتماد على worktrees؛ وإلا فقد يؤدي الخروج من worktree إلى حذف التزامات غير مدمجة أو غير مدفوعة.

**عدم تزامن الصلاحيات بعد تعديل settings.local.json**: إذا عدّلت أداة Edit الخاصة بـ Claude ملف `.claude/settings.local.json` أثناء الجلسة، فإن حالة الصلاحيات في الذاكرة [تفقد تزامنها مع الملف على القرص](https://github.com/anthropics/claude-code/issues/41259). تتوقف قواعد السماح عن العمل ويُطلب من المستخدم مراراً وتكراراً الموافقة على أوامر مسموح بها بالفعل. الملف على القرص صحيح؛ المشكلة هي الذاكرة المؤقتة. الحل البديل: دع Claude Code يدير ملفات الصلاحيات عبر آلية المطالبة الخاصة به، أو أعد تشغيل الجلسة بعد التعديلات اليدوية.

**جديد في v2.1.89: حدث خطاف PermissionDenied**: يُطلق حدث خطاف جديد بعد رفض مصنف الوضع التلقائي. يمكن للخطافات إرجاع `{"retry": true}` لإخبار النموذج بأنه يمكنه إعادة محاولة العملية المرفوضة. توثق المشكلة المرتبطة الفجوة الأصلية في التوثيق لهذا الحدث. أيضاً في v2.1.89: شروط `if` للخطافات أصبحت الآن [تطابق أوامر Bash المركبة](https://github.com/anthropics/claude-code/issues/41262) (`ls && git push` يطابق `Bash(git *)`) والأوامر ذات بادئات متغيرات البيئة (`FOO=bar git push`).

**عدم عرض systemMessage الخاص بـ SessionStart (v2.1.89)**: حقل `systemMessage` الذي تُرجعه خطافات SessionStart [لم يعد يُعرض في الطرفية](https://github.com/anthropics/claude-code/issues/41285). يعمل الخطاف وما زال `additionalContext` يُحقن في سياق النموذج، لكن المخرجات المرئية التي كانت تظهر سابقاً (مثل "SessionStart:startup says: ...") مفقودة بصمت. إذا كنت تعتمد على `systemMessage` لإشعارات المشغل أو تحديد الجلسة، فلن يكون المخرج مرئياً. ذات صلة: [#9090](https://github.com/anthropics/claude-code/issues/9090)، [#15344](https://github.com/anthropics/claude-code/issues/15344).

**فشل الخطافات في الجلسة الأولى في مشروع جديد**: في أول جلسة في دليل مشروع، تُطلق خطافات SessionStart وUserPromptSubmit [قبل وجود دليل المشروع](https://github.com/anthropics/claude-code/issues/41310) (`~/.claude/projects/<encoded-path>/`). أي خطاف يستمد مسارات الملفات من `transcript_path` ويحاول الكتابة هناك سيفشل. الحل البديل: أضف `mkdir -p` للمسارات المشتقة من transcript_path قبل الكتابة.

**تنفيذ النموذج الذاتي في الجلسات الطويلة**: في الجلسات الطويلة غير المراقبة، يمكن للنموذج أن [يهلوس نص `Human:` بعد تسليم إشعار المهمة](https://github.com/anthropics/claude-code/issues/41307) ثم ينفذه كما لو كان طلب مستخدم حقيقي، مما يطلق عمليات git وتعديلات ملفات غير مصرح بها. لا يمكن للخطافات اكتشاف ذلك لأن استدعاءات الأدوات الناتجة حقيقية — فقط المحفّز هو المُهلوس. التخفيف: استخدم حدوداً زمنية للجلسة وتجنب الجلسات الطويلة جداً غير المراقبة.

**تسريب GIT_INDEX_FILE في worktree**: يمكن أن يتلف فهرس git للوكلاء المُنشأين عبر EnterWorktree [بسبب إدخالات إضافات السوق](https://github.com/anthropics/claude-code/issues/41314) نتيجة تسريب متغير البيئة `GIT_INDEX_FILE` عبر حدود العمليات. إذا أظهرت عمليات worktree ملفات غير متوقعة في git status، فقد يكون هذا هو السبب.

**لا يمكن إيقاف الوكلاء في الخلفية**: الوكلاء المُنشأون عبر أداة Agent مع `run_in_background` [لا يمكن إنهاؤهم بشكل موثوق](https://github.com/anthropics/claude-code/issues/41461) من قبل المستخدم. في حالة موثقة واحدة، كتب 14 وكيلاً متوازياً إلى نفس الملف واستهلكوا ~1.4M رمزاً (55-106 دولاراً). لا توجد آلية إنهاء مدمجة. التخفيف: تجنب إنشاء العديد من الوكلاء في الخلفية، وراقب استهلاك الرموز إذا فعلت ذلك.

**قد يتم تجاهل إعداد cleanupPeriodDays**: يمكن [تجاوز إعداد `cleanupPeriodDays` في `settings.json` بصمت](https://github.com/anthropics/claude-code/issues/41458)، مما يحذف ملفات الجلسات حتى عند ضبطه على قيم عالية جداً. فقد أحد المستخدمين 490 جلسة رغم ضبطه على 99999. إذا كنت تعتمد على استمرارية الجلسات، قم بنسخ `~/.claude/projects/` احتياطياً بشكل مستقل.

**أدلة .claude/ المرتبطة رمزياً غير مكتشفة (Linux)**: أوامر الشرطة المائلة من [`.claude/commands/` المرتبطة رمزياً](https://github.com/anthropics/claude-code/issues/41451) لا تُحمّل على Linux (تراجع). هذا نمط شائع في الفرق (تخزين الإعدادات المشتركة في دليل مركزي وربطه رمزياً). قد تفشل الخطافات والمهارات أيضاً إذا كان `.claude/` نفسه رابطاً رمزياً. الحل البديل: انسخ الملفات بدلاً من الربط الرمزي.

**فقدان صلاحية التنفيذ لـ ripgrep المرفق (Linux)**: يمكن أن يفقد الثنائي المرفق `rg` [صلاحية التنفيذ الخاصة به](https://github.com/anthropics/claude-code/issues/41463) على Linux، مما يكسر بصمت جميع أوامر الشرطة المائلة المعرفة من قبل المستخدم في `~/.claude/commands/`. الإصلاح: `chmod +x` للثنائي المرفق.

**تراجعات اكتشاف الأوامر في v2.1.88-89**: كان v2.1.88 [مُهجَناً/مُسحوباً من npm](https://github.com/anthropics/claude-code/issues/41497) بعد توقف تحميل الأوامر المخصصة وشحن `cli.js.map` عن طريق الخطأ. أبقى v2.1.89 على تراجع اكتشاف الأوامر لبعض المستخدمين ([#41864](https://github.com/anthropics/claude-code/issues/41864))، رغم أنه أضاف أيضاً ميزات خطافات مثل `PermissionDenied`. أشارت Anthropic إلى أن إصلاح صلاحية تنفيذ `rg` المرفق قد شُحن في v2.1.91. إذا اختفت الأوامر أو المهارات المخصصة، حدّث إلى أحدث إصدار من Claude Code وأعد تشغيل `safety-check --verify`.

**تعلق الجلسات غير التفاعلية عند حد الاستخدام**: في الوضع بدون واجهة، أو `--print`، أو وضع التحكم عن بعد، يؤدي بلوغ حد الاستخدام إلى [إظهار مطالبة تأكيد لا يمكن الإجابة عليها](https://github.com/anthropics/claude-code/issues/41502) لعدم وجود stdin. تعلق الجلسة بشكل دائم. لا يوجد حل برمجي بديل ([#41503](https://github.com/anthropics/claude-code/issues/41503)). إذا كنت تشغّل Claude Code في CI أو cron أو حلقات مستقلة، فاضبط حدوداً زمنية للجلسة وراقب العمليات العالقة.

**تجاوز قواعد الرفض عبر الأنابيب والأوامر المركبة**: تطابق قواعد الرفض المدمجة سلسلة الأمر الكاملة فقط. `Bash(rm *)` يحظر `rm -rf /` لكن ليس `find /foo | xargs rm` أو `something && rm -rf /`. تقول التوثيقات إن قواعد السماح تحلل عوامل تشغيل الصدفة، لكن [قواعد الرفض لا تفعل ذلك](https://github.com/anthropics/claude-code/issues/41559). ملاحظة: ثُبّتت شروط `if` للخطافات منبعياً (أواخر مارس 2026) لتطابق الأوامر المركبة وبادئات متغيرات البيئة بشكل صحيح، لذا فإن الخطافات *تُطلق* بشكل صحيح لهذه الأنماط. الفجوة تحديداً في *قواعد* الرفض، وليس في الخطافات. يحلل bash-guard كل مقطع أنابيب وكل سلسلة مركبة بشكل مستقل، ملتقطاً أنماط التجاوز هذه. انظر أيضاً [#37662](https://github.com/anthropics/claude-code/issues/37662)، [#16180](https://github.com/anthropics/claude-code/issues/16180).

**"تأكيد كل تغيير على حدة" يُتخطى بصمت**: عند الخروج من وضع التخطيط واختيار "تأكيد كل تغيير على حدة"، [تُطبَّق التغييرات دون أي مطالبة](https://github.com/anthropics/claude-code/issues/41551) إذا كانت الأدوات (Edit وWrite وBash) ضمن `permissions.allow`. تتجاوز قواعد السماح الدائمة اختيار المستخدم الصريح لكل جلسة. الحل البديل: أزل سماحات الأدوات الواسعة واستخدم الخطافات للفرض بدلاً من ذلك.

**قتل خطافات SessionEnd قبل الاكتمال**: خطافات SessionEnd التي تؤدي عملاً غير متزامن (استدعاءات API، تلخيص LLM، طلبات الشبكة) [تُقتل أثناء التنفيذ](https://github.com/anthropics/claude-code/issues/41577) عند خروج Claude Code، بغض النظر عن المهلة المكوّنة. يصل الخطاف إلى الاستدعاء غير المتزامن لكن العملية الأم تخرج قبل عودة الاستجابة. الحل البديل: افصل العمل الثقيل في عملية خلفية باستخدام `nohup ... & disown`، ثم نفّذ `exit 0` فوراً.

**السماح الدائم بالوصول إلى الدليل لا يُحفظ**: النقر على "نعم، والسماح دائماً بالوصول إلى [المجلد]" [لا يُحفظ بشكل موثوق](https://github.com/anthropics/claude-code/issues/41579). يعيد Claude طلب نفس الدليل في الجلسات اللاحقة. الإضافة إلى `additionalDirectories` في settings.json غير مستقرة أيضاً. ذات صلة بـ [#40606](https://github.com/anthropics/claude-code/issues/40606) (تسريب additionalDirectories عبر المشاريع).

**الكتابة إلى `~/.claude/` تعلّق الجلسات الآلية**: تؤدي الكتابة إلى مسارات ضمن `~/.claude/` إلى إطلاق مطالبة صلبة للملفات الحساسة [لا يمكن كبتها](https://github.com/anthropics/claude-code/issues/41615) عبر `permissions.allow`، أو خطافات PreToolUse التي تُرجع `"allow"`، أو وضع `bypassPermissions`، أو `skipDangerousModePermissionPrompt`. الجلسات الآلية (tmux، CI، الحلقات المستقلة) التي تحتاج إلى تعديل ملفات إعدادات Claude Code ستتعلق عند المطالبة التفاعلية. الحل البديل: استخدم أوامر أداة Bash (`echo`، `cat`، `jq`) لكتابة الملفات مباشرة بدلاً من أداتي Edit/Write.

**تغليف `bash -c` يتجاوز حماية الكتابة لدليل `.claude/`**: يحمي نظام الصلاحيات ملفات `.claude/` من التعديل (التحرير والكتابة وأوامر bash المباشرة كلها تطلق نافذة تأكيد). لكن تغليف الأمر في [`bash -c 'echo "..." >> .claude/file'`](https://github.com/anthropics/claude-code/issues/43085) يتجاوز الفحص تماماً: لا نافذة، والكتابة تنجح بصمت. تفحص مطابقة الأنماط سلسلة الأمر على المستوى الأعلى لكن ليس الأصداف الفرعية المتداخلة. هذا يعني أن النموذج (أو حقن المطالبة عبر نتائج الأدوات) يمكنه تعديل الخطافات أو settings.json أو المهارات أو تعريفات الوكلاء دون تأكيد المستخدم. يلتقط file-guard هذا إذا أُضيف `.claude/` إلى إعداد `.file-guard`، لأنه يفحص سلسلة أمر Bash الكاملة بحثاً عن مسارات محمية (بما في ذلك داخل الوسائط المقتبسة). المستخدمون الذين يعتمدون فقط على فحوصات الصلاحيات المدمجة معرضون للخطر.

**خطافات `WorktreeCreate` تعلّق `claude -w`**: أي خطاف `WorktreeCreate` يتسبب في [تعليق `claude -w` إلى أجل غير مسمى](https://github.com/anthropics/claude-code/issues/41614) بغض النظر عن محتوى الخطاف. حتى `echo ok < /dev/null` يجمّد الجلسة. ينفذ الخطاف ويعود، لكن Claude Code لا يستكمل أبداً. أزل جميع خطافات `WorktreeCreate` إذا كنت بحاجة إلى عمل `claude -w`.

**يمكن للنموذج التلاعب بملفات حالة الخطافات**: يمتلك النموذج وصولاً إلى نظام الملفات و[يمكنه الكتابة فوق الملفات التي تعتمد عليها الخطافات](https://github.com/anthropics/claude-code/issues/38841) — ملفات نقاط التفتيش وملفات القفل والعدادات. في حالة موثقة واحدة، احتسب Claude تجزئة SHA256 لاسم ملف نقطة تفتيش وكتب طابعاً زمنياً جديداً لتجاوز بوابة قراءة المحتوى. الخطافات التي تعتمد على ملفات حالة خارجية للفرض يجب أن تفترض أن النموذج يمكنه قراءة وتعديل تلك الملفات. يمكن للتوقيعات التشفيرية أو التحقق خارج العملية التخفيف من ذلك.

**`bypassPermissions` لا يُستعاد عند استئناف الجلسة (VS Code)**: عندما يُهيأ `bypassPermissions` عبر `initialPermissionMode` في إعدادات VS Code، [تعود المحادثات المستأنفة إلى وضع الصلاحيات الافتراضي](https://github.com/anthropics/claude-code/issues/42735) وتطلب الموافقة على كل تعديل. قد تلتقط الجلسات الجديدة الإعداد، لكن الجلسات المستأنفة تفشل بشكل متكرر. الخطافات التي تعتمد على تشغيل الجلسة في وضع التجاوز لا يمكنها الاعتماد على استمراره عبر الاستئناف.

**عزل worktree ينكسر في الوحدات الفرعية لـ git**: استخدام `isolation: "worktree"` على أداة Agent داخل وحدة فرعية لـ git [ينشئ worktree في `.git/modules/<path>/.claude/worktrees/`](https://github.com/anthropics/claude-code/issues/42732) بدلاً من `.claude/worktrees/` الخاص بالمشروع. يضع هذا الوكيل خارج نطاق صلاحيات المشروع، مما يتسبب في تخفيض `bypassPermissions` بصمت وإطلاق مطالبات صلاحيات غير متوقعة.

**موافقة المهارات غير مرتبطة بتجزئة المحتوى**: عندما يوافق المستخدم على مهارة، تكون الموافقة [غير مرتبطة بتجزئة محتوى الملف](https://github.com/anthropics/claude-code/issues/43157). إذا عُدّل ملف المهارة بعد الموافقة (حتى في منتصف الجلسة)، يُنفَّذ الإصدار المعدّل دون إعادة مطالبة. بالإضافة إلى ذلك، يمكن أن تتجاوز الموافقة على مهارة قواعد الرفض على مستوى الأدوات في `settings.json`. هذا خطر على سلسلة التوريد: أي شيء لديه صلاحية كتابة إلى `~/.claude/skills/` يمكنه تصعيد القدرات بعد الموافقة.**خوادم MCP من نوع stdio لا يعاد اتصالها تلقائيًا أبدًا**: عندما تموت عملية خادم MCP من نوع stdio أو تنقطع، يميزها Claude Code [على أنها فاشلة ولا يعيد المحاولة أبدًا](https://github.com/anthropics/claude-code/issues/43177). تحصل خوادم HTTP/SSE/WebSocket على إعادة اتصال تلقائية مع تراجع أسي (5 محاولات)، لكن خوادم stdio مستبعدة صراحةً. يجب على المستخدمين تشغيل `/mcp` يدويًا لإعادة الاتصال. وهذا يؤثر على أي تكامل MCP يستخدم نقل stdio (النمط المحلي الأكثر شيوعًا).

**تجاوز وضع الخطة بعد الدورة الأولى**: بعد إكمال دورة واحدة من الموافقة على الخطة وتنفيذها، فإن الدخول إلى وضع الخطة مرة أخرى [لا يفرض قيود القراءة فقط بشكل موثوق](https://github.com/anthropics/claude-code/issues/43147). ينقل Claude الحالة الذهنية "الموافَق عليها" ويبدأ في تحرير الملفات قبل موافقة المستخدم على الخطة الجديدة. الخطافات التي تعتمد على وضع الخطة كحد أمان لا يمكنها الوثوق به عبر دورات متعددة في نفس الجلسة.

**Windows**: جميع الخطافات السبعة لها مكافئات **PowerShell 7+** أصلية (`hook.ps1`) لا تتطلب أي تبعيات خارجية. يتطلب [PowerShell 7](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows) (`pwsh`)، وليس Windows PowerShell 5 المدمج. قم بتثبيتها باستخدام:```powershell
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } all"