@yeaft/webchat-agent 0.1.1012 → 0.1.1015

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.1012",
+  "version": "0.1.1015",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/yeaft/engine.js

@@ -21,6 +21,7 @@ import { randomUUID } from 'crypto';
 import { promises as fsp } from 'fs';
 import { join, resolve as resolvePath } from 'path';
 import { buildSystemPrompt, buildWorkerPrompt } from './prompts.js';
+import { getRuntimePlatformInfo } from './runtime-platform.js';
 import { LLMContextError, LLMAbortError } from './llm/adapter.js';
 import { runMemoryPreflow, buildRelevantScopes } from './sessions/pre-flow.js';
 import { readProjectDoc, pickProjectDocFile, DEFAULT_PROJECT_DOC_MAX_BYTES } from './sessions/project-doc.js';
@@ -815,6 +816,7 @@ export class Engine {
       activeScope,
       sessionAnnouncement,
       projectDoc,
+      runtimePlatform: getRuntimePlatformInfo(),
       taskCtx,
       // Worker-shape harness is descriptive metadata for human inspection;
       // production prompts skip it to save tokens. Re-enable via env when
@@ -903,6 +905,7 @@ export class Engine {
     return {
       signal,
       yeaftDir: this.#yeaftDir,
+      runtimePlatform: getRuntimePlatformInfo(),
       // Group-scoped working directory. Threaded from #runQuery({ workDir })
       // → set by web-bridge runVpTurn from sessionMeta.workDir. Tools read
       // `ctx.cwd` and resolve relative paths against it. Always absolute

package/yeaft/prompts.js

@@ -25,6 +25,7 @@
 import { readFileSync, existsSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
+import { getRuntimePlatformInfo, renderRuntimePlatformPrompt } from './runtime-platform.js';
 import { DEFAULT_VPS } from './vp/seed-defaults.js';
 
 // ─── Template Loading (one-time at startup) ──────────────────────
@@ -196,8 +197,12 @@ const PROMPTS = {
     date: (d) => `Date: ${d}`,
     dream: 'You are in dream mode. Reflect on past conversations and consolidate memories.',
     tools: (names) => `Available tools: ${names}`,
-    // DESIGN-PROMPT §3 ④ — Active Scope header
-    activeScopeHeader: '## active_scope',
+    // DESIGN-PROMPT §3 ④ — current session context block.
+    activeScopeHeader: '## Current session context',
+    activeScopeSessionIdLabel: 'Session ID',
+    activeScopeMembersLabel: 'Session members',
+    activeScopeTopicsLabel: 'Current focus',
+    activeScopeEnvelopeLabel: 'Handoff',
     multiVpRoutingHeader: '## multi_vp_routing',
     sessionAnnouncementHeader: '[Session Announcement]',
     // Project-doc (CLAUDE.md / AGENTS.md) header + one-liner intro. Both
@@ -212,8 +217,12 @@ const PROMPTS = {
     date: (d) => `日期：${d}`,
     dream: '你处于梦境模式。回顾过去的对话，整理和巩固记忆。',
     tools: (names) => `可用工具：${names}`,
-    // DESIGN-PROMPT §3 ④ — Active Scope header
-    activeScopeHeader: '## active_scope',
+    // DESIGN-PROMPT §3 ④ — 当前会话上下文。
+    activeScopeHeader: '## 当前会话上下文',
+    activeScopeSessionIdLabel: '会话 ID',
+    activeScopeMembersLabel: '会话成员',
+    activeScopeTopicsLabel: '当前讨论',
+    activeScopeEnvelopeLabel: '转交消息',
     multiVpRoutingHeader: '## multi_vp_routing',
     sessionAnnouncementHeader: '[会话公告]',
     // 项目文档块：CLAUDE.md / AGENTS.md（与 Codex 通用命名兼容）。
@@ -299,6 +308,7 @@ export function buildSystemPrompt({
   vpPersona,
   sessionAnnouncement = '',
   projectDoc = '',
+  runtimePlatform,
 } = {}) {
   // Normalize app locales like `zh-CN` to prompt dictionary/template keys.
   const effectiveLang = normalizePromptLanguage(language);
@@ -362,7 +372,12 @@ export function buildSystemPrompt({
     parts.push(dreamTemplate || lang.dream);
   }
 
-  // ─── 4. Tools + Tool Guidance ──────────────────────────
+  // ─── 4. Runtime Platform + Tools + Tool Guidance ──────
+  const runtimePlatformBlock = renderRuntimePlatformPrompt(runtimePlatform || getRuntimePlatformInfo(), effectiveLang);
+  if (runtimePlatformBlock) {
+    parts.push(runtimePlatformBlock);
+  }
+
   if (toolNames.length > 0) {
     parts.push(lang.tools(toolNames.join(', ')));
 
@@ -495,20 +510,22 @@ function selectVpPersonaBody(vpPersona, effectiveLang) {
 function renderActiveScope(activeScope, lang) {
   if (!activeScope || typeof activeScope !== 'object') return '';
 
+  const isZh = lang === PROMPTS.zh;
+  const separator = isZh ? '：' : ': ';
   const lines = [];
   const session = typeof activeScope.sessionId === 'string' && activeScope.sessionId.trim()
     ? activeScope.sessionId.trim()
     : '';
-  if (session) lines.push(`session_id: ${session}`);
+  if (session) lines.push(`${lang.activeScopeSessionIdLabel}${separator}${session}`);
 
-  const membersLine = renderSessionMembersLine(activeScope.sessionMembers || activeScope.members);
-  if (membersLine) lines.push(`session_members: ${membersLine}`);
+  const membersLine = renderSessionMembersLine(activeScope.sessionMembers || activeScope.members, isZh);
+  if (membersLine) lines.push(`${lang.activeScopeMembersLabel}${separator}${membersLine}`);
 
-  const topicsLine = renderSessionMembersLine(activeScope.sessionTopics);
-  if (topicsLine) lines.push(`session_topics: ${topicsLine}`);
+  const topicsLine = renderSessionTopicsLine(activeScope.sessionTopics, isZh);
+  if (topicsLine) lines.push(`${lang.activeScopeTopicsLabel}${separator}${topicsLine}`);
 
-  const envLine = renderEnvelopeLine(activeScope.envelope);
-  if (envLine) lines.push(`envelope: ${envLine}`);
+  const envLine = renderEnvelopeLine(activeScope.envelope, isZh);
+  if (envLine) lines.push(`${lang.activeScopeEnvelopeLabel}${separator}${envLine}`);
 
   if (lines.length === 0) return '';
 
@@ -523,8 +540,149 @@ function firstNonEmptyString(...values) {
   return '';
 }
 
-function renderSessionMembersLine(members) {
-  return normalizeSessionMemberIds(members).join(', ');
+function renderSessionMembersLine(members, useChineseSeparator = false) {
+  return normalizeSessionMemberIds(members).join(useChineseSeparator ? '、' : ', ');
+}
+
+function renderSessionTopicsLine(topics, isZh = false) {
+  const descriptions = [];
+  const seen = new Set();
+  for (const topic of normalizeSessionTopicIds(topics)) {
+    const description = describeSessionTopic(topic, isZh);
+    if (!description || seen.has(description)) continue;
+    seen.add(description);
+    descriptions.push(description);
+  }
+  return descriptions.join(isZh ? '；' : '; ');
+}
+
+function normalizeSessionTopicIds(topics) {
+  if (!Array.isArray(topics)) return [];
+  const clean = [];
+  const seen = new Set();
+  for (const topic of topics) {
+    if (typeof topic !== 'string') continue;
+    const id = topic.trim();
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    clean.push(id);
+  }
+  return clean;
+}
+
+function describeSessionTopic(topic, isZh = false) {
+  const normalized = topic.toLowerCase().replace(/[_\s]+/g, '-');
+
+  if (normalized.includes('dream') && normalized.includes('segments')) {
+    return isZh
+      ? '梦境记忆片段的抽取与整理'
+      : 'Dream memory segment extraction and organization';
+  }
+  if (normalized.includes('dream') && normalized.includes('session') && normalized.includes('extraction')) {
+    return isZh
+      ? '梦境会话记忆的抽取质量'
+      : 'Dream session-memory extraction quality';
+  }
+  if (normalized.includes('system-prompt') && normalized.includes('localization')) {
+    return isZh
+      ? '系统提示词的中英文一致性'
+      : 'system prompt language localization';
+  }
+  if (normalized.includes('default-character') && normalized.includes('prompt-soul')) {
+    return isZh
+      ? '默认角色灵魂提示词的表达方式'
+      : 'default persona soul prompt wording';
+  }
+  if (normalized.includes('prompt') && normalized.includes('soul')) {
+    return isZh
+      ? '角色灵魂提示词的表达方式'
+      : 'persona soul prompt wording';
+  }
+  if (normalized.includes('openai-responses')) {
+    return isZh
+      ? 'Yeaft 的 OpenAI Responses 适配与模型配置'
+      : 'Yeaft OpenAI Responses adapter and model configuration';
+  }
+  if (normalized.includes('model-config-isolation')) {
+    return isZh
+      ? 'Yeaft 的模型配置隔离'
+      : 'Yeaft model configuration isolation';
+  }
+  if (normalized.includes('route-forward') || normalized.includes('handoff')) {
+    return isZh
+      ? 'Yeaft 的会话路由交接与可见性'
+      : 'Yeaft session routing handoff and visibility';
+  }
+  if (normalized.includes('copilot-cli') || normalized.includes('chat-session')) {
+    return isZh
+      ? 'Copilot CLI 的聊天会话行为'
+      : 'Copilot CLI chat session behavior';
+  }
+  if (normalized.includes('claude-opus')) {
+    return isZh
+      ? 'Yeaft 的 Claude Opus 模型接入'
+      : 'Yeaft Claude Opus model integration';
+  }
+  if (normalized.includes('pr-workflow')) {
+    return isZh
+      ? '项目的 PR review、merge 和 tag 发布流程'
+      : 'project PR review, merge, and tag release workflow';
+  }
+  if (/\bpr[-/]?\d+\b/.test(normalized) || normalized.includes('release') || /v\d+\.\d+\.\d+/.test(normalized)) {
+    return isZh
+      ? '最近的 PR 修复、review、merge 和 tag 发布流程'
+      : 'recent PR fixes, review, merge, and tag release work';
+  }
+  if (normalized.includes('active-scope')) {
+    return isZh
+      ? '当前会话上下文的提示词呈现'
+      : 'current session context prompt rendering';
+  }
+  if (normalized.includes('prompt') || normalized.includes('system')) {
+    return isZh
+      ? '近期的系统提示词调整'
+      : humanizeTopicSlug(topic, false) || 'recent system prompt work';
+  }
+  if (normalized.includes('dream')) {
+    return isZh
+      ? '近期的 Dream 记忆维护工作'
+      : humanizeTopicSlug(topic, false) || 'recent Dream memory work';
+  }
+  if (normalized.includes('session')) {
+    return isZh
+      ? '近期的会话上下文调整'
+      : humanizeTopicSlug(topic, false) || 'recent session context work';
+  }
+
+  if (isZh) return '近期的项目协作事项';
+  return humanizeTopicSlug(topic, false) || 'recent session collaboration topics';
+}
+
+function humanizeTopicSlug(topic, isZh = false) {
+  if (isZh) return '';
+  const words = topic
+    .replace(/[\/_-]+/g, ' ')
+    .replace(/\bv\d+(?:\.\d+)+\b/gi, '')
+    .replace(/\bpr\s*\d+\b/gi, '')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+  if (words.length === 0) return '';
+
+  const normalizedWords = words.map(word => {
+    const lower = word.toLowerCase();
+    if (lower === 'yeaft') return 'Yeaft';
+    if (lower === 'project') return 'project';
+    if (lower === 'config') return 'configuration';
+    if (lower === 'isolation') return 'isolation';
+    if (lower === 'rendering') return 'rendering';
+    if (lower === 'workflow') return 'workflow';
+    if (lower === 'session') return 'session';
+    if (lower === 'context') return 'context';
+    return word;
+  });
+
+  return normalizedWords.join(' ');
 }
 
 function normalizeSessionMemberIds(members) {
@@ -581,21 +739,21 @@ function renderMultiVpRouting(activeScope, lang) {
  * @param {object|null|undefined} envelope
  * @returns {string}
  */
-function renderEnvelopeLine(envelope) {
+function renderEnvelopeLine(envelope, isZh = false) {
   if (!envelope || typeof envelope !== 'object') return '';
   const segments = [];
   const fromVp = typeof envelope.fromVpId === 'string' && envelope.fromVpId.trim()
     ? envelope.fromVpId.trim()
     : (typeof envelope.senderVpId === 'string' ? envelope.senderVpId.trim() : '');
-  if (fromVp) segments.push(`from=${fromVp}`);
+  if (fromVp) segments.push(`${isZh ? '来自' : 'from'}=${fromVp}`);
   const fromUser = typeof envelope.fromUserId === 'string' && envelope.fromUserId.trim()
     ? envelope.fromUserId.trim()
     : '';
-  if (fromUser) segments.push(`user=${fromUser}`);
+  if (fromUser) segments.push(`${isZh ? '用户' : 'user'}=${fromUser}`);
   const intent = typeof envelope.intent === 'string' && envelope.intent.trim()
     ? envelope.intent.trim()
     : '';
-  if (intent) segments.push(`intent=${intent}`);
+  if (intent) segments.push(`${isZh ? '意图' : 'intent'}=${intent}`);
   return segments.join(' ');
 }
 

package/yeaft/runtime-platform.js

@@ -0,0 +1,103 @@
+/**
+ * runtime-platform.js — Runtime OS/platform facts for prompts and tools.
+ *
+ * Keep OS detection in one place. Tools should read `ctx.runtimePlatform`
+ * instead of guessing from scattered `process.platform` checks.
+ */
+
+const WINDOWS_PLATFORMS = new Set(['win32']);
+const MAC_PLATFORMS = new Set(['darwin']);
+const LINUX_PLATFORMS = new Set(['linux']);
+
+/**
+ * @param {string | undefined | null} platform
+ * @returns {NodeJS.Platform | string}
+ */
+export function normalizePlatform(platform) {
+  const raw = typeof platform === 'string' && platform.trim()
+    ? platform.trim().toLowerCase()
+    : process.platform;
+  if (raw === 'windows') return 'win32';
+  if (raw === 'mac' || raw === 'macos' || raw === 'osx') return 'darwin';
+  return raw;
+}
+
+/**
+ * @param {{ platform?: string, env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {{ command: string, argsPrefix: string[], family: 'powershell' | 'cmd' | 'posix' }}
+ */
+export function resolveDefaultShell(opts = {}) {
+  const platform = normalizePlatform(opts.platform);
+  const env = opts.env || process.env;
+
+  if (WINDOWS_PLATFORMS.has(platform)) {
+    const configured = env.YEAFT_WINDOWS_SHELL || env.PWSH || env.POWERSHELL;
+    const shell = configured || 'powershell.exe';
+    const lower = shell.toLowerCase();
+    if (lower.includes('cmd.exe') || lower.endsWith('cmd')) {
+      return { command: shell, argsPrefix: ['/d', '/s', '/c'], family: 'cmd' };
+    }
+    return {
+      command: shell,
+      argsPrefix: ['-NoLogo', '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command'],
+      family: 'powershell',
+    };
+  }
+
+  return {
+    command: env.SHELL || '/bin/bash',
+    argsPrefix: ['-c'],
+    family: 'posix',
+  };
+}
+
+/**
+ * @param {{ platform?: string, env?: NodeJS.ProcessEnv }} [opts]
+ */
+export function getRuntimePlatformInfo(opts = {}) {
+  const platform = normalizePlatform(opts.platform);
+  const shell = resolveDefaultShell({ platform, env: opts.env });
+  const isWindows = WINDOWS_PLATFORMS.has(platform);
+  const isMacOS = MAC_PLATFORMS.has(platform);
+  const isLinux = LINUX_PLATFORMS.has(platform);
+
+  return Object.freeze({
+    platform,
+    os: isWindows ? 'Windows' : (isMacOS ? 'macOS' : (isLinux ? 'Linux' : platform)),
+    isWindows,
+    isMacOS,
+    isLinux,
+    pathSeparator: isWindows ? '\\' : '/',
+    defaultShell: shell.command,
+    shellFamily: shell.family,
+    shellArgsPrefix: shell.argsPrefix,
+  });
+}
+
+/**
+ * @param {ReturnType<typeof getRuntimePlatformInfo>} info
+ * @param {string} [language]
+ */
+export function renderRuntimePlatformPrompt(info = getRuntimePlatformInfo(), language = 'en') {
+  const shell = info.shellFamily === 'powershell'
+    ? `${info.defaultShell} (PowerShell syntax)`
+    : (info.shellFamily === 'cmd' ? `${info.defaultShell} (cmd.exe syntax)` : `${info.defaultShell} (POSIX shell syntax)`);
+
+  if ((language || '').toLowerCase().startsWith('zh')) {
+    return [
+      '## runtime_platform',
+      `当前 Agent 运行系统：${info.os} (${info.platform})`,
+      `默认命令 shell：${shell}`,
+      `路径分隔符：${info.pathSeparator}`,
+      '生成 Bash 工具命令时必须匹配当前系统；Windows 上优先使用 PowerShell/cmd 语法，不要默认输出 Linux-only 命令。',
+    ].join('\n');
+  }
+
+  return [
+    '## runtime_platform',
+    `Agent OS: ${info.os} (${info.platform})`,
+    `Default command shell: ${shell}`,
+    `Path separator: ${info.pathSeparator}`,
+    'When generating Bash tool commands, match this OS. On Windows, prefer PowerShell/cmd syntax instead of Linux-only commands.',
+  ].join('\n');
+}

package/yeaft/templates/base.md

@@ -76,16 +76,10 @@ You are participating in the current session. Keep the user's context, answer fr
 
 - 使用紧凑的 GitHub 风格 Markdown。
 - 先给结论；不要一句话一段。
-<<<<<<< HEAD
 - 列表用于并列信息，不要把每句话都拆成列表项。
-- 围栏代码块 只用于代码、命令、配置、diff 或日志，并写语言标识。
-- 文件路径用 行内代码，例如 `agent/yeaft/prompts.js`。
-=======
-- 列表用于并列信息，不要把每句话都拆成 bullet。
-- fenced code block 只用于代码、命令、配置、diff 或日志，并写语言标识。
+- 围栏代码块只用于代码、命令、配置、diff 或日志，并写语言标识。
 - 不要把普通说明、摘要、标签、标题、列表或单个词包进 fenced code block。
 - 文件路径、命令、标识符、状态值或短文本用 inline code，不要用 fenced code block。
 - 文件路径用 inline code，例如 `agent/yeaft/prompts.js`。
->>>>>>> origin/main
 - 开发总结用 `改动 / 验证 / 风险` 或等价的简洁结构。
 - 评审用 `结论 / Findings / 验证`。

package/yeaft/templates/common-rules.md

@@ -89,15 +89,10 @@
 - 使用 GitHub 风格 Markdown。
 - 普通说明写成紧凑自然段，不要一句话一段。
 - 并列信息用扁平列表，避免深层嵌套。
-<<<<<<< HEAD
 - 围栏代码块只用于真正的代码、命令、配置、diff、日志或用户需要精确复制的文本，并始终带语言标识。
-- 文件路径用行内代码，例如 `agent/yeaft/prompts.js`。
-=======
-- fenced code block 只用于真正的代码、命令、配置、diff、日志或用户需要精确复制的文本，并始终带语言标识。
 - 不要把普通说明、摘要、标签、标题、列表或单个词包进 fenced code block。
 - 文件路径、命令、标识符、状态值或短文本用 inline code，不要用 fenced code block。
 - 文件路径用 inline code，例如 `agent/yeaft/prompts.js`。
->>>>>>> origin/main
 - 开发完成汇报使用：`改动`、`验证`、`风险 / 下一步`。
 - 评审使用：`结论`、`发现项`、`验证`。
 - 排障在需要时使用：`现象`、`证据`、`修复`、`验证`；简单问题保持更短。

package/yeaft/tools/bash.js

@@ -4,13 +4,15 @@
  * Spawns a child process to run shell commands with timeout, output
  * truncation, working directory support, and cancellation via AbortSignal.
  *
- * Modeled after Claude Code's Bash tool implementation.
+ * The tool name remains Bash for wire compatibility. Internally it uses the
+ * platform default shell: POSIX shell on Linux/macOS, PowerShell/cmd on Windows.
  */
 
 import { defineTool } from './types.js';
 import { spawn } from 'child_process';
 import { existsSync } from 'fs';
 import { resolve } from 'path';
+import { getRuntimePlatformInfo, resolveDefaultShell } from '../runtime-platform.js';
 
 /** Max output size in bytes before truncation (256 KB). */
 const MAX_OUTPUT = 256 * 1024;
@@ -21,18 +23,44 @@ const DEFAULT_TIMEOUT_MS = 120_000;
 /** Max timeout in ms (10 minutes). */
 const MAX_TIMEOUT_MS = 600_000;
 
+/**
+ * @param {string} command
+ * @param {{ runtimePlatform?: object }} opts
+ */
+export function buildShellInvocation(command, opts = {}) {
+  const runtimePlatform = opts.runtimePlatform || getRuntimePlatformInfo();
+  const shell = runtimePlatform.defaultShell
+    ? {
+        command: runtimePlatform.defaultShell,
+        argsPrefix: Array.isArray(runtimePlatform.shellArgsPrefix) ? runtimePlatform.shellArgsPrefix : null,
+        family: runtimePlatform.shellFamily,
+      }
+    : resolveDefaultShell({ platform: runtimePlatform.platform });
+
+  const argsPrefix = Array.isArray(shell.argsPrefix)
+    ? shell.argsPrefix
+    : resolveDefaultShell({ platform: runtimePlatform.platform }).argsPrefix;
+
+  return {
+    command: shell.command,
+    args: [...argsPrefix, command],
+    family: shell.family || runtimePlatform.shellFamily || 'posix',
+  };
+}
+
 /**
  * Run a command in a child process.
  * @returns {Promise<{ stdout: string, stderr: string, exitCode: number, timedOut: boolean }>}
  */
-function runCommand(command, { cwd, timeout, signal }) {
-  return new Promise((resolve, reject) => {
-    const shell = process.env.SHELL || '/bin/bash';
-    const proc = spawn(shell, ['-c', command], {
+function runCommand(command, { cwd, timeout, signal, runtimePlatform }) {
+  return new Promise((resolve) => {
+    const platform = runtimePlatform || getRuntimePlatformInfo();
+    const invocation = buildShellInvocation(command, { runtimePlatform: platform });
+    const proc = spawn(invocation.command, invocation.args, {
       cwd,
       env: { ...process.env, TERM: 'dumb', FORCE_COLOR: '0' },
       stdio: ['ignore', 'pipe', 'pipe'],
-      timeout,
+      detached: !platform.isWindows,
     });
 
     let stdout = '';
@@ -40,6 +68,31 @@ function runCommand(command, { cwd, timeout, signal }) {
     let stdoutTruncated = false;
     let stderrTruncated = false;
     let timedOut = false;
+    let settled = false;
+    let timeoutId = null;
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      if (timeoutId) clearTimeout(timeoutId);
+      resolve(result);
+    };
+
+    const killProcess = () => {
+      try {
+        if (!platform.isWindows && proc.pid) {
+          process.kill(-proc.pid, 'SIGTERM');
+          return;
+        }
+      } catch {
+        // Fall back to killing the shell process below.
+      }
+      try {
+        proc.kill('SIGTERM');
+      } catch {
+        // ignore
+      }
+    };
 
     proc.stdout.on('data', (chunk) => {
       if (stdout.length < MAX_OUTPUT) {
@@ -61,46 +114,41 @@ function runCommand(command, { cwd, timeout, signal }) {
       }
     });
 
-    // Handle abort signal
-    const onAbort = () => {
-      try { proc.kill('SIGTERM'); } catch {}
-      setTimeout(() => {
-        try { proc.kill('SIGKILL'); } catch {}
-      }, 2000);
-    };
+    timeoutId = setTimeout(() => {
+      timedOut = true;
+      killProcess();
+      finish({
+        stdout,
+        stderr: stderr + `\nProcess timed out after ${timeout}ms`,
+        exitCode: 124,
+        timedOut: true,
+      });
+    }, timeout);
+
     if (signal) {
-      if (signal.aborted) { onAbort(); return; }
-      signal.addEventListener('abort', onAbort, { once: true });
+      signal.addEventListener('abort', () => {
+        killProcess();
+      }, { once: true });
     }
 
-    proc.on('close', (code) => {
-      if (signal) signal.removeEventListener('abort', onAbort);
-      resolve({
-        stdout: stdoutTruncated ? stdout + '\n... (output truncated)' : stdout,
-        stderr: stderrTruncated ? stderr + '\n... (stderr truncated)' : stderr,
-        exitCode: code ?? 1,
+    proc.on('close', (code, signalName) => {
+      if (stdoutTruncated) stdout += '\n[Output truncated]';
+      if (stderrTruncated) stderr += '\n[Output truncated]';
+      finish({
+        stdout,
+        stderr,
+        exitCode: timedOut ? 124 : (code ?? (signalName ? 128 : 1)),
         timedOut,
       });
     });
 
     proc.on('error', (err) => {
-      if (signal) signal.removeEventListener('abort', onAbort);
-      if (err.code === 'ETIMEDOUT' || err.killed) {
-        timedOut = true;
-        resolve({
-          stdout,
-          stderr: stderr + `\nProcess timed out after ${timeout}ms`,
-          exitCode: 124,
-          timedOut: true,
-        });
-      } else {
-        resolve({
-          stdout,
-          stderr: `Error spawning process: ${err.message}`,
-          exitCode: 1,
-          timedOut: false,
-        });
-      }
+      finish({
+        stdout,
+        stderr: `Error spawning process: ${err.message}`,
+        exitCode: 1,
+        timedOut: false,
+      });
     });
   });
 }
@@ -109,10 +157,13 @@ export default defineTool({
   name: 'Bash',
   description: `Execute a shell command and return its output.
 
-Use this tool to run CLI commands, scripts, and system operations.
+Use this tool to run CLI commands, scripts, and system operations. The tool name
+is kept as Bash for compatibility; on Windows the command is executed through
+the configured Windows shell (PowerShell by default, or cmd when configured).
 
 Guidelines:
 - Commands run in the working directory (cwd from context)
+- Match command syntax to the Agent OS shown in the runtime_platform prompt
 - Timeout defaults to 2 minutes (max 10 minutes)
 - Large outputs are truncated at 256KB
 - Use absolute paths when possible
@@ -124,7 +175,7 @@ Guidelines:
     properties: {
       command: {
         type: 'string',
-        description: 'The shell command to execute',
+        description: 'The shell command to execute using the Agent OS default shell',
       },
       cwd: {
         type: 'string',
@@ -143,8 +194,9 @@ Guidelines:
     if (!input?.command) return false;
     const cmd = input.command.toLowerCase();
     return cmd.includes('rm ') || cmd.includes('rmdir') ||
+           cmd.includes('remove-item') || cmd.startsWith('del ') || cmd.includes(' del ') ||
            cmd.includes('git reset --hard') || cmd.includes('git clean') ||
-           cmd.includes('dd ') || cmd.includes('mkfs') ||
+           cmd.includes('dd ') || cmd.includes('mkfs') || cmd.includes('format ') ||
            cmd.includes('> /dev/') || cmd.includes('chmod 000');
   },
   async execute(input, ctx) {
@@ -162,12 +214,14 @@ Guidelines:
 
     // Clamp timeout
     const timeout = Math.min(Math.max(timeout_ms || DEFAULT_TIMEOUT_MS, 1000), MAX_TIMEOUT_MS);
+    const runtimePlatform = ctx?.runtimePlatform || getRuntimePlatformInfo();
 
     try {
       const result = await runCommand(command, {
         cwd,
         timeout,
         signal: ctx?.signal,
+        runtimePlatform,
       });
 
       // Format output similar to Claude Code
@@ -176,13 +230,13 @@ Guidelines:
       if (result.stderr) parts.push(`STDERR:\n${result.stderr}`);
       if (result.timedOut) parts.push(`\n(Command timed out after ${timeout}ms)`);
 
-      const output = parts.join('\n') || '(no output)';
-
-      return result.exitCode === 0
-        ? output
-        : `Exit code: ${result.exitCode}\n${output}`;
+      const output = parts.join('\n');
+      if (result.exitCode !== 0) {
+        return `Exit code: ${result.exitCode}\n${output}`;
+      }
+      return output || '(no output)';
     } catch (err) {
-      return JSON.stringify({ error: `Bash execution failed: ${err.message}` });
+      return JSON.stringify({ error: err.message });
     }
   },
 });

package/yeaft/tools/enter-worktree.js

@@ -9,7 +9,7 @@
  */
 
 import { defineTool } from './types.js';
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import { existsSync, mkdirSync } from 'fs';
 import { join, resolve } from 'path';
 import { randomUUID } from 'crypto';
@@ -45,7 +45,7 @@ Returns the worktree path and branch name.`,
 
     // Verify we're in a git repo
     try {
-      execSync('git rev-parse --git-dir', { cwd, stdio: 'pipe' });
+      execFileSync('git', ['rev-parse', '--git-dir'], { cwd, stdio: 'pipe' });
     } catch {
       return JSON.stringify({ error: 'Not in a git repository' });
     }
@@ -75,9 +75,9 @@ Returns the worktree path and branch name.`,
     }
 
     try {
-      // Create worktree with new branch
-      const cmd = `git worktree add -b "${branchName}" "${worktreeDir}" ${baseRef}`;
-      execSync(cmd, { cwd, stdio: 'pipe' });
+      // Create worktree with new branch. Use execFileSync args instead of
+      // shell quoting so Windows drive letters and spaces in paths survive.
+      execFileSync('git', ['worktree', 'add', '-b', branchName, worktreeDir, baseRef], { cwd, stdio: 'pipe' });
 
       return JSON.stringify({
         success: true,

package/yeaft/tools/exit-worktree.js

@@ -8,7 +8,7 @@
  */
 
 import { defineTool } from './types.js';
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import { existsSync } from 'fs';
 import { resolve } from 'path';
 
@@ -66,7 +66,7 @@ unless discard_changes is set to true.`,
       // Check for uncommitted changes
       if (!input.discard_changes) {
         try {
-          const status = execSync('git status --porcelain', {
+          const status = execFileSync('git', ['status', '--porcelain'], {
             cwd: worktreePath,
             encoding: 'utf8',
             stdio: ['pipe', 'pipe', 'pipe'],
@@ -86,7 +86,7 @@ unless discard_changes is set to true.`,
       // Get branch name before removal
       let branchName = null;
       try {
-        branchName = execSync('git rev-parse --abbrev-ref HEAD', {
+        branchName = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
           cwd: worktreePath,
           encoding: 'utf8',
           stdio: ['pipe', 'pipe', 'pipe'],
@@ -95,9 +95,9 @@ unless discard_changes is set to true.`,
         // ignore
       }
 
-      // Remove worktree
-      const forceFlag = input.discard_changes ? ' --force' : '';
-      execSync(`git worktree remove "${worktreePath}"${forceFlag}`, {
+      // Remove worktree. Use argv form so Windows paths with spaces or drive
+      // letters are passed to git unchanged.
+      execFileSync('git', ['worktree', 'remove', ...(input.discard_changes ? ['--force'] : []), worktreePath], {
         cwd: mainCwd,
         stdio: 'pipe',
       });
@@ -105,7 +105,7 @@ unless discard_changes is set to true.`,
       // Remove the branch if it was a yeaft worktree branch
       if (branchName && branchName.startsWith('yeaft-wt/')) {
         try {
-          execSync(`git branch -D "${branchName}"`, {
+          execFileSync('git', ['branch', '-D', branchName], {
             cwd: mainCwd,
             stdio: 'pipe',
           });

package/yeaft/tools/localized-descriptions.js

@@ -0,0 +1,237 @@
+const zh = {
+  Skill: {
+    description: '加载、查看和搜索 Yeaft skill 库中的工作流说明。用于发现某类任务是否已有可复用 skill，或读取指定 skill 的完整内容；不要用它执行普通文件搜索。',
+    parameters: {
+      action: '操作类型：list 列出 skill 元数据，view/load 读取指定 skill，search 按查询词匹配相关 skill。',
+      name: '要读取的 skill 名称，仅在 view/load 时需要。',
+      query: '搜索 skill 时使用的查询词，描述你要解决的任务。',
+      filePath: '读取目录型 skill 的关联文件路径，例如 references/style-guide.md。',
+      category: 'list 时可选的分类过滤条件。',
+    },
+  },
+  EnterWorktree: {
+    description: '为代码开发创建隔离 git worktree 和专用分支。任何功能开发、修 bug、测试性改动都应先进入 worktree，避免污染 main checkout；不要用它做普通目录切换。',
+    parameters: {
+      name: 'worktree 名称，会用于目录名和分支名；应使用有语义的 feat-/fix- 前缀。',
+      base_ref: '新分支基于的 git ref；通常使用 HEAD 或 origin/main。',
+    },
+  },
+  ExitWorktree: {
+    description: '结束一个 git worktree 会话。用于开发完成后保留或删除隔离 worktree；删除有未提交改动的 worktree 前必须确认这些改动不再需要。',
+    parameters: {
+      path: '要退出的 worktree 路径。',
+      action: 'keep 表示保留目录和分支；remove 表示删除 worktree 目录并删除分支。',
+      discard_changes: 'remove 时是否丢弃未提交改动；只有确认改动已提交/合并或明确不需要时才设为 true。',
+    },
+  },
+  AskUser: {
+    description: '向用户提出一个真正阻塞继续推进的问题并等待回答。只在缺少关键信息会导致错误或不安全操作时使用；不要把它当作普通说明或反问。',
+    parameters: {
+      question: '要问用户的具体问题，应说明为什么需要这个信息。',
+      options: '可选答案列表；当用户只需从固定选项中选择时提供。',
+    },
+  },
+  WebSearch: {
+    description: '搜索 Web 获取最新信息。用于查当前文档、版本、新闻、API 变更等训练数据可能过期的内容；已知 URL 应直接用 WebFetch。',
+    parameters: {
+      query: '搜索查询词；对时效性问题应包含年份、产品名或版本号。',
+      limit: '最多返回多少条搜索结果。',
+    },
+  },
+  WebFetch: {
+    description: '抓取并读取指定 URL 的页面或 API 响应。用于阅读文档、文章、PR 页面或接口返回；不要用于本地文件，本地文件请用 FileRead。',
+    parameters: {
+      url: '完整 URL，必须包含 http:// 或 https://。',
+      max_length: '返回内容的最大字符数；页面很大时提高该值或分段读取。',
+      raw: '是否返回原始响应体；读取 API/JSON 时设为 true，普通网页通常设为 false。',
+    },
+  },
+  HistorySearch: {
+    description: '搜索已持久化的历史对话消息。用于找之前的决策、用户偏好、代码片段或上下文；不要用它搜索当前工作区文件。',
+    parameters: {
+      keyword: '大小写不敏感的搜索关键词。',
+      limit: '最多返回多少条结果。',
+    },
+  },
+  Bash: {
+    description: '在 shell 中执行非交互式命令。用于运行测试、git/gh 命令、脚本和确定性诊断；避免交互式程序，不要执行未经用户允许的破坏性命令。',
+    parameters: {
+      command: '要执行的 shell 命令；需要引用文件路径时正确加引号。',
+      cwd: '命令运行目录；代码改动和测试应在对应 worktree 中运行。',
+      timeout_ms: '超时时间毫秒；长测试或构建可适当提高但不能超过工具上限。',
+    },
+  },
+  FileRead: {
+    description: '读取文本文件并带行号返回内容。编辑前必须先读文件；已知路径时直接使用它，不要先用 shell cat。',
+    parameters: {
+      file_path: '要读取的文件路径，可为绝对路径或相对当前工作目录。',
+      offset: '从第几行开始读取，0 基；只有大文件或明确行段时才需要。',
+      limit: '最多读取多少行；普通文件默认整段读取即可。',
+    },
+  },
+  FileWrite: {
+    description: '写入完整文件内容，会创建父目录并覆盖已有文件。适合新建文件或完整重写；修改已有文件时优先用 FileEdit 做小范围替换。',
+    parameters: {
+      file_path: '要写入的文件路径。',
+      content: '完整文件内容，不是补丁或片段。',
+    },
+  },
+  FileEdit: {
+    description: '在已有文件中做精确文本替换。使用前必须读取文件；old_string 必须和文件内容完全一致，除非明确 replace_all，否则必须唯一。',
+    parameters: {
+      file_path: '要编辑的文件路径。',
+      old_string: '要查找并替换的精确文本，必须与文件内容完全一致，包含空格、缩进和换行。',
+      new_string: '替换后的文本。',
+      replace_all: '是否替换所有匹配项；默认只允许唯一匹配，避免误改。',
+    },
+  },
+  Glob: {
+    description: '按 glob 模式查找文件路径。用于只知道文件名模式或扩展名时定位文件；如果要搜内容请用 Grep。',
+    parameters: {
+      pattern: 'glob 模式，例如 **/*.js 或 src/**/*.ts。',
+      path: '搜索起始目录。',
+      limit: '最多返回多少个文件。',
+    },
+  },
+  Grep: {
+    description: '用正则搜索文件内容。用于快速定位符号、错误文本、调用点或配置项；应结合 path、glob 或 type 缩小范围。',
+    parameters: {
+      pattern: '要搜索的正则表达式；特殊字符需要转义。',
+      path: '要搜索的文件或目录。',
+      output_mode: '输出模式：content 显示匹配行，files_with_matches 只列文件，count 显示计数。',
+      glob: '文件名过滤 glob，例如 *.{js,css}。',
+      type: '文件类型过滤，例如 js、py、rust。',
+      case_insensitive: '是否忽略大小写。',
+      context: 'content 模式下每个匹配周围显示的上下文行数。',
+      before: 'content 模式下每个匹配前显示的行数。',
+      after: 'content 模式下每个匹配后显示的行数。',
+      multiline: '是否启用多行正则匹配。',
+      head_limit: '最多返回多少条匹配结果。',
+    },
+  },
+  ListDir: {
+    description: '列出目录内容和文件大小。用于了解目录结构；需要查找模式时用 Glob，需要搜内容时用 Grep。',
+    parameters: {
+      path: '要列出的目录路径。',
+      show_hidden: '是否显示以点开头的隐藏文件。',
+    },
+  },
+  ApplyPatch: {
+    description: '应用 unified diff 补丁到文件。适合一次修改多个位置或创建新文件；补丁必须和当前文件内容匹配，简单替换优先用 FileEdit。',
+    parameters: {
+      patch: '标准 unified diff 内容，包含 ---、+++ 和 @@ hunk。',
+    },
+  },
+  SpawnAgent: {
+    description: '启动一个后台子 Agent 处理独立任务。用于单 VP 场景下的并行调查、测试、评审或长任务；启动后不要阻塞等待，继续主任务，并用 ListAgents 非阻塞查看状态或等待通知回灌。',
+    parameters: {
+      name: '子 Agent 的简短名称，便于识别。',
+      task: '给子 Agent 的明确任务说明。',
+      mission: '任务目标、范围和成功标准。',
+      expected_output: '期望子 Agent 最终交付的结果格式。',
+      persona: '可选人格或工作风格说明。',
+      budget: '子 Agent 的资源预算。',
+      'budget.max_tokens': '允许子 Agent 消耗的最大 token 数。',
+      'budget.max_turns': '允许子 Agent 执行的最大 turn 数。',
+      'budget.wall_time_ms': '最长运行时间毫秒；超时应被标记并终止，避免 running zombie。',
+      cwd: '子 Agent 的工作目录。',
+    },
+  },
+  PromptAgent: {
+    description: '向已存在的子 Agent 追加消息。仅用于继续或补充一个已启动的子 Agent；不要用它替代 SpawnAgent 创建新任务。',
+    parameters: {
+      agent_id: '目标子 Agent id。',
+      message: '发送给子 Agent 的消息。',
+    },
+  },
+  WaitAgent: {
+    description: '兼容用的短轮询工具，用于快速查看某个子 Agent 是否已有结果。不要把它当作主流程循环等待；需要状态时优先用 ListAgents，长任务应后台运行并等待通知。',
+    parameters: {
+      agent_id: '要检查的子 Agent id。',
+      timeout_ms: '最多等待多少毫秒；应保持很短，避免阻塞父 VP。',
+    },
+  },
+  CloseAgent: {
+    description: '关闭子 Agent 并可记录最终结果。用于用户要求停止、任务已被主流程接管、或子 Agent 不再需要时；不要关闭无关 Agent。',
+    parameters: {
+      agent_id: '要关闭的子 Agent id。',
+      result: '可选的最终结果或关闭原因。',
+    },
+  },
+  ListAgents: {
+    description: '非阻塞列出当前 VP 拥有的子 Agent 状态。用于查看后台任务是否 running、stale、completed 或 failed，以及读取结果摘要和输出文件路径。',
+    parameters: {
+      include_closed: '是否包含已关闭的子 Agent。',
+      include_terminal: '是否包含 completed、failed、abandoned 等终态子 Agent。',
+    },
+  },
+  RouteForward: {
+    description: '把当前任务或问题明确转交给同一 Session 中的其他 VP。多 VP 场景下，只要用户点名其他 VP、任务属于其他 VP 职责、需要并行协作、或你需要另一个 VP 继续处理，就必须调用这个工具；在聊天文本里写 @名字 不会真正路由。',
+    parameters: {
+      to: '目标 VP id，或使用 all 广播给其他成员；不能填自己。',
+      text: '要代表你转发给目标 VP 的完整任务内容，必须包含必要上下文和明确期望。',
+      reason: '可选的简短转发理由，用于审计和界面展示。',
+    },
+  },
+  TodoWrite: {
+    description: '维护用户可见的多步骤任务清单。任务包含 3 个以上有意义步骤、用户给了列表、或即将做复杂多文件改动时必须使用；不要为单个琐碎动作制造清单。',
+    parameters: {
+      todos: '完整的当前 todo 列表；每次调用都要发送全量列表，不是增量 diff。',
+      'todos[].content': '命令式步骤描述，例如“运行测试”。',
+      'todos[].status': '步骤状态；任意时刻最多只能有一个 in_progress。',
+      'todos[].activeForm': '该步骤执行中展示的进行时文案，例如“正在运行测试”。',
+    },
+  },
+  StartPlan: {
+    description: '进入规划模式，为非琐碎任务先形成短计划再继续执行。用户要求计划/思考、任务多步骤、范围不清或大型改动前应使用；除非第一步被用户信息阻塞，否则计划后继续推进。',
+    parameters: {
+      topic: '一句话说明正在规划的主题。',
+      userProblem: '用户真正想解决的底层问题，可选。',
+      stuckAt: '当前阻塞点或必须先决策的未知，可选。',
+      expectedScale: '预估规模，例如文件数、代码量或时间范围，可选。',
+      additionalContext: '影响计划的其他事实、约束或背景，可选。',
+    },
+  },
+  JsRepl: {
+    description: '在持久 JavaScript REPL 中执行代码。用于计算、数据转换和快速实验；不能访问文件系统或网络，状态会在多次调用之间保留。',
+    parameters: {
+      code: '要执行的 JavaScript 代码；reset=true 且只清空状态时可省略。',
+      reset: '是否先重置 REPL 上下文再执行代码。',
+    },
+  },
+  JsReplReset: {
+    description: '已废弃的 JavaScript REPL 重置工具。新调用应使用 JsRepl 并设置 reset=true；仅为兼容旧调用保留。',
+    parameters: {},
+  },
+  NotebookEdit: {
+    description: '读取或编辑 Jupyter notebook 单元格。用于 .ipynb 文件的精确 cell 级修改；普通文本文件不要用它。',
+    parameters: {
+      notebook_path: '目标 .ipynb 文件路径。',
+      action: '操作类型：read、replace、insert 或 delete。',
+      cell_index: '单元格索引，0 基。',
+      cell_type: '插入或替换时的单元格类型：code 或 markdown。',
+      source: '插入或替换的单元格源码内容。',
+    },
+  },
+  ImageGeneration: {
+    description: '根据文本描述生成图片并保存到工作目录。用于明确要求生成图像的任务；分析已有图片应使用 ViewImage。',
+    parameters: {
+      prompt: '详细、具体的图片生成描述，包含风格、构图和氛围。',
+      output_path: '生成图片保存路径。',
+      size: '图片尺寸。',
+    },
+  },
+  ViewImage: {
+    description: '读取本地图片文件并附加到对话中供模型分析。用于用户引用本地截图、图表或设计稿时；远程图片 URL 不用它。',
+    parameters: {
+      file_path: '图片文件路径，必须在项目目录或允许访问的目录内。',
+    },
+  },
+};
+
+export const BUILTIN_TOOL_LOCALIZED_DESCRIPTIONS = Object.freeze({ zh: Object.freeze(zh) });
+
+export function getBuiltinToolLocalization(toolName, language) {
+  if (!String(language || '').toLowerCase().startsWith('zh')) return null;
+  return BUILTIN_TOOL_LOCALIZED_DESCRIPTIONS.zh[toolName] || null;
+}

package/yeaft/tools/path-safety.js

@@ -0,0 +1,49 @@
+/**
+ * path-safety.js — Cross-platform path containment helpers for tools.
+ */
+
+import path from 'path';
+
+/**
+ * Return true when child is equal to or inside parent for the supplied path
+ * implementation (`path` on the host, or `path.win32`/`path.posix` in tests).
+ *
+ * @param {string} parent
+ * @param {string} child
+ * @param {{ relative: Function, isAbsolute: Function, resolve: Function }} [pathImpl]
+ */
+export function isPathInsideOrEqual(parent, child, pathImpl = path) {
+  if (!parent || !child) return false;
+  const base = pathImpl.resolve(parent);
+  const target = pathImpl.resolve(child);
+  const rel = pathImpl.relative(base, target);
+  return rel === '' || (!!rel && !rel.startsWith('..') && !pathImpl.isAbsolute(rel));
+}
+
+/**
+ * @param {string} absPath
+ * @param {string} cwd
+ * @param {string[]} [allowlist]
+ * @param {{ relative: Function, isAbsolute: Function, resolve: Function }} [pathImpl]
+ */
+export function checkPathAllowed(absPath, cwd, allowlist = [], pathImpl = path) {
+  if (isPathInsideOrEqual(cwd, absPath, pathImpl)) return null;
+
+  if (Array.isArray(allowlist)) {
+    for (const dir of allowlist) {
+      if (typeof dir !== 'string' || !pathImpl.isAbsolute(dir)) continue;
+      if (isPathInsideOrEqual(dir, absPath, pathImpl)) return null;
+    }
+  }
+
+  const inputWasAbs = pathImpl.isAbsolute(absPath);
+  return inputWasAbs
+    ? {
+        kind: 'absolute_outside_allowlist',
+        message: 'Absolute image paths must be inside the project directory or a ctx.imageAllowlist directory.',
+      }
+    : {
+        kind: 'relative_escape',
+        message: 'Relative image paths may not escape the working directory.',
+      };
+}

package/yeaft/tools/registry.js

@@ -10,6 +10,7 @@
  */
 
 import { formatSize } from '../archive/tool-results.js';
+import { getBuiltinToolLocalization } from './localized-descriptions.js';
 
 /**
  * Collaboration tools are mutually exclusive per Yeaft group shape:
@@ -93,7 +94,37 @@ function localizeVisibleText(value, language, toolName) {
  * is actually a string. Object/array values under a `description` key
  * are sub-schemas and must be recursed into normally.
  */
-function localizeParameters(parameters, language, toolName) {
+function cloneSchema(value) {
+  if (!value || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(cloneSchema);
+  const out = {};
+  for (const [key, child] of Object.entries(value)) out[key] = cloneSchema(child);
+  return out;
+}
+
+function schemaAtPath(schema, path) {
+  const parts = String(path || '').split('.').filter(Boolean);
+  let node = schema;
+  for (const rawPart of parts) {
+    const part = rawPart.endsWith('[]') ? rawPart.slice(0, -2) : rawPart;
+    node = node?.properties?.[part];
+    if (!node) return null;
+    if (rawPart.endsWith('[]')) node = node.items;
+  }
+  return node || null;
+}
+
+function applyParameterOverrides(parameters, overrides) {
+  if (!overrides || !parameters || typeof parameters !== 'object') return parameters;
+  const out = cloneSchema(parameters);
+  for (const [path, description] of Object.entries(overrides)) {
+    const schema = schemaAtPath(out, path);
+    if (schema && typeof description === 'string') schema.description = description;
+  }
+  return out;
+}
+
+function localizeParameters(parameters, language, toolName, parameterOverrides = null) {
   const lang = normalizeLanguage(language);
   if (lang !== 'zh' || !parameters || typeof parameters !== 'object') return parameters;
   if (Array.isArray(parameters)) return parameters.map(v => localizeParameters(v, lang, toolName));
@@ -102,12 +133,12 @@ function localizeParameters(parameters, language, toolName) {
     if (key === 'description' && typeof value === 'string') {
       out[key] = localizeVisibleText(value, lang, toolName);
     } else if (value && typeof value === 'object') {
-      out[key] = localizeParameters(value, lang, toolName);
+      out[key] = localizeParameters(value, lang, toolName, null);
     } else {
       out[key] = value;
     }
   }
-  return out;
+  return applyParameterOverrides(out, parameterOverrides);
 }
 
 /**
@@ -342,11 +373,14 @@ export class ToolRegistry {
     const collabToolPolicy = normalizeCollabToolPolicy(opts?.collabToolPolicy);
     return this.getAllTools()
       .filter(t => !isToolHiddenByCollabPolicy(t.name, collabToolPolicy))
-      .map(t => ({
-        name: t.name,
-        description: localizeVisibleText(t.description, lang, t.name),
-        parameters: localizeParameters(t.parameters, lang, t.name),
-      }));
+      .map(t => {
+        const localized = getBuiltinToolLocalization(t.name, lang);
+        return {
+          name: t.name,
+          description: localized?.description || localizeVisibleText(t.description, lang, t.name),
+          parameters: localizeParameters(t.parameters, lang, t.name, localized?.parameters),
+        };
+      });
   }
 
   /**

package/yeaft/tools/types.js

@@ -14,6 +14,8 @@
  * @typedef {Object} ToolContext
  * @property {AbortSignal} [signal] — cancellation signal
  * @property {string} [yeaftDir] — Yeaft data directory
+ * @property {ReturnType<import('../runtime-platform.js').getRuntimePlatformInfo>} [runtimePlatform]
+ *   — runtime OS/shell facts for platform-aware tools
  * @property {string} [cwd] — working directory
  * @property {import('../mcp.js').MCPManager} [mcpManager] — MCP manager
  * @property {object} [skillManager] — Skill manager

package/yeaft/tools/view-image.js

@@ -27,7 +27,8 @@
 import { defineTool } from './types.js';
 import { stat, readFile } from 'fs/promises';
 import { existsSync } from 'fs';
-import { resolve, extname, isAbsolute, relative } from 'path';
+import { resolve, extname, isAbsolute } from 'path';
+import { checkPathAllowed } from './path-safety.js';
 
 /** Default max image size in bytes (20 MiB). Override via ctx.maxImageBytes. */
 const DEFAULT_MAX_IMAGE_BYTES = 20 * 1024 * 1024;
@@ -109,36 +110,6 @@ function parseImageDimensions(buffer, ext) {
   return null;
 }
 
-/**
- * Check whether `absPath` is allowed given a project `cwd` and an optional
- * allowlist of absolute directories. Returns `null` on success, or an object
- * `{ kind, message }` describing the failure. The `kind` field lets callers
- * tailor the error text (see prev-3 P2: distinguish "absolute path outside
- * project" from "relative path containing ..").
- */
-function checkPathAllowed(absPath, cwd, allowlist) {
-  // Reject if the resolved path lives inside the project (good).
-  const relToCwd = relative(cwd, absPath);
-  const insideCwd = relToCwd && !relToCwd.startsWith('..') && !isAbsolute(relToCwd);
-  if (insideCwd) return null;
-
-  // Otherwise must match an allowlist entry.
-  if (Array.isArray(allowlist) && allowlist.length > 0) {
-    for (const dir of allowlist) {
-      if (typeof dir !== 'string' || !isAbsolute(dir)) continue;
-      const rel = relative(dir, absPath);
-      if (rel && !rel.startsWith('..') && !isAbsolute(rel)) return null;
-    }
-  }
-
-  return {
-    kind: 'path_outside',
-    message:
-      'Path is outside the project directory and not on the image allowlist. ' +
-      'Either move the file into the project, or ask the user to add its parent ' +
-      'directory to ctx.imageAllowlist (set via ~/.yeaft/config.json imageAllowlist[]).',
-  };
-}
 
 function formatBytes(n) {
   if (n < 1024) return `${n}B`;