أوضاع الصلاحيات

import { createAgent, createFsTools, MemoryWorkspace } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const workspace = new MemoryWorkspace({ files: { 'notes.md': '# Notes\n' } });
const agent = createAgent({
  provider: mockModel(['I would add a "Todo" section to notes.md.', 'Done.']),
  instructions: 'You are a coding agent.',
  tools: createFsTools(workspace, { needsApproval: { write_file: true, edit_file: true } }),
});

const session = agent.session({ permissionMode: 'plan' });
await session.send('Plan how to add a todo list to notes.md.'); // reads only; writes are refused
session.setPermissionMode('acceptEdits');
await session.send('Apply the plan.'); // write_file and edit_file run without asking

​

الأوضاع

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

​

أي الأدوات للقراءة فقط

• أداة لها annotations: { readOnlyHint: true }. من المدمجة: read_file وlist_dir وglob وgrep وtodo_read وcurrent_date وday_name وweb_fetch وload_skill وكل أداة ذاكرة recall_<name>، وagent_status / agent_await (تراقبان الوكلاء الفرعيين في الخلفية). ولـأداة OpenAPI لعملية GET التلميح نفسه، وتحتفظ أداة MCP بالتلميح الذي أرسله خادمها: وهو كلمة الخادم لا ضمانًا، فلا تربط إلا خوادم تثق بها.
• الأداة المدمجة ask_question (هي تسأل فقط؛ ويتوقف الاستدعاء بانتظار الجواب) والأداة task (يرث وكيلها الفرعي وضع plan، انظر أدناه).
• أدوات المزوّد المستضافة تعمل داخل طلب المزوّد، فلا يمكن رفض أي استدعاء. يرسل وضع plan الأداتين webSearch() وfileSearch() (فهما تقرآن) ويترك codeInterpreter() وكل hostedTool() خارج طلب النموذج؛ وترسلها الأوضاع الأخرى كلها.

import { defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

const lookUpOrder = defineTool({
  name: 'look_up_order',
  description: 'Read an order by id',
  input: z.object({ id: z.string() }),
  annotations: { readOnlyHint: true },
  execute: async ({ id }) => ({ id, status: 'shipped' }),
});

​

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

import { defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

const appendLine = defineTool({
  name: 'append_line',
  description: 'Append a line to a file in the project',
  input: z.object({ path: z.string(), line: z.string() }),
  needsApproval: true,
  editsFiles: true,
  execute: async ({ path, line }) => `appended to ${path}: ${line}`,
});

​

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

1. التحقق من الوسائط، ثم خطّافات preToolCall. رفض الخطّاف ينهي الأمر هنا.
2. قواعد الصلاحيات (permissions). قاعدة deny تنهي الأمر هنا.
3. حواجز حماية الأداة. الحجب ينهي التشغيل.
4. needsApproval الخاص بالأداة. الرفض ينهي الأمر هنا؛ وقاعدة allow أو ask تحلّ محل طلبها.
5. وضع الصلاحيات، على ما تبقّى.

​

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

• createAgent({ permissionMode }): وضع الوكيل. الدالة تُقرأ عند كل استدعاء أداة، فالوضع الذي تبدّله أثناء تشغيل جارٍ يسري على استدعائه التالي.
• agent.send(message, { permissionMode }) / agent.stream(...): الوضع لذلك التشغيل وحده.
• agent.session({ permissionMode })، ثم session.setPermissionMode(mode) والمُجلِب session.permissionMode. تقرأ الجلسة وضعها عند كل استدعاء أداة في الدورة، فإن استُدعيت setPermissionMode() أثناء دورة (من مستمع tool.start مثلًا) سرت من استدعاء الأداة التالي في تلك الدورة. وافتراضيًا تأخذ الجلسة وضع الوكيل.

import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({
  provider,
  instructions: 'You are a coding agent.',
  onPermissionDecision: (entry) => console.log(entry.toolName, entry.decision, entry.mode),
  onPermissionModeChange: ({ sessionId, from, to, at }) => console.log(at, sessionId, `${from} -> ${to}`),
});

​

سجل التدقيق

​

الوكلاء الفرعيون

​

الاستئناف بعد موافقة