cc-viewer 1.7.22 → 1.8.0

package/README.md

@@ -35,6 +35,13 @@ brew install cc-viewer
 brew upgrade cc-viewer   # use this to upgrade; do NOT use npm install -g to upgrade a brew-installed ccv
 ```
 
+#### Install via pnpm (global)
+
+```bash
+pnpm add -g cc-viewer
+pnpm add -g cc-viewer@latest   # use this to upgrade; do NOT use npm install -g to upgrade a pnpm-installed ccv
+```
+
 ### How to start
 
 ccv is a drop-in replacement for claude — all arguments are passed through to claude while the Web Viewer is launched alongside it.
@@ -54,6 +61,18 @@ Once started in programming mode, the web page opens automatically.
 
 cc-viewer also ships as a native desktop app: [download page](https://github.com/weiesky/cc-viewer/releases)
 
+### SDK mode (headless, `ccv -SDK`)
+
+`ccv -SDK` runs the session through the Agent SDK instead of an interactive terminal — no terminal panel, messages are sent from the web UI, and everything else (session logs, streaming typewriter, usage stats) works the same as in terminal mode.
+
+```bash
+ccv -SDK                # headless session; chat from the browser
+ccv -SDK -c             # continue the most recent session
+ccv -SDK --model sonnet # pick a model
+```
+
+Approvals (Bash/Edit/Write/WebFetch/…) pop up in the browser with allow / deny / allow-for-session, and `AskUserQuestion` / plan prompts appear as modals. `npm publish` always requires an explicit approval — even with `--d`. Requires the `@anthropic-ai/claude-agent-sdk` package (bundled with cc-viewer); falls back to terminal mode if unavailable.
+
 ### Choose the Claude executable
 
 On the local CCV page, open **Global Settings → Claude executable** to choose the

package/cli.js

@@ -16,6 +16,7 @@ import { ensureHooks, removeAllManagedHooks } from './server/lib/ensure-hooks.js
 import { injectCliJsAt, removeCliJsInjectionAt, INJECT_START as _INJECT_START, INJECT_END as _INJECT_END, buildInjectBlock as _buildInjectBlock } from './server/lib/cli-inject.js';
 import { normalizeBasePath } from './server/lib/base-path.js';
 import { mergeSettingsIntoArgs } from './server/lib/settings-merge.js';
+import { splitSdkLaunchArgs } from './server/lib/launch-config.js';
 import { createHardenedCleanup, installWinKeypressFallback } from './server/lib/term-signals.js';
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
@@ -486,7 +487,7 @@ async function runCliMode(extraClaudeArgs = [], cwd, noOpen = false) {
   // IM worker：服务器监听成功后把真实端口回填进 im.lock（manager 据此做 HTTP 身份探测）
   if (process.env.CCV_IM_PLATFORM) {
     try {
-      const { updateImLockPort } = await import('./server/lib/im-lock.js');
+      const { updateImLockPort } = await import('./server/lib/im/im-lock.js');
       updateImLockPort(process.env.CCV_IM_PLATFORM, port);
     } catch (e) {
       console.error('[CC Viewer] updateImLockPort failed:', e.message);
@@ -587,15 +588,15 @@ async function runCliMode(extraClaudeArgs = [], cwd, noOpen = false) {
 // 外加：全局唯一锁、CC_APPEND_SYSTEM.md 人格预置/迁移、IM 专属 env。由 im-process-manager 以 detached 子进程拉起，
 // 也可手动 `ccv --im <id>` 启动。
 async function runImMode(platformId) {
-  const { getDescriptor } = await import('./server/lib/im-config.js');
+  const { getDescriptor } = await import('./server/lib/im/im-config.js');
   if (!getDescriptor(platformId)) {
     console.error(t('cli.imUnknownPlatform', { id: platformId }));
     process.exit(1);
   }
 
-  const { acquireImLock, releaseImLock, imDir } = await import('./server/lib/im-lock.js');
-  const { ensureImAppendSystem, migrateImClaudeMd } = await import('./server/lib/im-append-system.js');
-  const { ensureImBuiltinSkills } = await import('./server/lib/im-skills.js');
+  const { acquireImLock, releaseImLock, imDir } = await import('./server/lib/im/im-lock.js');
+  const { ensureImAppendSystem, migrateImClaudeMd } = await import('./server/lib/im/im-append-system.js');
+  const { ensureImBuiltinSkills } = await import('./server/lib/im/im-skills.js');
 
   const dir = imDir(platformId);
   mkdirSync(dir, { recursive: true });
@@ -653,14 +654,21 @@ async function runSdkMode(extraClaudeArgs = [], cwd, noOpen = false) {
   const { registerWorkspace } = await import('./server/workspace-registry.js');
   await registerWorkspace(workingDir);
 
-  // 不需要 ensureHooks — SDK canUseTool 处理 AskUserQuestion + 权限
-  // 不需要 proxy — SDK 直接管理 API 通信
+  // 不需要 ensureHooks — SDK canUseTool 处理 AskUserQuestion + 权限；
+  // 也不向子进程注入 CCVIEWER_PORT，让 CCV 的 settings bridges 保持休眠，避免双通道审批。
 
-  // 设置环境标记（必须在 import server.js 之前）
+  // 设置环境标记（必须在 import proxy.js / server.js 之前 — proxy.js → interceptor.js
+  // 可能触发 server.js 加载，而 server.js 的 isCliMode/isSdkMode 在模块顶层求值且只执行一次）
   process.env.CCV_CLI_MODE = '1';
   process.env.CCV_SDK_MODE = '1';
   process.env.CCV_PROJECT_DIR = workingDir;
-  process.env.CCV_PROXY_MODE = '1'; // 使 interceptor.js 惰性
+  process.env.CCV_PROXY_MODE = '1';
+
+  // 启动本地回环代理 — SDK 子进程的 API 流量经 ANTHROPIC_BASE_URL 指向这里，
+  // 报文捕获/落盘/流式推送与 PTY 模式走同一条 wire 通路
+  const { startProxy } = await import('./server/proxy.js');
+  const proxyPort = await startProxy();
+  process.env.CCV_PROXY_PORT = String(proxyPort);
 
   // 启动 HTTP 服务器
   const serverMod = await import('./server/server.js');
@@ -685,12 +693,75 @@ async function runSdkMode(extraClaudeArgs = [], cwd, noOpen = false) {
     permissionMode = 'bypassPermissions';
   }
 
+  // 合并用户 --settings 与注入的 env.ANTHROPIC_BASE_URL（与 PTY 的 --settings 注入
+  // 等价、同一 helper，注入键优先）；SDK 模式下经 options.settings 传给 query()。
+  // settingsMerge.args 已剥离 --settings；其余参数（--model/-c/-r 等）的映射后续接入。
+  const proxyBaseUrl = `http://127.0.0.1:${proxyPort}`;
+  const settingsMerge = mergeSettingsIntoArgs(extraClaudeArgs, { env: { ANTHROPIC_BASE_URL: proxyBaseUrl } }, { cwd: workingDir });
+  if (settingsMerge.warningDetail) {
+    console.warn(`[CC Viewer] --settings merge failed (${settingsMerge.warningDetail.reason}): ${settingsMerge.warningDetail.value}`);
+  }
+
+  // 子进程 env：代理指向 + 禁自动更新 + EDITOR 劫持（对齐 pty-manager 的注入面；
+  // 刻意不注入 CCVIEWER_PORT/PROTOCOL/INTERNAL_TOKEN — settings bridges 在 SDK 模式休眠）
+  const editorScript = resolve(__dirname, 'server', 'lib', 'ccv-editor.js');
+  const childEnv = {
+    ...process.env,
+    ANTHROPIC_BASE_URL: proxyBaseUrl,
+    // 与 PTY 子进程同款(pty-manager.js:247):SDK 子进程的 cli.js 若已被 -logger/PTY 注入
+    // interceptor,CCV_PROXY_MODE=1 让它只装 fetch hook 而不再自起 server;wire 捕获本来
+    // 就发生在主进程 proxy 的出站 fetch(ANTHROPIC_BASE_URL 指过来),此键保证子进程不双起。
+    CCV_PROXY_MODE: '1',
+    CCV_LOG_DIR: process.env.CCV_LOG_DIR || LOG_DIR,
+    DISABLE_AUTOUPDATER: '1',
+    EDITOR: `${process.execPath} ${editorScript}`,
+    VISUAL: `${process.execPath} ${editorScript}`,
+    CCV_EDITOR_PORT: String(port),
+  };
+  // 与 PTY 同款剥离(pty-manager.js:250-256):内部短路开关与 server 专属模式标记不外泄。
+  delete childEnv.CCV_SKIP_THINKING_DISPLAY;
+  delete childEnv.CCV_WORKSPACE_MODE;
+  delete childEnv.CCV_ELECTRON_MULTITAB;
+
+  // 用户参数映射到 SDK options：--model/-c/-r/--fork-session 提升为 SDK 原生 option
+  // （resume-pin 语义也需要它们），其余参数经 extraArgs 原样透传给 CLI 子进程。
+  // 不再静默丢弃任何参数。
+  const sdkArgs = splitSdkLaunchArgs(settingsMerge.args);
+  if (sdkArgs.pickerResume) {
+    console.warn('[CC Viewer] SDK mode: bare -r (interactive session picker) is not supported headless — starting a fresh session. Use -r <sessionId> to resume a specific session.');
+  }
+
   // 初始化 SDK 会话
