plan)، أو يعدّل الملفات دون سؤال (acceptEdits)، أو لا يتوقف أبدًا (dontAsk). بدّله في منتصف الـ session، بالطريقة نفسها التي تعمل بها مع coding agent: خطّط أولًا، ثم دعه يعدّل.
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 التي وافقت عليها ruleallowوالتي لا تحتاج موافقة تعمل كالمعتاد. ولا يتوقف شيء، فلا يُستدعى أيapprovecallback أبدًا.
أي الـ 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؛ الأوضاع الأخرى ترسلها كلها.
تعديل الملفات: علامة editsFiles
acceptEdits لا يوافق إلا على الـ tools المعلَّمة بأنها تعدّل الملفات: write_file وedit_file من createFsTools()، وأي tool معرَّفة بـ editsFiles: true (تُخزَّن كـ metadata.editsFiles). لا تُحسب الـ tool معدِّلة للملفات من اسمها وحده، فإذا سمّيت tool من صنعك write_file فلن يُوافَق عليها بصمت.
ترتيب التقييم
لكل tool call، بهذا الترتيب:- validation للـ arguments، ثم hooks الـ
preToolCall. رفض الـ hook يتوقف هنا. - قواعد الصلاحيات (
permissions). rule من نوعdenyتتوقف هنا. - guardrails الـ tool. أي block ينهي الـ run.
needsApprovalالخاص بالـ tool. الرفض يتوقف هنا؛ وrule من نوعallowأوaskتحل محل سؤاله.- وضع الصلاحيات، على الباقي.
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)والـ gettersession.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 }:
الـ 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 التي تستأنف.