الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
وضع الصلاحيات يضع الـ agent في حالة لها اسم، بدلًا من أن تكتب rules: ينظر فقط دون أن يلمس شيئًا (plan)، أو يعدّل الملفات دون سؤال (acceptEdits)، أو لا يتوقف أبدًا (dontAsk). بدّله في منتصف الـ session، بالطريقة نفسها التي تعمل بها مع coding agent: خطّط أولًا، ثم دعه يعدّل.
الأوضاع presets فوق قواعد الصلاحيات وneedsApproval، وليست نظامًا آخر. تنطبق في النهاية، على ما قرّرته الـ rules والـ guardrails وneedsApproval الخاص بالـ tool.

الأوضاع

  • plan: أي call لـ tool ليست read-only يُرفض بـ kind: 'denied' والسبب The agent is in plan mode: it may read but not change anything. Describe the change instead. — حتى لو طابقته rule من نوع allow. والـ run الذي يبدأ في plan mode يأخذ فقرة واحدة في الـ system prompt تخبر الـ model بأنه في plan mode. أما الـ call لـ tool غير موجودة فيعيد خطأ not-found المعتاد، فيرى الـ model المشكلة الحقيقية.
  • acceptEdits: الـ call الذي كان سيتوقف لطلب موافقة يعمل دون سؤال إذا كانت الـ tool تعدّل الملفات (editsFiles، أدناه). الباقي لا يتغيّر.
  • dontAsk: الـ call الذي كان سيتوقف لطلب موافقة — rule من نوع ask، أو needsApproval، أو ask_question — يُرفض بالسبب The agent is in dontAsk mode: calls that need approval are refused. الـ calls التي وافقت عليها rule allow والتي لا تحتاج موافقة تعمل كالمعتاد. ولا يتوقف شيء، فلا يُستدعى أي approve callback أبدًا.

أي الـ tools read-only

وضع plan لا يشغّل الـ tool إلا إذا صرّحت بنفسها بأنها لا تغيّر شيئًا. الـ tool التي لم تصرّح بشيء تُعامل كأداة لها side effects وتُرفض.
  • tool لديها annotations: { readOnlyHint: true }. من الجاهزة: read_file، list_dir، glob، grep، todo_read، current_date، day_name، web_fetch، load_skill، وكل memory tool بصيغة recall_<name>، وagent_status / agent_await (تراقب الـ sub-agents العاملة في الخلفية). الـ OpenAPI tool لعملية GET لديها الـ hint نفسه. أما الـ MCP tool فلا تُحسب read-only إلا إذا كان مدخل خادمها في الإعدادات يضبط approval: 'annotations': الـ hint مجرد كلام من الخادم، وليس ضمانًا، لذا يرفض وضع plan افتراضيًا كل MCP tool.
  • الـ ask_question الجاهزة (هي تسأل فقط؛ ويظل الـ call متوقفًا بانتظار الجواب) وtask (الـ sub-agent الخاص بها يرث plan mode، انظر أدناه).
  • الـ hosted provider tools تعمل داخل طلب الـ provider، فلا يُرفض أي call. وضع plan يرسل webSearch() وfileSearch() (لأنهما يقرآن فقط) ويترك codeInterpreter() وكل hostedTool() خارج طلب الـ model؛ الأوضاع الأخرى ترسلها كلها.
عرّف tool read-only خاصة بك هكذا:
الـ hint وعد تقطعه على الـ tool الخاصة بك: plan mode يثق به.

تعديل الملفات: علامة editsFiles

acceptEdits لا يوافق إلا على الـ tools المعلَّمة بأنها تعدّل الملفات: write_file وedit_file من createFsTools()، وأي tool معرَّفة بـ editsFiles: true (تُخزَّن كـ metadata.editsFiles). لا تُحسب الـ tool معدِّلة للملفات من اسمها وحده، فإذا سمّيت tool من صنعك write_file فلن يُوافَق عليها بصمت.

ترتيب التقييم

لكل tool call، بهذا الترتيب:
  1. validation للـ arguments، ثم hooks الـ preToolCall. رفض الـ hook يتوقف هنا.
  2. قواعد الصلاحيات (permissions). rule من نوع deny تتوقف هنا.
  3. guardrails الـ tool. أي block ينهي الـ run.
  4. needsApproval الخاص بالـ tool. الرفض يتوقف هنا؛ وrule من نوع allow أو ask تحل محل سؤاله.
  5. وضع الصلاحيات، على الباقي.