+  // claudeExecutable 走与 PTY 相同的解析优先级(configured → codefuse → native → PATH → npm)。
+  // 缺了它 SDK 会从 PATH 解析 claude,在装有 agent-security headless guard 的机器上
+  // 会挑到一个 spawn 即被 SIGKILL 的二进制(PTY 交互式终端不在其拦截范围,headless 正中)。
+  let sdkClaudeSelection = null;
+  try {
+    sdkClaudeSelection = assertUsableClaudeSelection(resolvePreferredClaudeSelection());
+  } catch (err) {
+    console.error(`[CC Viewer] ${err.message}`);
+    process.exit(1);
+  }
+  const sdkClaudePath = sdkClaudeSelection?.path || null;
+  if (sdkClaudePath) {
+    process.env.CCV_CLAUDE_EXECUTABLE = sdkClaudePath;
+    console.log(`[CC Viewer] SDK mode: claude executable → ${sdkClaudePath} (${sdkClaudeSelection.source})`);
+  } else {
+    console.warn('[CC Viewer] SDK mode: no claude executable resolved — SDK will fall back to PATH/builtin discovery.');
+  }
+  // 观测面走与 PTY 相同的 wire 通路(SDK 子进程流量经 ANTHROPIC_BASE_URL 到 ccv proxy →
+  // fetch hook → v2 transcript → SSE),sdk-manager 不再另接 v2/streaming 注入。
   sdkManager.initSdkSession(workingDir, basename(workingDir), {
-    onEntry: (entry) => serverMod.pushSdkEntry(entry),
-    onStreamingStatus: (data) => serverMod.setSdkStreamingState(data),
     broadcastWs: (msg) => serverMod.broadcastWsMessage(msg),
     permissionMode,
+    env: childEnv,
+    settings: JSON.parse(settingsMerge.settingsJson),
+    model: sdkArgs.model,
+    claudeExecutable: sdkClaudePath,
+    launchResume: (sdkArgs.continue || sdkArgs.resume || sdkArgs.forkSession)
+      ? { continue: sdkArgs.continue, resumeId: sdkArgs.resume, forkSession: sdkArgs.forkSession }
+      : null,
+    userArgs: sdkArgs.rest,
     runWaterfallHook: (await import('./server/lib/plugin-loader.js')).runWaterfallHook,
     // Round-3 P0: SDK mode has no Stop hook (ensureHooks() skipped above), so
     // the only place we learn a turn ended is the SDK 'result' message. Forward
@@ -707,6 +778,9 @@ async function runSdkMode(extraClaudeArgs = [], cwd, noOpen = false) {
       try { serverMod.broadcastTurnEnd(sessionId, ts); }
       catch (err) { console.warn('[sdk] broadcastTurnEnd threw:', err?.message); }
     },
+    // query 级失败(spawn/protocol/iterator)推到 Web UI toast —— 此前只有 console.error,
+    // 死掉的 query 在 UI 上看与挂起无异。
+    onQueryError: (message) => serverMod.broadcastWsMessage({ type: 'sdk-error', message }),
   });
 
   // 注册 SDK 回调到 server.js（WS 消息路由用）
