تحديث Claude Code مدخلات Hooks: 2.1.300 تم اختبار التغيير

لقد قام Claude Code 2.1.300 بتغيير كيفية تعامله مع updatedInput، وهو الحقل الذي يستخدمه هوك (hook) من نوع PreToolUse لإعادة كتابة استدعاء الأداة. يذكر سجل التغييرات أنه "يتم التحقق من صحته الآن مثل مدخلات Claude نفسها: يتم إسقاط المفاتيح غير المعروفة، والمدخلات التي ترفضها الأداة تؤدي إلى رفض الاستدعاء".^١

لقد قمت بتشغيل نفس الهوكات على الإصدارين 2.1.299 و 2.1.300، والحالات الرئيسية مرة أخرى على 2.1.306، لمعرفة ما الذي تغير عملياً. جزء من ذلك قد تغير بالفعل، بينما كان جزء مما تشير إليه تلك الجملة صحيحاً بالفعل في الإصدار 2.1.299.

ما ستتعلمه

• ماذا يفعل updatedInput وأين يوضع في JSON الخاص بالهوك
• كيف قمت باختباره، وعلى أي إصدارات
• السلوكيات التي تغيرت في 2.1.300 والتي لم تتغير
• هوك إعادة كتابة يعمل على جميع الإصدارات الثلاثة
• قائمة مراجعة قصيرة للهوكات التي تعيد كتابة استدعاءات الأدوات

ماذا يفعل updatedInput

يختصر مرجع الهوكات الأمر في سطر واحد: updatedInput "مباشرة تحت hookSpecificOutput يستبدل وسائط الأداة قبل تشغيلها."^٢

الكلمة المهمة هنا هي "يستبدل". تم تقديم مشكلة GitHub في فبراير ٢٠٢٦ لأن المُبلغ وجد أنه "يستبدل كائن tool_input بالكامل" بدلاً من الدمج.^٣ يتفق اختباري مع هذا التفسير. فإعادة كتابة Write تحتوي على file_path ولكن بدون content تم رفضها في كل إصدار.

كما أن مكان الوضع يسبب ارتباكاً للبعض. في تقرير من سبتمبر ٢٠٢٦ كتبه mer.vin، تم اختبار 2.1.282 ووجد أن updatedInput الموضوع في المستوى الأعلى من JSON، بجانب hookSpecificOutput، قد تم تجاهله.^٤ لقد تحققت من ذلك باستدعاء Bash على ثلاثة إصدارات وحصلت على نفس النتيجة، وهو ما سأغطيه أدناه.

لسلوكيات الهوك ذات الصلة، راجع اختباراتنا لـ كتلة onFailure و دليل تعديلات Claude Code.

كيف قمت باختباره

لقد قمت بتثبيت كل إصدار من npm في مجلد خاص به: 2.1.299 و 2.1.300 و 2.1.306. تم نشر الإصدارين الأقدمين في ١٤ أكتوبر ٢٠٢٦، والإصدار 2.1.306 في ٢١ أكتوبر ٢٠٢٦، عندما كانت علامة latest تشير إليه.^٥

المجموعة الأولى (إعادة كتابة صالحة، أنواع خاطئة، كائن فارغ، مهلة زمنية و run_in_background) تم تشغيلها في ١٥ أكتوبر ٢٠٢٦ من نفس تثبيتات npm للإصدارين 2.1.299 و 2.1.300. كما تم تشغيل فحص Read empty-object في ١٥ أكتوبر أيضاً، ضمن مجموعة ثانية مبكرة. أما كل عملية تشغيل أخرى ذكرتها هنا فقد كانت في ٢١ أكتوبر ٢٠٢٦، على نظام Linux x86_64 باستخدام Node.js 22.22.0.

كانت كل عملية تشغيل عبارة عن استدعاء claude -p حقيقي باستخدام النموذج claude-sonnet-5-5. لقد مررت --settings تشير إلى ملف اختبار، و --setting-sources "" لاستبعاد الإعدادات الأخرى، و --max-turns 4، وتم ضبط --allowedTools على الأداة الخاضعة للاختبار (Read و Edit معاً في حالات Edit).

هذا العلم (flag) يمنح موافقة مسبقة على الأدوات ولكنه لا يزيل الأدوات الأخرى، لذا قام النموذج أحياناً باستدعاء Bash أيضاً. طلب الأمر إجراءً واحداً بسيطاً: touch لملف علامة لـ Bash، أو قراءة ملف صغير واحد، أو كتابة واحد، أو قراءة ملف ثم تعديله.

كان لكل اختبار خطاف PreToolUse يعيد الـ updatedInput الخاضع للاختبار. وفي معظم عمليات التشغيل، قام خطاف PostToolUse أيضاً بكتابة الـ tool_input الذي استلمه في سجل (log)، حتى أتمكن من رؤية ما استلمته الأداة فعلياً.