أي أنه لا يوجد وضع يحوّل الرفض إلى تشغيل: رفض الـ hook، وrule deny، ورفض needsApproval تظل رفضًا في كل وضع. وacceptEdits لا يوافق أبدًا على call حجبه guardrail.

ضبط الوضع وتبديله

  • createAgent({ permissionMode }): وضع الـ agent. إذا مرّرت function، تُقرأ عند كل tool call، فالوضع الذي تبدّله أثناء تشغيل الـ run ينطبق على الـ call التالي.
  • agent.send(message, { permissionMode }) / agent.stream(...): الوضع لهذا الـ run فقط.
  • agent.session({ permissionMode })، ثم session.setPermissionMode(mode) والـ getter session.permissionMode. الـ session تقرأ وضعها عند كل tool call في الـ turn، فإذا استدعيت setPermissionMode() وأنت داخل turn (من listener على tool.start مثلًا — أي listener مسجّلة بـ session.on() أو loop على stream()) ينطبق التبديل ابتداءً من الـ tool call التالي في الـ turn نفسها. والـ session تأخذ وضع الـ agent افتراضيًا.
التبديل دائمًا استدعاء صريح لـ setPermissionMode(). وكل تبديل يُرسل إلى onPermissionModeChange مع { sessionId, from, to, at }:
الـ system prompt يُبنى عند بداية الـ run: لا يُخبَر الـ model بالوضع إلا إذا بدأ الـ run (أو الـ turn في session) في plan mode. والتبديل في منتصف الـ run يفرضه فحص الـ tool calls وحده، وهذا يكفي لأن سبب الرفض في الـ call المرفوض يصل إلى الـ model.

الـ audit log

ما دام هناك وضع غير 'default' مفعّل، يُسجَّل قرار كل tool call — حتى لو لم يضبط الـ agent permissions ولا onPermissionDecision. يُرسل القرار إلى onPermissionDecision (إذا كان مضبوطًا) ويظهر في الـ stream كـ event اسمه permission.decision. ولا يُضبط حقل mode في الـ entry إلا عندما يغيّر الوضع نتيجة الـ call: 'plan' أو 'dontAsk' مع decision: 'deny' والـ reason الخاص بالوضع، و'acceptEdits' مع decision: 'allow'. وإذا رفض الوضع call طابقته rule allow، يحتفظ الـ entry بـ rule.index الخاص بتلك القاعدة. تبديلات الوضع تُرسل إلى onPermissionModeChange. والـ argument الثاني في onPermissionDecision هو { principal }، أي من يعمل الـ run بالنيابة عنه؛ الـ entry والـ event لا يحملان هوية الـ caller (انظر auth).

الـ sub-agents

الـ sub-agent (أداة task أو task في الخلفية) يعمل بوضع الـ lead ما دام وضع الـ lead ليس 'default'، وإلا يعمل بالـ permissionMode الخاص به. والـ sub-agent الذي أنشأته بـ permissionMode: 'plan' يبقى في plan mode مهما كان وضع الـ lead. يُقرأ الوضع عند كل tool call من الـ sub-agent، فإذا بدّلت وضع session الـ lead ينطبق التبديل على sub-agent قيد التشغيل. وهذا ما يجعل task آمنة في plan mode: الـ sub-agent أيضًا لا يستطيع تغيير شيء. أما الـ remote sub-agent (remoteAgent()) فيعمل على خادم آخر وبصلاحيات ذلك الخادم، فلا تستطيع إلزامه بوضع الـ lead: في plan mode يُرفض الـ task call الموجّه إليه دون الاتصال به أصلًا، وفي dontAsk يُفشل الـ approval البعيد الـ task بدلًا من أن يوقف الـ lead.

الاستئناف بعد approval

الـ checkpoints وsnapshots الـ approvals لا تحفظ الوضع. الـ run الذي يكمله agent.approvals.resolve() يستخدم الوضع الحالي للـ session المتوقفة إذا كان الـ run المتوقف تابعًا لـ session، وإلا يستخدم وضع الـ agent (لا الوضع الذي مرّرته إلى send()). أي أن turn توقفت في 'default' وحُسمت بعد session.setPermissionMode('dontAsk') تشغّل الـ call الموافَق عليه، ثم ترفض الـ calls التالية التي كانت ستسأل. وفي plan mode يُرفض الـ call الموافَق عليه نفسه أيضًا إذا لم تكن الـ tool read-only. الاستئناف في process أخرى يستخدم الوضع الموجود لدى الـ agent أو الـ session التي تستأنف.