@@ -714,6 +788,13 @@ async function runSdkMode(extraClaudeArgs = [], cwd, noOpen = false) {
   serverMod.setSdkCancelApproval(sdkManager.cancelApproval);
   serverMod.setSdkSendUserMessage(sdkManager.sendUserMessage);
   serverMod.setSdkInterruptTurn(sdkManager.interruptTurn);
+  serverMod.setSdkGetPendingApprovals(sdkManager.getPendingApprovals);
+  serverMod.setSdkGetInitSnapshot(sdkManager.getSdkInitSnapshot);
+  // Busy-queue bubble actions (queue-send-now / queue-remove / queue-clear / replay).
+  serverMod.setSdkSendQueuedNow(sdkManager.sendQueuedNow);
+  serverMod.setSdkRemoveQueued(sdkManager.removeQueued);
+  serverMod.setSdkClearQueued(sdkManager.clearQueued);
+  serverMod.setSdkGetQueueSnapshot(sdkManager.getQueueSnapshot);
 
   // 自动打开浏览器
   const protocol = serverMod.getProtocol();

package/concepts/ar/GlobalSettings.md

@@ -122,12 +122,12 @@ CC-Viewer 自动注册到 `~/.claude/settings.json` 的 `hooks.PreToolUse` 中
 
 ### 1. AskUserQuestion 桥接
 - **匹配器**: `"AskUserQuestion"`
-- **命令**: `node <安装目录>/server/lib/ask-bridge.js`
+- **命令**: `node <安装目录>/server/lib/ask/ask-bridge.js`
 - **作用**: 将 Claude 的问题转发到 Web UI，等待用户回答
 
 ### 2. 权限审批桥接
 - **匹配器**: `""` (空 = 匹配所有工具)
-- **命令**: `node <安装目录>/server/lib/perm-bridge.js`
+- **命令**: `node <安装目录>/server/lib/ask/perm-bridge.js`
 - **作用**: 仅 `Bash`/`Edit`/`Write`/`NotebookEdit` 需要 Web UI 审批，其余自动放行
 
 ## 七、Shell 集成

package/concepts/ar/Tool-Artifact.md

@@ -9,6 +9,13 @@
 - إدراج القطع الموجودة للمستخدم للعثور على واحدة من جلسة سابقة (`action: "list"`)
 - **ليس** للمحتوى الذي يجب أن يبقى محليًا أو الإجابات النصية البسيطة أو أي شيء يحتاج إلى موارد شبكية خارجية في وقت العرض — يمنع CSP الصارم كل مضيف خارجي
 
+## التفعيل
+
+- يتطلب خطة Pro أو Max أو Team أو Enterprise مع تسجيل الدخول إلى claude.ai (`/login`).
+- Anthropic API فقط — غير متاح على Amazon Bedrock وGoogle Cloud أو Microsoft Foundry.
+- يتطلب Claude Code ≥ 2.1.183 أو تطبيق Desktop ≥ 1.13576.0.
+- عطِّله بإعداد `disableArtifact` أو بـ `CLAUDE_CODE_DISABLE_ARTIFACT=1`.
+
 ## المعاملات
 
 - `file_path` (نص): المسار إلى ملف `.html` أو `.md` لتصييره. يتم لف الملف في هيكل المستند عند النشر، لذا اكتب محتوى الصفحة مباشرة — بدون وسوم `<!DOCTYPE>` أو `<html>` أو `<head>` أو `<body>`. نفس المسار → نفس عنوان URL عند النشر مجددًا؛ المسار المختلف يحصل على عنوان URL جديد.

package/concepts/ar/Tool-EndConversation.md

@@ -0,0 +1,35 @@
+# EndConversation
+
+ينهي المحادثة الحالية ويمنع إرسال أي رسائل أخرى.
+
+## متى يُستخدم
+
+- فقط عند إساءة مستمرة من المستخدم، أو عندما يطلب المستخدم صراحةً عرضاً لهذه الأداة.
+
+هذا إجراء الملاذ الأخير: تتطلب قواعد الأداة نفسها تحذير المستخدم أولاً والتأكيد قبل الاستخدام، ويجب ألا تُستخدم أبداً في حالات إيذاء النفس أو المواقف المرتبطة بالأذى.
+
+## التفعيل
+
+- يتطلب Claude Code 2.1.213+ ونموذجاً من عائلة Opus 4.8 / Sonnet 5 / Fable 5 أو ما بعدها.
+- جلسات الطرفية التفاعلية فقط — لا يتوفر أبداً في وضع `--bare`، ولا يتوفر أبداً للوكلاء الفرعيين.
+- غير متاح على Amazon Bedrock وClaude Platform on AWS وVertex AI وMicrosoft Foundry أو البوابات السحابية.
+- يتطلب علَم ميزة من جهة الخادم — معظم الجلسات لا تعرض هذه الأداة.
+
+## المعاملات
+
+لا تأخذ هذه الأداة أي معاملات.
+
+## أمثلة
+
+### مثال 1: إنهاء المحادثة
+
+```
+EndConversation()
+```
+
+التدفق من خطوتين: الاستدعاء الأول يُعيد رسالة تأمل؛ والاستدعاء الثاني بعده مباشرة ينهي المحادثة فعلياً (`ended: true`).
+
+## ملاحظات
+
+- خاضعة لبوابات شديدة: تتطلب نموذجاً مدعوماً ونقطة دخول CLI وعلَم ميزة من جهة الخادم — معظم الجلسات لا تعرض هذه الأداة.
+- بمجرد انتهائها، لا يمكن إرسال أي رسائل أخرى في المحادثة.

package/concepts/ar/Tool-LSP.md

@@ -2,7 +2,7 @@
 
 يستعلم من خوادم بروتوكول خادم اللغة (LSP) للحصول على ذكاء الشيفرة — التعريفات والمراجع والتلميحات والرموز والتنفيذات وتسلسل الاستدعاءات. أكثر دقة من البحث النصي لأنه يفهم الشيفرة دلاليًا.
 
-## متى تستخدمه
+## متى يُستخدم
 
 - الانتقال إلى تعريف رمز (`goToDefinition`) أو العثور على كل مرجع له (`findReferences`)
 - قراءة توقيعات الأنواع / التوثيق لرمز ما (`hover`)
@@ -10,6 +10,11 @@
 - العثور على تنفيذات واجهة أو طريقة مجردة (`goToImplementation`)
 - التنقل في تسلسل استدعاءات دالة (`prepareCallHierarchy` و`incomingCalls` و`outgoingCalls`)
 
+## التفعيل
+
+- غير نشط حتى يُثبَّت مكوِّن ذكاء الشيفرة الإضافي الخاص باللغة (يُثبَّت ملف الخادم الثنائي بشكل منفصل).
+- لا تظهر الأداة إلا عند اتصال عميل LSP.
+
 ## المعاملات
 
 - `operation` (string، مطلوب): إحدى العمليات المذكورة أعلاه.

package/concepts/ar/Tool-ListAgents.md

@@ -0,0 +1,35 @@
+# ListAgents
+
+يسرد الوكلاء الذين يمكنك إرسال رسالة إليهم عبر `SendMessage`: الوكلاء الفرعيون داخل العملية الذين أنشأتهم، وجلسات Claude المحلية الأخرى على هذا الجهاز، وجلساتك السحابية (عند توفر وصول سحابي لهذه الجلسة)، و— عند اتصال Remote Control — جلسات حسابك الأخرى. كل صف مُوسوم بنوعه.
+
+## متى يُستخدم
+
+- تحتاج الاسم الدقيق لجلسة نظيرة أو وكيل فرعي قبل إرسال رسالة إليه.
+- تريد رؤية الجلسات القابلة للوصول حالياً من هذه الجلسة.
+
+## التفعيل
+
+- يتطلب Claude Code 2.1.224+ والمراسلة عبر الجلسات (علَم ميزة من جهة الخادم، معطَّل افتراضياً).
+- المراسلة عبر الجلسات غير متاحة على Amazon Bedrock وClaude Platform on AWS وGoogle Cloud Agent Platform وMicrosoft Foundry.
+- معطَّل عند ضبط `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` أو `DISABLE_TELEMETRY` أو `DO_NOT_TRACK` أو `DISABLE_GROWTHBOOK`.
+- يمكن فرض تفعيله بـ `CLAUDE_CODE_HARBOR_KITE=1`.
+
+## المعاملات
+
+- `channel` (سلسلة، اختياري): غير متاح في هذا البناء؛ اتركه غير مضبوط.
+- `q` (سلسلة، اختياري): غير متاح في هذا البناء؛ اتركه غير مضبوط.
+
+## أمثلة
+
+### مثال 1: سرد الوكلاء القابلين للوصول
+
+```
+ListAgents()
+```
+
+يطبع كل صف اسماً — ذلك الاسم هو العنوان. أرسل بـ `SendMessage({to: "<name>", message: "..."})` ناسخاً الاسم تماماً كما طُبع. ألحق ` [ref]` الخاص بصف فقط عندما يكون الاسم المجرد ملتبساً (يتشاركه صفان، أو يطلب خطأ التوضيح).
+
+## ملاحظات
+
+- للقراءة فقط وآمن مع التزامن.
+- تستقبل الجلسة السحابية رسالتك لكنها لا تستطيع الرد بعد — اقرأ إجابتها في نصها (transcript) الخاص.

package/concepts/ar/Tool-ListConnectors.md

@@ -0,0 +1,34 @@
+# ListConnectors
+
+يسرد موصلات MCP المثبتة لمؤسسة المستخدم على claude.ai، مع تصفية اختيارية بالكلمات المفتاحية.
+
+## متى يُستخدم
+
+- تحتاج معرفة الموصلات المثبتة بالفعل قبل اقتراح موصلات جديدة.
+- يسأل المستخدم عن عمليات التكامل التي تمتلكها مؤسسته.
+
+## التفعيل
+
+- متاح فقط في الجلسات البعيدة (claude.ai) عبر واجهة API الرسمية.
+
+## المعاملات
+
+- `keywords` (مصفوفة سلاسل، اختياري): تصفية القائمة — حتى 8 عناصر، كل عنصر من 1 إلى 64 حرفاً. احذفه لسرد كل شيء.
+
+## أمثلة
+
+### مثال 1: سرد كل الموصلات المثبتة
+
+```
+ListConnectors()
+```
+
+### مثال 2: التصفية بالكلمة المفتاحية
+
+```
+ListConnectors(keywords=["github"])
+```
+
+## ملاحظات
+
+- اقرنها بـ `SearchMcpRegistry` (الاكتشاف) و`SuggestConnectors` (التفاصيل) لتدفق البحث والتفعيل الكامل.

package/concepts/ar/Tool-ListMcpResources.md

@@ -0,0 +1,35 @@
+# ListMcpResources
+
+يسرد الموارد التي تعرضها خوادم MCP المتصلة، مع إمكانية التصفية الاختيارية إلى خادم واحد.
+
+## متى يُستخدم
+
+- تحتاج اكتشاف الموارد (ملفات أو سجلات أو مستندات) التي يقدمها خادم MCP قبل قراءتها.
+- تريد نظرة عامة على كل الموارد عبر كل خادم متصل.
+
+## التفعيل
+
+- مفعَّل دائماً، لكنه غير معروض في قائمة أدوات النموذج — مُخصَّص لاستخدام thin-client / sidecar.
+
+## المعاملات
+
+- `server` (سلسلة، اختياري): اسم الخادم لتصفية الموارد به. احذفه لسرد الموارد من جميع الخوادم المتصلة.
+
+## أمثلة
+
+### مثال 1: سرد كل شيء
+
+```
+ListMcpResources()
+```
+
+### مثال 2: سرد موارد خادم واحد
+
+```
+ListMcpResources(server="github")
+```
+
+## ملاحظات
+
+- هذه خطوة الاكتشاف: مرر URIs المثيرة للاهتمام إلى `ReadMcpResource` (مورد واحد) أو `ReadMcpResourceDir` (قوائم أدلة).
+- تتصل الخوادم وتنفصل على مدى عمر الجلسة؛ أعد السرد إذا أُضيف خادم للتو.

package/concepts/ar/Tool-ListPlugins.md

@@ -0,0 +1,35 @@
+# ListPlugins
+
+يسرد مكوِّنات claude.ai الإضافية المفعلة لدى المستخدم، مع تصفية اختيارية بالكلمات المفتاحية.
+
+## متى يُستخدم
+
+- تحتاج معرفة المكوِّنات الإضافية المفعلة بالفعل — مثلاً للتأكد مما ثُبِّت بعد بطاقة `SuggestPluginInstall`.
+- يسأل المستخدم عن المكوِّنات الإضافية التي يمتلكها.
+
+## التفعيل
+
+- يتطلب إذن الوصول إلى سجل المكوِّنات الإضافية.
+- يعتمد التوفر على نوع الجلسة والتفعيل التدريجي للميزات — معطَّل في بيئات HIPAA، ومتاح دائماً في الجلسات البعيدة.
+
+## المعاملات
+
+- `keywords` (مصفوفة سلاسل، اختياري): تصفية القائمة — حتى 8 عناصر، كل عنصر من 1 إلى 64 حرفاً. احذفه لسرد كل شيء.
+
+## أمثلة
+
+### مثال 1: سرد المكوِّنات الإضافية المفعلة
+
+```
+ListPlugins()
+```
+
+### مثال 2: التصفية بالكلمة المفتاحية
+
+```
+ListPlugins(keywords=["figma"])
+```
+
+## ملاحظات
+
+- إذا تعذر الوصول إلى كتالوج المكوِّنات الإضافية (مرفوض)، تتدهور الأداة إلى قائمة فارغة مع تحذير بدلاً من الفشل.

package/concepts/ar/Tool-ListSkills.md

@@ -0,0 +1,37 @@
+# ListSkills
+
+يسرد مهارات claude.ai المفعلة لدى المستخدم، مع تصفية اختيارية بالكلمات المفتاحية.
+
+## متى يُستخدم
+
+- تحتاج القائمة المرجعية للمهارات المفعلة حالياً — قبل استدعاء إحداها، أو للتأكد مما أضافته بطاقة `SuggestSkills`.
+- يسأل المستخدم عن المهارات التي يمتلكها.
+
+## التفعيل
+
+- يتطلب إذن الوصول إلى سجل المكوِّنات الإضافية.
+- معطَّل في بيئات HIPAA.
+- متاح دائماً في الجلسات البعيدة.
+
+## المعاملات
+
+- `keywords` (مصفوفة سلاسل، اختياري): تصفية القائمة — حتى 8 عناصر، كل عنصر من 1 إلى 64 حرفاً. احذفه لسرد كل شيء.
+
+## أمثلة
+
+### مثال 1: سرد المهارات المفعلة
+
+```
+ListSkills()
+```
+
+### مثال 2: التصفية بالكلمة المفتاحية
+
+```
+ListSkills(keywords=["review"])
+```
+
+## ملاحظات
+
+- إذا تعذر الوصول إلى الكتالوج (مرفوض)، تتدهور الأداة إلى قائمة فارغة مع تحذير بدلاً من الفشل.
+- هذه تسرد المهارات *المفعلة*؛ استخدم `SuggestSkills` لإظهار مهارات يمكن للمستخدم إضافتها.

package/concepts/ar/Tool-Monitor.md

@@ -10,6 +10,13 @@
 - انتظار شرط محدد عبر تكرارات عديدة (مثل الوصول إلى نقطة تحقق في خطوة تدريب أو إفراغ طابور)
 - **ليس** للانتظار البسيط حتى الانتهاء — استخدم `Bash` مع `run_in_background` لذلك؛ يُرسل إشعار اكتمال واحد عند انتهاء العملية
 
+## التفعيل
+
+- معطَّل افتراضياً (علَم ميزة من جهة الخادم).
+- غير متاح على Amazon Bedrock وGoogle Cloud وMicrosoft Foundry.
+- معطَّل عند ضبط `DISABLE_TELEMETRY` أو `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`.
+- يتطلب مصدر WebSocket إصدار Claude Code 2.1.195+.
+
 ## المعاملات
 
 - `command` (نص، مطلوب): أمر الصدفة أو البرنامج النصي المراد تشغيله. كل سطر يُكتب في المخرجات القياسية يصبح حدث إشعار مستقلًا. ينتهي المراقب عند انتهاء العملية.

package/concepts/ar/Tool-Projects.md

@@ -0,0 +1,46 @@
+# Projects
+
+يدير مستندات المشروع في قاعدة معرفة مشروع المستخدم على Claude: قراءة وبحث وكتابة وحذف المستندات، أو جلب معلومات المشروع.
+
+## متى يُستخدم
+
+- حفظ مستند (مخرج أو ملاحظات أو مادة مرجعية) في مشروع المستخدم حتى يبقى بعد الجلسة.
+- قراءة مستندات المشروع الحالية أو البحث فيها لتأسيس المهمة الحالية على سياق سابق.
+- رفع ملف محلي إلى المشروع دون تحميل محتواه في السياق.
+- إزالة مستند مشروع قديم.
+
+## المعاملات
+
+- `method` (سلسلة، مطلوب): واحدة من `project_info` أو `project_read` أو `project_search` أو `project_write` أو `project_delete`.
+- `path` (سلسلة، اختياري): لأجل `project_read`/`project_write`/`project_delete`: مسار المستند. ولأجل `project_write`: المسار الموجود يُستبدل في مكانه؛ واسم الملف المجرد الجديد (بدون "/") يُنسَب إلى `claude/<name>`.
+- `content` (سلسلة، اختياري): لأجل `project_write`: نص المستند المكتوب مباشرة. متنافٍ مع `local_path`.
+- `local_path` (سلسلة، اختياري): لأجل `project_write`: ملف داخل دليل العمل لرفعه — لا يدخل محتواه سياقك أبداً. متنافٍ مع `content`.
+- `present_to_user` (منطقي، اختياري): لأجل `project_write`: علِّم هذا المستند بوصفه المخرج الذي يحتاج المستخدم إلى رؤيته. الافتراضي false؛ اتركه غير مضبوط للحفظات الروتينية والكتابات المجمعة.
+- `query` (سلسلة، اختياري): لأجل `project_search`: استعلام قاعدة المعرفة.
+- `n` (عدد، اختياري): لأجل `project_search`: عدد النتائج (الافتراضي 5).
+
+## أمثلة
+
+### مثال 1: كتابة المخرج في المشروع
+
+```
+Projects(
+  method="project_write",
+  path="claude/migration-plan.md",
+  local_path="./migration-plan.md",
+  present_to_user=true
+)
+```
+
+يرفع الملف المحلي دون سحب محتواه إلى السياق، ويعلّمه بوصفه مخرج المستخدم.
+
+### مثال 2: البحث في قاعدة المعرفة
+
+```
+Projects(method="project_search", query="authentication refresh tokens", n=5)
+```
+
+## ملاحظات
+
+- `content` للنص الذي تؤلفه مباشرة؛ و`local_path` لأي شيء موجود على القرص بالفعل — لا تخلط بينهما أبداً.
+- استخدم `present_to_user=true` باعتدال: فقط للمستند الوحيد الذي طلبه المستخدم أو يجب أن يتصرف بناءً عليه.

package/concepts/ar/Tool-ProposeGoal.md

@@ -0,0 +1,43 @@
+# ProposeGoal
+
+يقترح هدف إنجاز قابلاً للتحقق للجلسة. يُعرض الهدف على المستخدم في حوار موافقة (افتراضياً)، وبمجرد ضبطه يوجه بقية المحادثة نحو نتيجة قابلة للفحص.
+
+## متى يُستخدم
+
+- للجلسة حالة نهاية ملموسة يمكن لمُقيِّم التحقق منها من المحادثة (مثل "all tests in test/auth pass").
+- تريد موافقة صريحة من المستخدم على ما يعنيه «الانتهاء» قبل القيام بعمل جوهري.
+- كلمات المستخدم نفسها نصت بالفعل على النتيجة وتريد تسجيلها هدفاً للجلسة.
+
+## التفعيل
+
+- معطَّل افتراضياً (علَم ميزة من جهة الخادم).
+- مستثنى من الجلسات التفاعلية وجلسات الخلفية.
+- يُطفأ بمفتاح الإعدادات `modelProposedGoals: "disabled"`.
+
+## المعاملات
+
+- `condition` (سلسلة، مطلوب): شرط الإنجاز، مكتوباً بحيث يستطيع مُقيِّم منفصل التحقق منه من المحادثة (مثل "all tests in test/auth pass (bun test exits 0)"). 500 حرف كحد أقصى — يجب أن يستطيع المستخدم قراءة الشرط كاملاً في حوار الموافقة.
+- `ask_user` (منطقي، اختياري): ما إذا كان يُطلب من المستخدم الموافقة قبل ضبط الهدف. الافتراضي true (يُعرض حوار موافقة). اضبطه false فقط عندما تكون كلمات المستخدم في هذه المحادثة قد نصت على هذه النتيجة بوصفها ما يريده؛ عندئذ يُضبط الهدف مباشرة مع إشعار مرئي، ويمكن للمستخدم مسحه بـ `/goal clear`.
+
+## أمثلة
+
+### مثال 1: اقتراح هدف مدعوم بالاختبارات
+
+```
+ProposeGoal(condition="npm run test exits 0 with the new catalog cases included")
+```
+
+يرى المستخدم الشرط في حوار موافقة ويمكنه قبوله أو تعديله أو رفضه.
+
+### مثال 2: تبني نتيجة المستخدم المنصوص عليها مباشرة
+
+```
+ProposeGoal(condition="the login form validates email format and shows an inline error", ask_user=false)
+```
+
+صالح فقط لأن المستخدم نص صراحةً على تلك النتيجة في وقت سابق من المحادثة.
+
+## ملاحظات
+
+- أبقِ `condition` قصيراً وقابلاً للفحص موضوعياً — الأهداف المبهمة ("make it better") تُفقد الغرض قيمته.
+- `ask_user=false` مقتصر تماماً على النتائج التي نص عليها المستخدم نفسه؛ أي شيء آخر يجب أن يمر عبر حوار الموافقة.

package/concepts/ar/Tool-PushNotification.md

@@ -14,6 +14,12 @@
 
 لا ترسل إشعارًا لتحديثات التقدم الروتينية أثناء تنفيذ مهمة، ولا لتأكيد إجابة سؤال طرحه المستخدم للتو وهو ينتظر ردًا واضحًا. لا ترسل إشعارًا عند انتهاء مهمة قصيرة — إذا أرسل المستخدم المهمة للتو وهو ينتظر، فالإشعار لا قيمة له ويُضعف الثقة في الإشعارات المستقبلية. مِل بشدة نحو عدم الإرسال.
 
+## التفعيل
+
+- معطَّل افتراضياً (علَم ميزة من جهة الخادم).
+- يتم التسليم عبر بنية تحتية مستضافة لدى Anthropic — غير متاح على Amazon Bedrock وClaude Platform on AWS وGoogle Cloud أو Microsoft Foundry.
+- يتطلب إشعار الهاتف إضافةً عميل Remote Control متصلاً.
+
 ## المعاملات
 
 - `message` (سلسلة نصية، مطلوب): نص الإشعار. احتفظ به أقل من 200 حرف؛ تقوم أنظمة التشغيل للهواتف المحمولة باقتصاص السلاسل الأطول. ابدأ بما سيتصرف المستخدم بناءً عليه: "build failed: 2 auth tests" أكثر فائدة من "task complete".

package/concepts/ar/Tool-REPL.md

@@ -0,0 +1,47 @@
+# REPL
+
+ينفذ JavaScript في سياق vm خاص بـ Node.js دائم داخل الجلسة. يُدعَم `await` على المستوى الأعلى، وتبقى المتغيرات/الدوال المعرَّفة في استدعاء واحد متاحة في الاستدعاءات اللاحقة.
+
+## متى يُستخدم
+
+- حسابات سريعة أو تحويل بيانات أو معالجة JSON أسهل في الكود منها في أسطر shell المنفردة.
+- برمجة متعددة الخطوات يجب أن تستمر فيها الحالة الوسيطة بين الاستدعاءات (عدادات، نتائج متراكمة).
+- استكشاف سلوك واجهة API أو مكتبة تفاعلياً قبل كتابته في ملف.
+
+## التفعيل
+
+- معطَّل افتراضياً — اضبط `CLAUDE_CODE_REPL=true` لتفعيله.
+- في جلسات الطرفية (`cli`) و claude.ai (`remote`)، قد يفعِّله أيضاً علَم ميزة من جهة الخادم.
+- عند إيقافه، يُخفى REPL من قائمة أدوات النموذج. وعند تشغيله، تحل اختصارات REPL محل `Read` و`Glob` و`Grep` و`Bash` و`PowerShell` و`NotebookEdit`.
+
+## المعاملات
+
+- `code` (سلسلة، مطلوب): كود JavaScript المطلوب تنفيذه. يدعم await على المستوى الأعلى. تستمر الحالة عبر الاستدعاءات.
+- `description` (سلسلة، اختياري): وصف واضح وموجز لما يفعله هذا السكريبت بصيغة المبني للمعلوم (5–10 كلمات)، مثل "Trace upgrade message to its GrowthBook flag".
+- `timeout` (عدد، اختياري): المهلة بالمللي ثانية. القيمة الافتراضية 30000؛ والحد الأقصى 600000.
+
+## أمثلة
+
+### مثال 1: حساب حالة وإعادة استخدامها
+
+```
+REPL(code="const counts = new Map(); ['a','b','a'].forEach(k => counts.set(k, (counts.get(k)||0)+1)); counts.get('a')")
+```
+
+يُعيد `2`؛ ويبقى `counts` معرَّفاً لاستدعاءات REPL اللاحقة في الجلسة نفسها.
+
+### مثال 2: await على المستوى الأعلى مع مهلة أطول
+
+```
+REPL(
+  code="const res = await fetch('https://example.com/api'); await res.json()",
+  description="Fetch example API and parse JSON",
+  timeout=60000
+)
+```
+
+## ملاحظات
+
+- الحالة لكل جلسة: إعادة تشغيل الجلسة تمسح كل التعريفات.
+- هذه بيئة JavaScript (Node) — استخدم Bash لأوامر shell أو الأعمال كثيفة الملفات أو بيئات التشغيل غير JS.
+- يجب أن يحدد الكود طويل الأمد `timeout` صراحةً؛ فالافتراضي 30 ثانية يقتل أي شيء أبطأ.