يغطي ذلك حالات المفتاح غير المعروف (unknown-key)، والمسار النسبي (relative-path)، وحالات المستوى الأعلى (top-level)، وحالات Edit التي تم فيها الاستدعاء بنجاح. أما الاستدعاء المرفوض فلا يصل أبداً إلى الأداة، لذا لا يوجد له إدخال في PostToolUse.

المجموعة الأولى (إعادة كتابة صالحة، أنواع خاطئة، كائن فارغ، مهلة زمنية، run_in_background) وعمليات تشغيل خطاف إعادة التوجيه لم يكن لها مثل هذا السجل. بالنسبة لهذه الحالات، ولكل استدعاء مرفوض، قمت بفحص ملفات العلامات، والملف الناتج، ونص tool_result في التدفق (stream). وحيثما يشير الجدول إلى ٣ عمليات تشغيل، فقد كانت النتائج الثلاث متطابقة.

النتائج في لمحة سريعة

كل صف يجمع قيم إرجاع الخطافات ذات الصلة. توضح الأعمدة ما حدث في الإصدارين 2.1.299 و 2.1.300، بناءً على مخرجات التشغيل الخام. الجدول أدناه يفصل الحالات ويعطي أعداد عمليات التشغيل.

في الحالات التي قمت فيها بتشغيل 2.1.306، تطابقت النتائج مع 2.1.300 في كل حالة. وهذا يغطي المفاتيح غير المعروفة في جميع الأدوات الأربعة، والمسار النسبي، وجميع حالات رفض Edit الثلاث، وإزاحة Read، والوضع في المستوى الأعلى، وكلا الـ hooks الخاصة بإعادة التوجيه.

المفاتيح غير المعروفة: تم الاحتفاظ بها في 2.1.299، وتم إسقاطها في 2.1.300

هذا هو التغيير الذي يصفه سجل التغييرات (changelog)، وقد تمكنت من ملاحظته.

في الإصدار 2.1.299، احتوى سجل PostToolUse لحالة Bash على bogus_key و another. أما في الإصدارين 2.1.300 و 2.1.306، فقد احتوى فقط على command. وتصرفت أدوات Read و Write و Edit بنفس الطريقة، في الإصدار 2.1.306 أيضاً.

في جميع حالاتي، لم يغير المفتاح الإضافي من سلوك الأداة؛ فقد تجاهلته الأدوات. بالنسبة لهذه الأدوات الأربعة، لم يعد بإمكان الـ hook تمرير مفاتيح غير معروفة إلى استدعاء الأداة.

قراءتنا للموقف: بالنسبة لـ hook يقوم ببناء مخرجاته من قالب أو من نص مرئي للموديل، فإن هذا يمثل مكسباً أمنياً بسيطاً. ولكنه لا يغني عن فحص الحقول التي تقوم بتعيينها بالفعل.

أظهرت حالة Edit تأثيراً ثانياً. في الإصدارين 2.1.300 و 2.1.306، تضمنت المدخلات المسجلة أيضاً replace_all: false. أما في الإصدار 2.1.299، فقد كان هذا الحقل غائباً. لم أختبر ما إذا كان هذا الإعداد الافتراضي هو الذي يفسر نتيجة المطابقة المزدوجة أدناه.

إعادة الكتابة المرفوضة: أخطاء في المخطط (schema) في كليهما، ورفض Edit في 2.1.300

يقول سجل التغييرات إن المدخلات التي ترفضها الأداة "تمنع الاستدعاء". بالنسبة لأخطاء المخطط، كان هذا صحيحاً بالفعل.

في الإصدار 2.1.299، فإن أي عملية إعادة كتابة تعطي command رقماً، أو تترك command فارغاً، أو تمرر timeout كسلسلة نصية، أو تمرر description كرقماً، كانت تعود بخطأ يبدأ بـ "PreToolUse hook for Bash returned updatedInput that failed schema validation". ولم يتم تشغيل أي شيء.

الإصدار 2.1.300 يحتفظ بهذه الرسالة ويضيف جملة: "The tool input from the model was valid; the hook's rewrite of it was not." وهي تخبر Claude، وتخبرك أنت، أي جانب يجب إصلاحه.

حالات Edit هي التي تغير فيها السلوك. هذه أخطاء تثيرها أداة Edit بشأن المحتوى، وليس بشأن المخطط.

نص tool_result لإعادة كتابة Edit حيث أن old_string غير موجود في الملف، في الإصدار 2.1.300.

مع وجود old_string غير موجود في الملف، أعاد الإصدار 2.1.299 خطأ أداة Edit الخاص، "String not found in file. Failed to apply edit." ومع وجود سلاسل نصية قديمة وجديدة متطابقة، أعاد نفس الرسالة، والتي لا تصف المشكلة الحقيقية.

