@yeaft/webchat-agent 1.0.377 → 1.0.378

package/local-runtime/version.json

@@ -1 +1 @@
-{"version":"1.0.377"}
+{"version":"1.0.378"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.377",
+  "version": "1.0.378",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",

package/yeaft/config.js

@@ -351,6 +351,7 @@ function loadLegacyConfig(dir, overrides) {
     proxyUrl: overrides.proxyUrl || env.YEAFT_PROXY_URL || fileConfig.proxyUrl || 'http://localhost:6628',
     baseUrl: overrides.baseUrl || env.YEAFT_BASE_URL || fileConfig.baseUrl || null,
     adapter: overrides.adapter || env.YEAFT_ADAPTER || fileConfig.adapter || null,
+    imageApiUrl: overrides.imageApiUrl || env.YEAFT_IMAGE_API_URL || fileConfig.imageApiUrl || null,
     debug: overrides.debug !== undefined ? overrides.debug
       : env.YEAFT_DEBUG !== undefined ? isTruthy(env.YEAFT_DEBUG)
         : fileConfig.debug !== undefined ? fileConfig.debug : DEFAULTS.debug,
@@ -476,6 +477,7 @@ export function loadConfig(overrides = {}) {
     // General settings
     language: overrides.language || jsonConfig.language || DEFAULTS.language,
     debug: overrides.debug !== undefined ? overrides.debug : (jsonConfig.debug ?? DEFAULTS.debug),
+    imageApiUrl: overrides.imageApiUrl || jsonConfig.imageApiUrl || null,
     dir,
 
     // Token limits. Resolution order:

package/yeaft/engine.js

@@ -24,7 +24,14 @@ import { buildSystemPrompt, buildWorkerPrompt } from './prompts.js';
 import { getRuntimePlatformInfo } from './runtime-platform.js';
 import { LLMContextError, LLMAbortError, LLMAuthError, LLMRateLimitError, LLMServerError, LLMStreamIdleTimeoutError } from './llm/adapter.js';
 import { runMemoryPreflow, buildRelevantScopes, memoryScopeLabel } from './sessions/pre-flow.js';
-import { readProjectDoc, pickProjectDocFile, DEFAULT_PROJECT_DOC_MAX_BYTES } from './sessions/project-doc.js';
+import {
+  readProjectDoc,
+  pickProjectDocFile,
+  selectProjectDocContext,
+  projectDocPathHintsFromToolCall,
+  projectDocWriteScopesNeedingReload,
+  DEFAULT_PROJECT_DOC_MAX_BYTES,
+} from './sessions/project-doc.js';
 import { partitionMessages } from './compact/partition.js';
 import { runCompact as runCompactOrchestrator } from './compact/orchestrator.js';
 import { evaluateCompactTriggers } from './compact/triggers.js';
@@ -45,7 +52,10 @@ import { countTurns } from './turn-utils.js';
 import { attachRouterPlan, extractPriorPlan, stripMetaForWire } from './router/continuity.js';
 import { resolveThinking } from './router/thinking.js';
 import { approxTokens, computeBudget } from './memory/budget.js';
-import { COLLAB_TOOL_POLICY, isToolErrorOutput, normalizeToolOutput, truncateToolResultIfNeeded } from './tools/registry.js';
+import { COLLAB_TOOL_POLICY, isToolErrorOutput, localizeVisibleText, normalizeToolOutput, truncateToolResultIfNeeded } from './tools/registry.js';
+import { CONDITIONAL_BUILTIN_TOOL_NAMES, resolveActiveToolNames } from './tools/activation.js';
+import { discoverToolCapabilities } from './tools/discover-tools.js';
+import { agentBelongsToScope, getAgentRegistry } from './tools/agent.js';
 import { extractDisplayImages, stripDisplayImageData } from './image-assets.js';
 import { acknowledgePendingNotifications, formatNotificationsForPrompt, peekPendingNotifications } from './sub-agent/notifications.js';
 import {
@@ -958,19 +968,22 @@ export class Engine {
   }
 
   /**
-   * Get the list of registered tool definitions (for passing to the adapter).
-   * Prefers ToolRegistry when available, falls back to legacy #tools Map.
-   *
-   * task-297: mode-based filtering was removed — all registered tools are
-   * always exposed to the LLM.
+   * Get the active tool definitions for one provider request. The registry keeps
+   * every implementation and compatibility alias loaded; only the active set is
+   * serialized into the request. Legacy standalone engines keep exposing their
+   * explicitly registered tools because they do not use the built-in registry.
    *
+   * @param {string|null} collabToolPolicy
+   * @param {Set<string>|null} activeToolNames
    * @returns {import('./llm/adapter.js').UnifiedToolDef[]}
    */
-  #getToolDefs(collabToolPolicy = null) {
+  #getToolDefs(collabToolPolicy = null, activeToolNames = null) {
     if (this.#toolRegistry) {
-      return this.#toolRegistry.getToolDefs(this.#config?.language || 'en', { collabToolPolicy });
+      return this.#toolRegistry.getToolDefs(this.#config?.language || 'en', {
+        collabToolPolicy,
+        activeToolNames,
+      });
     }
-    // Legacy path: no mode filtering
     const defs = [];
     for (const [, tool] of this.#tools) {
       defs.push({
@@ -982,6 +995,14 @@ export class Engine {
     return defs;
   }
 
+  #hasScopedSubAgents({ sessionId, parentVpId, parentThreadId } = {}) {
+    const scope = { sessionId, parentVpId, parentThreadId };
+    for (const agent of getAgentRegistry().values()) {
+      if (agentBelongsToScope(agent, scope)) return true;
+    }
+    return false;
+  }
+
   /**
    * Load prompt-facing canonical scope content. Every durable memory scope is
    * query-gated; summary.md remains catalog metadata for Dream triage only.
@@ -1196,7 +1217,7 @@ export class Engine {
    * @param {string} [args.explicitSkillName] — leading /skill:<name> command, if present
    * @returns {string}
    */
-  #buildSystemPrompt({ prompt, memoryInjection, vpPersona, activeScope, sessionAnnouncement, projectInstruction, projectLabel, workCenterInstructions, projectDoc, taskCtx, activeTasks, explicitSkillName, resolvedSkillContent = null } = {}) {
+  #buildSystemPrompt({ prompt, memoryInjection, vpPersona, activeScope, sessionAnnouncement, projectInstruction, projectLabel, workCenterInstructions, projectDoc, taskCtx, activeTasks, activeToolNames = null, promptNotices = [], explicitSkillName, resolvedSkillContent = null } = {}) {
     // Skill selection is normally resolved once by #runQuery so the prompt and
     // emitted protocol events describe the exact same skills. Keep the local
     // fallback for internal callers that do not need selection events.
@@ -1210,10 +1231,15 @@ export class Engine {
       }
     }
 
-    // Get tool names from the appropriate source
-    const toolNames = this.#toolRegistry
+    // Use the same active set for the prompt and provider schema. The prompt
+    // only needs these names to select scoped guidance; it does not repeat the
+    // catalogue because the API tool definitions are already authoritative.
+    const registeredToolNames = this.#toolRegistry
       ? this.#toolRegistry.getToolNames()
       : Array.from(this.#tools.keys());
+    const toolNames = activeToolNames instanceof Set
+      ? registeredToolNames.filter(name => activeToolNames.has(name))
+      : registeredToolNames;
 
     return buildWorkerPrompt({
       language: this.#config.language || 'en',
@@ -1230,6 +1256,7 @@ export class Engine {
       runtimePlatform: getRuntimePlatformInfo(),
       taskCtx,
       activeTasks,
+      promptNotices,
       // Worker-shape harness is descriptive metadata for human inspection;
       // production prompts skip it to save tokens. Re-enable via env when
       // diagnosing prompt structure issues.
@@ -1336,6 +1363,7 @@ export class Engine {
       conversationStore: this.#conversationStore,
       adapter: this.#adapter,
       config: this.#config,
+      discoverTools: vpCtx?.discoverTools,
       taskManager: this.#taskManager,
       sessionId: vpCtx?.sessionId || this.#sessionId || null,
       projectSessionIds: Array.isArray(vpCtx?.projectSessionIds)
@@ -2352,12 +2380,71 @@ export class Engine {
       envelope: inboundEnvelope || null,
     };
 
-    const projectDoc = this.#getProjectDocBlock(workDir);
-    const activeTasks = this.#taskManager
+    const projectDocSource = this.#getProjectDocBlock(workDir);
+    let projectDocLoadedPathHints = [];
+    let projectDocContext = selectProjectDocContext(projectDocSource, {
+      prompt,
+      messages,
+      pathHints: projectDocLoadedPathHints,
+      language: this.#config.language || 'en',
+    });
+    let activeTaskSnapshots = this.#taskManager
+      && typeof this.#taskManager.listActiveTasks === 'function'
+      ? this.#taskManager.listActiveTasks(runtimeSessionId)
+      : [];
+    let activeTasks = this.#taskManager
       ? this.#taskManager.renderActiveTasksForPrompt(runtimeSessionId, {
           language: this.#config.language || 'en',
         })
       : '';
+    const registeredToolNames = this.#toolRegistry
+      ? this.#toolRegistry.getToolNames()
+      : Array.from(this.#tools.keys());
+    const resolveCurrentActiveToolNames = () => this.#toolRegistry
+      ? resolveActiveToolNames({
+          toolNames: registeredToolNames,
+          prompt,
+          messages,
+          collabToolPolicy: effectiveCollabToolPolicy,
+          activeTasks: activeTaskSnapshots,
+          subAgentToolsActivated: this.#hasScopedSubAgents({
+            sessionId: runtimeSessionId,
+            parentVpId: queryVpId,
+            parentThreadId: runtimeThreadId,
+          }),
+          imageGenerationConfigured: typeof this.#config?.imageApiUrl === 'string'
+            && this.#config.imageApiUrl.trim().length > 0,
+        })
+      : null;
+    const discoveredToolNames = new Set();
+    const discoveryTraversals = new Map();
+    const currentDiscoverableTools = () => this.#toolRegistry
+      ? this.#toolRegistry.getAllTools()
+          .filter(tool => CONDITIONAL_BUILTIN_TOOL_NAMES.has(tool.name) || tool.name.startsWith('mcp__'))
+      : [];
+    const discoveryDirectorySnapshot = (tools, language) => tools
+      .map(tool => ({
+        name: tool.name,
+        description: localizeVisibleText(tool.description, language, tool.name),
+        parameters: tool.parameters,
+      }));
+    const discoveryDirectoryMatches = (snapshot, liveTools, language) => {
+      const liveSnapshot = discoveryDirectorySnapshot(liveTools, language);
+      if (snapshot.length !== liveSnapshot.length) return false;
+      const byName = new Map(snapshot.map(tool => [tool.name, tool]));
+      return liveSnapshot.every(tool => {
+        const prior = byName.get(tool.name);
+        return prior
+          && prior.description === tool.description
+          && JSON.stringify(prior.parameters) === JSON.stringify(tool.parameters);
+      });
+    };
+    const applyDiscoveredTools = (names) => {
+      for (const name of names) {
+        if (this.#toolRegistry?.has(name)) discoveredToolNames.add(name);
+      }
+    };
+    let activeToolNames = resolveCurrentActiveToolNames();
     let resolvedSkillContent = '';
     let resolvedSkills = [];
     let skillResolutionError = null;
@@ -2385,7 +2472,8 @@ export class Engine {
       }
     }
 
-    const systemPrompt = this.#buildSystemPrompt({
+    let promptNotices = [];
+    const buildCurrentSystemPrompt = () => this.#buildSystemPrompt({
       prompt,
       memoryInjection,
       vpPersona,
@@ -2394,11 +2482,14 @@ export class Engine {
       projectInstruction,
       projectLabel,
       workCenterInstructions,
-      projectDoc,
+      projectDoc: projectDocContext.text,
       activeTasks,
+      activeToolNames,
+      promptNotices,
       explicitSkillName,
       resolvedSkillContent,
     });
+    let systemPrompt = buildCurrentSystemPrompt();
 
     // ─── HARD INVARIANT: Compact ≠ Dream (read DESIGN-COMPACT-VS-DREAM.md) ─
     // Compact summary (this block) ONLY lands in the messages array head as
@@ -2598,7 +2689,7 @@ export class Engine {
       };
     }
 
-    const toolDefs = this.#getToolDefs(effectiveCollabToolPolicy);
+    let toolDefs = this.#getToolDefs(effectiveCollabToolPolicy, activeToolNames);
     let turnNumber = 0;
     let continueTurns = 0; // auto-continue counter
     let toolLoopTurns = 0; // task-327b: tool-use turns for long-loop auto-bump
@@ -2775,6 +2866,26 @@ export class Engine {
         }
       }
 
+      // Tool availability depends on live Session state. A Bash call can start a
+      // background task (or a sub-agent can appear) during the prior loop, so
+      // recompute the schemas and matching guidance before every provider call.
+      activeTaskSnapshots = this.#taskManager
+        && typeof this.#taskManager.listActiveTasks === 'function'
+        ? this.#taskManager.listActiveTasks(runtimeSessionId)
+        : [];
+      activeTasks = this.#taskManager
+        ? this.#taskManager.renderActiveTasksForPrompt(runtimeSessionId, {
+            language: this.#config.language || 'en',
+          })
+        : '';
+      activeToolNames = resolveCurrentActiveToolNames();
+      for (const name of [...discoveredToolNames]) {
+        if (this.#toolRegistry?.has(name)) activeToolNames?.add(name);
+        else discoveredToolNames.delete(name);
+      }
+      toolDefs = this.#getToolDefs(effectiveCollabToolPolicy, activeToolNames);
+      systemPrompt = buildCurrentSystemPrompt();
+
       try {
         // task-327b: resolve effort per-turn so the long-loop auto-bump
         // kicks in once toolLoopTurns crosses the threshold.
@@ -3826,6 +3937,72 @@ export class Engine {
         setCurrentTodos,
         askUser,
         workDir,
+        discoverTools: ({ query, cursor, maxResults } = {}) => {
+          if (!this.#toolRegistry) return { query: String(query || ''), tools: [], activated: 0 };
+          const language = this.#config.language || 'en';
+          const queryText = String(query || '');
+          const traversalKey = queryText.trim();
+          const liveTools = currentDiscoverableTools();
+          const requestedCursor = Number(cursor);
+          const hasCursor = cursor != null && cursor !== '' && Number.isInteger(requestedCursor) && requestedCursor > 0;
+          let traversal = hasCursor ? discoveryTraversals.get(traversalKey) : null;
+          if (hasCursor && (!traversal || !discoveryDirectoryMatches(traversal.candidates, liveTools, language))) {
+            discoveryTraversals.delete(traversalKey);
+            return {
+              query: queryText,
+              tools: [],
+              next_cursor: null,
+              total: liveTools.length,
+              omitted_invalid: 0,
+              activated: 0,
+              restart_required: true,
+              message: 'The hidden tool directory changed or no matching traversal exists. Restart discovery without a cursor.',
+            };
+          }
+          if (!hasCursor) {
+            traversal = {
+              candidates: discoveryDirectorySnapshot(liveTools, language),
+            };
+            discoveryTraversals.set(traversalKey, traversal);
+          } else {
+            const pendingTraversal = discoveryTraversals.get(traversalKey);
+            if (!pendingTraversal || pendingTraversal.nextCursor !== requestedCursor) {
+              discoveryTraversals.delete(traversalKey);
+              return {
+                query: queryText,
+                tools: [],
+                next_cursor: null,
+                total: liveTools.length,
+                omitted_invalid: 0,
+                activated: 0,
+                restart_required: true,
+                message: 'The discovery cursor is stale or out of sequence. Restart discovery without a cursor.',
+              };
+            }
+          }
+          const result = discoverToolCapabilities({
+            query: queryText,
+            candidates: traversal.candidates,
+            language,
+            cursor,
+            maxResults,
+          });
+          if (result.restart_required || result.next_cursor == null) discoveryTraversals.delete(traversalKey);
+          else traversal.nextCursor = result.next_cursor;
+          applyDiscoveredTools(result.tools.map(tool => tool.name));
+          return {
+            query: queryText,
+            ...result,
+            activated: result.tools.length,
+            message: result.restart_required
+              ? (result.message || 'The hidden tool directory changed. Restart discovery without a cursor.')
+              : (result.tools.length > 0
+                  ? (result.next_cursor == null
+                      ? 'This discovery page is active on the next model loop; the hidden directory is exhausted.'
+                      : 'This discovery page is active on the next model loop; use next_cursor if the target is not listed.')
+                  : 'No valid hidden registered tools remain on this directory page.'),
+          };
+        },
         currentToolCall: () => currentToolCallForAsyncTask ? { ...currentToolCallForAsyncTask } : null,
         requestEndTurn: (reason) => {
           // First call wins — preserve the kind/reason of the first tool
@@ -3921,8 +4098,17 @@ export class Engine {
 
         // Resolve tool: prefer ToolRegistry, fallback to legacy #tools Map
         const hasTool = this.#toolRegistry
-          ? this.#toolRegistry.isAllowed(tc.name, { collabToolPolicy: effectiveCollabToolPolicy })
+          ? this.#toolRegistry.isAllowed(tc.name, {
+              collabToolPolicy: effectiveCollabToolPolicy,
+              activeToolNames,
+            })
           : this.#tools.has(tc.name);
+        const toolProjectDocPathHints = projectDocPathHintsFromToolCall(tc.name, tc.input);
+        const readOnlyTool = hasTool ? isReadOnlyTool(this, tc.name, tc.input) : false;
+        const missingProjectDocScopes = hasTool && !readOnlyTool
+          ? projectDocWriteScopesNeedingReload(projectDocContext, toolProjectDocPathHints)
+          : new Set();
+        const needsProjectDocReload = missingProjectDocScopes.size > 0;
 
         if (skipped) {
           const source = activeToolBatchBarrier.sourceToolName || 'a preceding tool';
@@ -3945,12 +4131,42 @@ export class Engine {
             threadId: this.currentThreadId,
           };
         } else if (!hasTool) {
-          output = `Error: unknown tool "${tc.name}"`;
+          const registered = this.#toolRegistry?.has(tc.name) || this.#tools.has(tc.name);
+          output = registered
+            ? `Error: tool "${tc.name}" is not active for this request`
+            : `Error: unknown tool "${tc.name}"`;
           isError = true;
           yield { type: 'tool_end', id: tc.id, name: tc.name, output, isError: true, threadId: this.currentThreadId };
+        } else if (needsProjectDocReload) {
+          projectDocLoadedPathHints = [...new Set([
+            ...projectDocLoadedPathHints,
+            ...toolProjectDocPathHints,
+          ])];
+          const previouslySelectedProjectDocScopes = new Set(projectDocContext.selectedScopes);
+          projectDocContext = selectProjectDocContext(projectDocSource, {
+            prompt,
+            messages,
+            pathHints: projectDocLoadedPathHints,
+            language: this.#config.language || 'en',
+            forcedScopes: [...previouslySelectedProjectDocScopes, ...missingProjectDocScopes],
+          });
+          const zh = String(this.#config?.language || '').toLowerCase().startsWith('zh');
+          const notice = zh
+            ? `项目规则已针对路径 ${toolProjectDocPathHints.join(', ')} 重新加载。先复核新载入的规则，再重新提交写操作；本次调用未执行。`
+            : `Project rules were reloaded for ${toolProjectDocPathHints.join(', ')}. Review the newly loaded rules before resubmitting the write; this call was not executed.`;
+          promptNotices = [notice];
+          systemPrompt = buildCurrentSystemPrompt();
+          output = notice;
+          isError = true;
+          toolBatchBarrier = {
+            kind: 'project_rules_reloaded',
+            message: notice,
+            sourceToolCallId: tc.id,
+            sourceToolName: tc.name,
+          };
+          yield { type: 'tool_end', id: tc.id, name: tc.name, output, isError: true, skipped: true, threadId: this.currentThreadId };
         } else {
           duplicateKey = `${tc.name}\u001f${argsHashOf(tc.input)}`;
-          const readOnlyTool = isReadOnlyTool(this, tc.name, tc.input);
           cacheableTool = isCacheableTool(this, tc.name, tc.input);
           // The cache is only valid while the workspace has not changed. Clear
           // it before every potential mutation, including a tool that later

package/yeaft/prompts.js

@@ -135,12 +135,10 @@ function extractExactLangSection(content, language) {
 /** Loaded templates — read once at module load time. */
 const RAW_TEMPLATES = {
   base: readTemplate('base.md'),
-  // Phase 8 wire-up: split-out fragments for the persona-as-identity path.
-  // `identityYeaft` ships only when NO VP persona is active. `commonRules`
-  // ships every turn (with persona OR with Yeaft identity) — it carries
-  // output-format, code-editing, search, and frontend rules that are
-  // identity-independent. base.md remains as a back-compat bundle so any
-  // external snapshotter / test that reads the file directly keeps working.
+  core: readTemplate('core.md'),
+  // base.md and the older split fragments remain packaged for external
+  // snapshotters and deployment compatibility. Runtime prompt assembly uses
+  // core.md plus scoped guidance instead of concatenating those full bundles.
   identityYeaft: readTemplate('identity-yeaft.md', { required: false }),
   commonRules: readTemplate('common-rules.md', { required: false }),
   modeUnified: readTemplate('mode-unified.md'),
@@ -195,7 +193,6 @@ const PROMPTS = {
     identity: 'No VP soul is active for this turn. Participate in the current session with grounded, evidence-based answers and preserve the user\'s context.',
     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 ④ — current session context block.
     activeScopeHeader: '## Current session context',
     activeScopeSessionIdLabel: 'Session ID',
@@ -215,13 +212,13 @@ const PROMPTS = {
     // AGENTS.md is the cross-tool convention (Codex / OpenAI Codex CLI).
     projectDocHeader: '[Project Doc]',
     projectDocIntro:
-      'The user keeps project-level instructions and context in `CLAUDE.md` or `AGENTS.md` at the session working directory. Treat the content below as authoritative project context — coding conventions, task guidance, workflow rules, etc.',
+      'The text below is the authoritative project context selected for this turn. It contains the stable core plus any task- or path-scoped sections that the runtime loaded on demand.',
+    promptNoticeHeader: '[Runtime Notice]',
   },
   zh: {
     identity: '你正在当前会话中参与协作。保持用户上下文，回答要基于证据；需要工具时使用工具，但不要把自己没有实际执行过的事说成已经执行。',
     date: (d) => `日期：${d}`,
     dream: '你处于梦境模式。回顾过去的对话，整理和巩固记忆。',
-    tools: (names) => `可用工具：${names}`,
     // DESIGN-PROMPT §3 ④ — 当前会话上下文。
     activeScopeHeader: '## 当前会话上下文',
     activeScopeSessionIdLabel: '会话 ID',
@@ -239,7 +236,8 @@ const PROMPTS = {
     // 项目文档块：CLAUDE.md / AGENTS.md（与 Codex 通用命名兼容）。
     projectDocHeader: '[项目文档]',
     projectDocIntro:
-      '用户把项目级的说明和上下文记录在 session 工作目录下的 `CLAUDE.md` 或 `AGENTS.md` 中。下面的内容是权威的项目上下文 —— 编码规范、任务指导、工作流约定等，请遵循它来工作。',
+      '下面是当前 turn 选中的权威项目上下文，包含稳定核心以及 runtime 按任务或路径加载的范围章节。',
+    promptNoticeHeader: '[运行时提示]',
   },
 };
 
@@ -309,6 +307,7 @@ export function normalizePromptLanguage(language) {
  *   projectLabel?: string,
  *   workCenterInstructions?: string,
  *   projectDoc?: string,
+ *   promptNotices?: string[],
  * }} params
  * @returns {string}
  */
@@ -327,6 +326,7 @@ export function buildSystemPrompt({
   projectDoc = '',
   runtimePlatform,
   activeTasks = '',
+  promptNotices = [],
 } = {}) {
   // Normalize app locales like `zh-CN` to prompt dictionary/template keys.
   const effectiveLang = normalizePromptLanguage(language);
@@ -334,24 +334,16 @@ export function buildSystemPrompt({
 
   const parts = [];
 
-  // ─── 1. Core Identity ──────────────────────────────────
-  // Phase 8 wire-up: when a VP persona is active, the persona body REPLACES
-  // the Yeaft identity block (the LLM is that VP, not Yeaft pretending). When
-  // there is no persona, fall back to the legacy Yeaft identity bundle.
+  // ─── 1. Stable Core ────────────────────────────────────
+  // A VP persona supplies the identity layer when present. The compact core
+  // rules stay stable across turns and replace the old full base/common bundle.
   const personaBlock = renderVpPersona(vpPersona, lang, effectiveLang);
-  if (personaBlock) {
-    parts.push(personaBlock);
-    // Common rules (output format, code editing, search, frontend) still
-    // apply to every turn, regardless of which VP is speaking.
-    const commonRules = getTemplate('commonRules', effectiveLang);
-    if (commonRules) parts.push(commonRules);
-  } else {
-    const baseTemplate = getTemplate('base', effectiveLang);
-    if (baseTemplate) {
-      parts.push(baseTemplate);
-    } else {
-      parts.push(lang.identity);
-    }
+  if (personaBlock) parts.push(personaBlock);
+  const coreTemplate = getTemplate('core', effectiveLang);
+  if (coreTemplate) {
+    parts.push(coreTemplate);
+  } else if (!personaBlock) {
+    parts.push(lang.identity);
   }
 
   // ─── 1.4  Project Doc (CLAUDE.md / AGENTS.md from session workDir) ───
@@ -395,6 +387,13 @@ export function buildSystemPrompt({
     parts.push(`${header}\n${intro ? `${intro}\n\n` : ''}${workCenterText}`);
   }
 
+  const notices = Array.isArray(promptNotices)
+    ? promptNotices.map(value => typeof value === 'string' ? value.trim() : '').filter(Boolean)
+    : [];
+  if (notices.length > 0) {
+    parts.push(`${lang.promptNoticeHeader || '[Runtime Notice]'}\n${notices.join('\n')}`);
+  }
+
   // ─── 2. Date Metadata ──────────────────────────────────
   parts.push(lang.date(new Date().toISOString().split('T')[0]));
 
@@ -414,11 +413,10 @@ export function buildSystemPrompt({
   }
 
   if (toolNames.length > 0) {
-    parts.push(lang.tools(toolNames.join(', ')));
-
+    const guidance = renderActiveToolGuidance(toolNames, effectiveLang);
     const toolGuidanceTemplate = getTemplate('toolGuidance', effectiveLang);
-    if (toolGuidanceTemplate) {
-      parts.push(toolGuidanceTemplate);
+    if (guidance && toolGuidanceTemplate) {
+      parts.push(toolGuidanceTemplate.replace('{{guidance}}', guidance));
     }
   }
 
@@ -457,6 +455,59 @@ export function buildSystemPrompt({
 
 // ─── helpers ─────────────────────────────────────────────────────
 
+const TOOL_GUIDANCE_GROUPS = Object.freeze([
+  {
+    tools: ['DiscoverTools'],
+    en: 'If the visible tools do not clearly cover the request, use `DiscoverTools` with the user goal before concluding that a capability is unavailable. If the target is absent from a page, follow `next_cursor` until found or the hidden directory is exhausted. If `restart_required` is true, restart without a cursor because the registered directory changed.',
+    zh: '如果可见工具不能明确覆盖请求，应先按用户目标调用 `DiscoverTools`。若当前页没有目标，应按 `next_cursor` 继续翻页，直到找到或隐藏目录耗尽后，才能判断某项能力不可用。如果 `restart_required` 为 true，说明注册目录已变化，应丢弃游标重新开始。',
+  },
+  {
+    tools: ['FileRead', 'FileWrite', 'FileEdit', 'Glob', 'Grep', 'ListDir', 'ApplyPatch', 'NotebookEdit'],
+    en: 'Read existing files before editing. Use dedicated file/search tools instead of shell search or `sed -i`; make small, reviewable edits and batch independent reads.',
+    zh: '编辑前先读现有文件。文件搜索和修改优先使用专用工具，不用 shell 搜索或 `sed -i`；改动保持小而可审查，独立读取应并行发出。',
+  },
+  {
+    tools: ['Bash'],
+    en: 'Use non-interactive, deterministic shell commands, set reasonable timeouts, quote paths with spaces, and do not run destructive operations without authorization.',
+    zh: 'Shell 命令保持非交互、确定性并设置合理 timeout；包含空格的路径要引用，未经授权不要执行破坏性操作。',
+  },
+  {
+    tools: ['StartPlan', 'TodoWrite'],
+    en: 'For non-trivial multi-step work, use `StartPlan` before execution and keep the visible `TodoWrite` checklist current; do not stop after planning unless user input genuinely blocks the first step.',
+    zh: '非平凡多步骤任务在执行前使用 `StartPlan`，并持续更新可见的 `TodoWrite` checklist；只有用户信息确实阻塞第一步时才在规划后停下。',
+  },
+  {
+    tools: ['SpawnAgent', 'PromptAgent', 'WaitAgent', 'CloseAgent', 'ListAgents'],
+    en: 'Delegate only independent, bounded work. Keep ownership in the parent, avoid polling loops, and close sub-agents after collecting their result.',
+    zh: '只委派边界清晰且独立的工作。父级保留任务所有权，不要循环轮询，取得结果后关闭子 Agent。',
+  },
+  {
+    tools: ['ListTasks', 'ReadTaskLog', 'CancelTask'],
+    en: 'Treat background tasks as live execution state, not memory facts. Inspect status or logs before retrying or cancelling work.',
+    zh: '后台任务是实时执行状态，不是记忆事实。重试或取消前先检查状态或日志。',
+  },
+  {
+    tools: ['RouteForward'],
+    en: 'Use `RouteForward` for explicit VP-to-VP handoff; writing an @mention in ordinary text does not dispatch another VP.',
+    zh: '显式 VP 转交必须使用 `RouteForward`；普通文本中的 @mention 不会调度另一个 VP。',
+  },
+  {
+    tools: ['CreateWorkItem'],
+    en: 'Use `CreateWorkItem` only for goals that need durable cross-turn coordination, recovery, review, waiting, or retry.',
+    zh: '只有目标需要跨 turn 持久协调、恢复、评审、等待或重试时才使用 `CreateWorkItem`。',
+  },
+]);
+
+function renderActiveToolGuidance(toolNames, language) {
+  const active = new Set(Array.isArray(toolNames) ? toolNames : []);
+  const lines = [];
+  for (const group of TOOL_GUIDANCE_GROUPS) {
+    if (!group.tools.some(name => active.has(name))) continue;
+    lines.push(`- ${language === 'zh' ? group.zh : group.en}`);
+  }
+  return lines.join('\n');
+}
+
 /**
  * Render the VP identity block when the engine is running on behalf of an
  * addressed VP. The `persona` body from role.md is the only soul source;