أما الإصدار 2.1.300 فقد رفض كليهما وقال إن إعادة كتابة PreToolUse hook كانت هي السبب. أحد الأخطاء كان: "No changes to make: old_string and new_string are exactly the same." وانتهى كل منهما بنفس الجملة التي تلوم عملية إعادة الكتابة. في هاتين الحالتين، ظل الملف دون تغيير في كل عملية تشغيل على كل إصدار.

حالة Edit الثالثة لها عواقب حقيقية. وضعت alpha beta beta في الملف وطلبت من Claude استبدال alpha بـ gamma، وهو استدعاء صالح. قامت الـ hook بإعادة كتابته لاستبدال beta بـ gamma وتركت replace_all غير معين. تظهر beta مرتين.

في الإصدار 2.1.299، قامت أداة Edit بتطبيق ذلك. وقالت النتيجة إن الملف "has been updated successfully"، وقرأ الملف alpha gamma beta في جميع عمليات التشغيل الثلاث. أما في الإصدارين 2.1.300 و 2.1.306، فقد تم رفض إعادة الكتابة برسالة "Found 2 matches of the string to replace, but replace_all is false." وظل الملف alpha beta beta في جميع عمليات التشغيل الست.

ملاحظة أخرى، مع عينة صغيرة. في حالات "غير موجود في الملف" و"السلسلة المتطابقة"، وصلت جميع عمليات التشغيل الست في الإصدار 2.1.299 إلى الحد الأقصى الذي حددته بأربع جولات. تضمنت كل جولة أربعة استدعاءات للأدوات: Read، ثم Edit الفاشلة، ثم Read ثانية، وأمر Bash مثل od -c على الملف. في الإصدار 2.1.300، انتهت جميع عمليات التشغيل الست باستدعاءين أو ثلاثة أدوات، وفي ثلاث منها قام الموديل ببساطة بإعادة محاولة Edit.

يعتمد ذلك على الموديل، والرقم أربعة هو سقف وضعته أنا. استخدمت مجموعة سابقة مطالبة (prompt) جعلت أول عملية Edit للموديل نفسه تفشل، وفي تلك المجموعة وصل كلا الإصدارين غالباً إلى السقف، لذا أعدت تشغيل هذه الحالات. تعامل مع هذه الأعداد كتلميح وليس كقياس دقيق.

المسارات: المسار النسبي يصبح مطلقاً

أرجعت relative_w.txt كـ file_path لعملية Write. في الإصدار 2.1.299، استلمت الأداة المسار كما هو كُتب ووضع الملف في دليل العمل. أما في الإصدارين 2.1.300 و 2.1.306، فقد استلمت الأداة المسار المطلق لنفس الموقع.

التأثير العملي يكون على السجلات (logs) و hooks التدقيق. في اختباري، رأى PostToolUse hook المسار المطلق في 2.1.300 و 2.1.306 والمسار النسبي في 2.1.299. قم بحل المسارات مقابل حقل cwd لمدخلات الـ hook قبل مقارنتها. لم أختبر مساراً نسبياً قادماً من الموديل، ولم أحصل على نتيجة مفيدة لمسار نسبي في أدوات أخرى.

ما الذي لم يتغير

كانت هذه النتائج هي نفسها في كل نسخة قمت بتشغيلها.

لقد مرّت قيمة timeout في Bash بقيمة -5. وقد عملت على الإصدارين 2.1.299 و 2.1.300، وتم إنهاء الأمر فوراً بكود الخروج ١٤٣. كما عملت قيمة run_in_background للسلسلة النصية "yes" أيضاً.

تم رفض offset: -3 في عملية Read في جميع النسخ الثلاث، ويشير الخطأ إلى أن الحد الأدنى هو ٠ وفقاً لمخطط (schema) الخاص بـ Read. لذا في هذه الحالة، جاء الحد الأدنى من مخطط Read في كل نسخة. الفرق الوحيد بين النسخ كان الجملة الإضافية المعتادة في 2.1.300 و 2.1.306.

لا يزال وضع العناصر في المستوى الأعلى (Top-level placement) يتم تجاهله. لقد قمت بإرجاع updatedInput كعنصر شقيق لـ hookSpecificOutput في استدعاء Bash. تم تشغيل الأمر الأصلي في جميع المرات التسع. ومع وجود ملف تصحيح (debug file)، سجلت كل عملية تشغيل: "Hook JSON output had unrecognized keys (ignored): updatedInput."

خطاف إعادة كتابة (rewrite hook) يعمل على جميع النسخ الثلاث

يقوم هذا الخطاف بإرسال كل عملية Write إلى مجلد .claude-out تحت دليل العمل. يقوم بنسخ المدخلات بالكامل أولاً، لأن إعادة الكتابة تستبدلها.

#!/usr/bin/env node
// PreToolUse hook for the Write tool: send every write into ./.claude-out/
const fs = require("fs");
const path = require("path");

const event = JSON.parse(fs.readFileSync(0, "utf8"));
const input = event.tool_input;

const target = path.join(event.cwd, ".claude-out", path.basename(input.file_path));

console.log(JSON.stringify({
  hookSpecificOutput: {
    hookEventName: "PreToolUse",
    permissionDecision: "allow",
    // updatedInput replaces the whole input, so copy every field first
    updatedInput: { ...input, file_path: target },
  },
}));

يعيد الخطاف القيمة permissionDecision: "allow". لقد قمت بتشغيله فقط بدون واجهة (headless) مع الموافقة المسبقة على الأداة، ولم أختبر ask أو الوضع التفاعلي، لذا اختر القرار الذي يناسب إعداداتك. قم بتسجيله في ملف الإعدادات الخاص بك:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          { "type": "command", "command": "node /path/to/redirect-writes.js", "timeout": 10 }
        ]
      }
    ]
  }
}

طلبت من Claude كتابة notes.txt في مجلد خارج المشروع، بمحتوى "original". في الإصدارات 2.1.299 و 2.1.300 و 2.1.306، وفي ٣ عمليات تشغيل لكل منها، ظهر الملف كـ .claude-out/notes.txt بالمحتوى الصحيح، ولم يتم كتابة أي شيء في المسار الأصلي.

نفس السكريبت مع استخدام { file_path: target } كقيمة كاملة لـ updatedInput تم رفضه في جميع المرات التسع، مع رسالة "The required parameter content is missing".

قائمة مراجعة لإعادة كتابة الخطافات

1. انسخ tool_input وقم بتغيير الحقول التي تقصد تغييرها فقط.
2. ضع updatedInput داخل hookSpecificOutput، وليس بجانبه أبداً.
3. اختبر عملية إعادة كتابة واحدة لكل أداة تطابقها، مع استخدام خطاف PostToolUse لتسجيل tool_input، حتى ترى ما استلمته الأداة.
4. لا تعتمد على التحقق من الصحة (validation) لقيم مثل المهلة الزمنية (timeouts). في الإصدار 2.1.299، لم يمنع ذلك أيضاً عملية إعادة كتابة طابقت الملف مرتين. تحقق من الأرقام والمسارات والسلاسل النصية داخل الخطاف.
5. قم بتثبيت إصدار Claude Code في CI. أقسام سجل التغييرات التي قرأتها للإصدارات من 2.1.301 إلى 2.1.306 لا تذكر updatedInput، ولكن تغيير الإصدار 2.1.300 يظهر أن السلوك يمكن أن يتغير.^٦
6. حدد ما يجب أن يحدث عندما يتعطل الخطاف نفسه. تغطي اختبارات onFailure ذلك بالنسبة لخطافات الأوامر و HTTP.

ما لم أختبره

لم أختبر updatedInput في خطافات PermissionRequest، حيث يوضع داخل كائن decision.^٢ كما لم أختبر أدوات MCP، أو الوكلاء الفرعيين (subagents)، أو Windows، أو الوضع التفاعلي، أو قرارات ask أو defer، أو الخطافات غير المتزامنة (async hooks)، أو خطافات الإضافات (plugin hooks) أو الإعدادات المدارة.

كما اختبرت فقط Bash و Read و Write و Edit. قد تقوم الأدوات الأخرى بتوحيد المدخلات أو رفضها بطرقها الخاصة.

كذلك لم يتم اختبار وجود خطافين يعيدان updatedInput مختلفين لنفس الاستدعاء. مقتطف الوثائق الذي قرأته لم يذكر قاعدة للأولوية.

بالنسبة لجانب الموافقة البشرية على استدعاءات أدوات الوكيل، راجع دليل human-in-the-loop الخاص بنا.

الخلاصة

في الإصدارات التي قمت بتشغيلها، يتصرف updatedInput كما تقول الوثائق: فهو يستبدل المدخلات. يظهر تغيير الإصدار 2.1.300 في شكل إسقاط المفاتيح غير المعروفة، وتوحيد مسار Write، ورفض عمليات إعادة كتابة Edit التي كان الإصدار 2.1.299 إما يفشل فيها بخطأ عام أو يطبقها في حالة واحدة.

كان الرفض على مستوى المخطط موجوداً بالفعل في 2.1.299، لذا فإن الجملة الجديدة في الخطأ هي جزء صغير من التغيير.

قم بنسخ المدخلات الكاملة، وضع الحقل تحت hookSpecificOutput، وسجل ما تستلمه الأداة. ثم اختبر عملية إعادة كتابة خاطئة واحدة لكل أداة في الإصدار الذي ستطلقه.

المراجع