@yeaft/webchat-agent 1.0.454 → 1.0.456

package/local-runtime/version.json

@@ -1 +1 @@
-{"version":"1.0.454"}
+{"version":"1.0.456"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.454",
+  "version": "1.0.456",
   "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/debug-trace.js

@@ -1025,6 +1025,7 @@ function traceToolToLegacy(trace, tool) {
     tool_call_id: tool.toolCallId || null,
     duration_ms: tool.durationMs || 0,
     is_error: tool.isError ? 1 : 0,
+    suppressed: !!tool.suppressed,
     created_at: tool.createdAt || trace.openedAt || 0,
   };
 }
@@ -1305,7 +1306,15 @@ export class DebugTrace {
     this.#appendTraceRecord(trace, 'loop', loop, { writeMeta: !trace.active });
   }
 
-  logTool(turnId, { toolName, toolCallId = null, toolInput = null, toolOutput = null, durationMs = null, isError = false } = {}) {
+  logTool(turnId, {
+    toolName,
+    toolCallId = null,
+    toolInput = null,
+    toolOutput = null,
+    durationMs = null,
+    isError = false,
+    suppressed = false,
+  } = {}) {
     const id = randomUUID();
     const ctx = this.#turnIndex.get(turnId);
     if (!ctx) return id;
@@ -1322,6 +1331,7 @@ export class DebugTrace {
       toolOutput: truncateText(toolOutput == null ? null : String(toolOutput), this.#textMaxBytes),
       durationMs: Number(durationMs || 0),
       isError: !!isError,
+      suppressed: !!suppressed,
       createdAt: Date.now(),
     };
     trace.tools.push(tool);

package/yeaft/engine.js

@@ -2420,6 +2420,11 @@ export class Engine {
     let lastT1AtToolCount = 0;
     let arcStartIdx = turnStartIdx + 1;
     let t1CollapsesDone = 0;
+    // Duplicate policy is scoped to one user query. Only successful, real
+    // executions increment these counters; errors and cache reuse do not.
+    const queryDuplicateCounts = new Map();
+    const queryDuplicateSuppressions = new Map();
+    let duplicateReminderAwaitingResponse = false;
     const queryNumber = (this.#__queryCounter = (this.#__queryCounter || 0) + 1);
 
     // feat-6af5f9f1 PR B: a Turn = one user prompt + all AI responses.
@@ -2894,7 +2899,7 @@ export class Engine {
             commitDispatch();
           },
         });
-        yield { type: 'turn_start', turnNumber, threadId };
+        yield { type: 'turn_start', turnId: queryTurnId, turnNumber, threadId };
 
         // Provider iteration begins after the visible boundary. Native adapters
         // commit in onRequestStart immediately before fetch. A plain legacy
@@ -3546,6 +3551,23 @@ export class Engine {
       fullResponseText += responseText;
 
       // ─── Handle max_tokens → auto-continue ────────────
+      // A suppressed call leaves a synthetic reminder as the latest user
+      // message. Some models answer it with an empty end_turn. Continue exactly
+      // once so suppression cannot silently abandon the user's task.
+      if (duplicateReminderAwaitingResponse) {
+        if (responseText.trim() || toolCalls.length > 0) {
+          duplicateReminderAwaitingResponse = false;
+        } else {
+          duplicateReminderAwaitingResponse = false;
+          conversationMessages.push({
+            role: 'user',
+            content: '[system note] The duplicate tool call was suppressed, but the current user task is still active. Continue toward the requested outcome using the prior result or a different action; do not end the turn solely because the duplicate was blocked.',
+          });
+          yield { type: 'turn_end', turnNumber, stopReason: 'duplicate_tool_continue', threadId };
+          continue;
+        }
+      }
+
       if (stopReason === 'max_tokens' && continueTurns < MAX_CONTINUE_TURNS) {
         continueTurns++;
         // This synthetic continuation is part of the model-visible protocol.
@@ -3922,6 +3944,16 @@ export class Engine {
       let abortedDuringTools = false;
       /** @type {string[]} */
       const pendingDupReminders = [];
+      let terminateAfterDuplicateBatch = false;
+      const duplicatePolicyForCall = (toolCall) => {
+        const toolDef = this.#toolRegistry
+          ? this.#toolRegistry.get(toolCall.name)
+          : this.#tools.get(toolCall.name);
+        const requested = typeof toolDef?.duplicateCallPolicy === 'function'
+          ? toolDef.duplicateCallPolicy(toolCall.input)
+          : 'warn';
+        return ['allow', 'warn', 'suppress'].includes(requested) ? requested : 'warn';
+      };
       /**
        * Completed executions waiting for their original-order commit. Starting
        * a bounded read-only segment together removes wall-clock latency without
@@ -3977,6 +4009,7 @@ export class Engine {
 
         if (!preparedParallelExecution && !toolBatchBarrier && !signal?.aborted
             && toolAllowedForRequest(tc) && isConcurrencySafeTool(this, tc.name, tc.input)
+            && duplicatePolicyForCall(tc) !== 'suppress'
             && !mayMutateWorkspaceAfterReturn(this, tc.name, tc.input)) {
           const parallelCalls = [];
           const segmentCacheKeys = new Set();
@@ -3986,6 +4019,7 @@ export class Engine {
             const candidate = toolCalls[candidateIndex];
             if (!toolAllowedForRequest(candidate)
                 || !isConcurrencySafeTool(this, candidate.name, candidate.input)
+                || duplicatePolicyForCall(candidate) === 'suppress'
                 || mayMutateWorkspaceAfterReturn(this, candidate.name, candidate.input)) break;
             const candidateKey = `${candidate.name}\u001f${argsHashOf(candidate.input)}`;
             const candidateCacheable = isCacheableTool(this, candidate.name, candidate.input);
@@ -4048,36 +4082,14 @@ export class Engine {
           || (activeToolBatchBarrier != null && !readyParallelExecution);
         const toolStartTime = readyParallelExecution?.startedAt || Date.now();
 
-        // PR-L: duplicate-call detection. If this exact (toolName,
-        // argsHash) pair has already been executed DUP_TOOL_THRESHOLD
-        // (3) times within the current turn + last 2 turns, queue a
-        // system reminder. We push the reminder AFTER the tool batch
-        // completes (not now) so the
-        // assistant(tool_use) → user(tool_result, …) pairing demanded
-        // by the Anthropic / OpenAI Responses APIs stays intact. We
-        // don't block the call — the LLM still decides.
-        if (!skipped) {
-          const dupHash = argsHashOf(tc.input);
-          // PR-L follow-up: lookback is by user-conversation turn
-          // (`queryNumber`), NOT by inner adapter loop iteration. Each call
-          // to query() bumps queryNumber once, so "last 2 turns" means the
-          // current user turn + the previous two user turns — the natural
-          // semantic for "the model is stuck in a loop across the
-          // conversation."
-          const dupInfo = this.#execLog.dupInfo({
-            toolName: tc.name,
-            argsHash: dupHash,
-            currentTurn: queryNumber,
-            lookbackTurns: 2,
-          });
-          if (dupInfo.count + 1 >= DUP_TOOL_THRESHOLD) {
-            pendingDupReminders.push(buildDuplicateReminder({
-              toolName: tc.name,
-              count: dupInfo.count + 1,
-              lastResultBrief: dupInfo.lastResultBrief,
-            }));
-          }
-        }
+        const dupHash = argsHashOf(tc.input);
+        const duplicateCallKey = `${tc.name}:${dupHash}`;
+        const duplicateCallPolicy = duplicatePolicyForCall(tc);
+        const successfulDuplicateCount = queryDuplicateCounts.get(duplicateCallKey) || 0;
+        const duplicateCallSuppressed = !skipped
+          && duplicateCallPolicy === 'suppress'
+          && successfulDuplicateCount >= DUP_TOOL_THRESHOLD - 1;
+        let suppressionCount = queryDuplicateSuppressions.get(duplicateCallKey) || 0;
 
         let output;
         let displayImages = [];
@@ -4179,6 +4191,24 @@ export class Engine {
             sourceToolName: tc.name,
           };
           yield { type: 'tool_end', id: tc.id, name: tc.name, output, isError: true, skipped: true, threadId: this.currentThreadId };
+        } else if (duplicateCallSuppressed) {
+          suppressionCount += 1;
+          queryDuplicateSuppressions.set(duplicateCallKey, suppressionCount);
+          const dupInfo = this.#execLog.dupInfo({
+            toolName: tc.name,
+            argsHash: dupHash,
+            currentTurn: queryNumber,
+            lookbackTurns: 0,
+          });
+          pendingDupReminders.push(buildDuplicateReminder({
+            toolName: tc.name,
+            count: successfulDuplicateCount + suppressionCount,
+            lastResultBrief: dupInfo.lastResultBrief,
+          }));
+          if (suppressionCount >= DUP_TOOL_THRESHOLD) terminateAfterDuplicateBatch = true;
+          output = `Suppressed duplicate call: ${tc.name} returned a stable result twice with these arguments in this turn. Reuse the previous result or choose a different action.`;
+          yield { type: 'tool_start', id: tc.id, name: tc.name, input: tc.input, threadId: this.currentThreadId };
+          yield { type: 'tool_end', id: tc.id, name: tc.name, output, isError: false, suppressed: true, threadId: this.currentThreadId };
         } else {
           duplicateKey = `${tc.name}\u001f${argsHashOf(tc.input)}`;
           cacheableTool = isCacheableTool(this, tc.name, tc.input);
@@ -4280,6 +4310,24 @@ export class Engine {
 
         currentToolCallForAsyncTask = null;
 
+        if (!skipped && !duplicateCallSuppressed && !isError && !reusedReadOnlyResult
+            && duplicateCallPolicy !== 'allow') {
+          const nextDuplicateCount = successfulDuplicateCount + 1;
+          queryDuplicateCounts.set(duplicateCallKey, nextDuplicateCount);
+          if (duplicateCallPolicy === 'warn' && nextDuplicateCount === DUP_TOOL_THRESHOLD) {
+            const dupInfo = this.#execLog.dupInfo({
+              toolName: tc.name,
+              argsHash: dupHash,
+              currentTurn: queryNumber,
+              lookbackTurns: 0,
+            });
+            pendingDupReminders.push(buildDuplicateReminder({
+              toolName: tc.name,
+              count: nextDuplicateCount,
+              lastResultBrief: dupInfo.lastResultBrief,
+            }));
+          }
+        }
         const toolDurationMs = readyParallelExecution?.durationMs ?? (Date.now() - toolStartTime);
 
         // feat-6af5f9f1 PR B: emit a structured `tool_exec` event for the
@@ -4294,6 +4342,7 @@ export class Engine {
           name: tc.name,
           durationMs: toolDurationMs,
           isError,
+          suppressed: duplicateCallSuppressed,
           toolOutput: output,
           ...(reusedReadOnlyResult ? { reused: true, reusedCallId: reusedReadOnlyCallId } : {}),
           ...(skipped ? { skipped: true } : {}),
@@ -4303,7 +4352,8 @@ export class Engine {
         // 2026-05-13: feed the per-tool counters. Stays best-effort — a
         // stats sink that throws shouldn't crash the engine. `record`
         // already swallows internal write errors.
-        if (!skipped && this.#toolStats && typeof this.#toolStats.record === 'function') {
+        if (!skipped && !duplicateCallSuppressed
+            && this.#toolStats && typeof this.#toolStats.record === 'function') {
           try {
             this.#toolStats.record({
               name: tc.name,
@@ -4322,15 +4372,17 @@ export class Engine {
           toolOutput: output,
           durationMs: toolDurationMs,
           isError,
+          suppressed: duplicateCallSuppressed,
           skipped,
           reused: reusedReadOnlyResult,
           reusedCallId: reusedReadOnlyCallId,
         });
 
-        if (!skipped && !reusedReadOnlyResult && tc.name === 'StartPlan') {
+        if (!skipped && !duplicateCallSuppressed && !reusedReadOnlyResult && tc.name === 'StartPlan') {
           planBootstrapPending = true;
         }
-        if (!skipped && !reusedReadOnlyResult && !readOnlyToolReuseDisabled && cacheableTool) {
+        if (!skipped && !duplicateCallSuppressed && !reusedReadOnlyResult
+            && !readOnlyToolReuseDisabled && cacheableTool) {
           readOnlyToolResults.set(duplicateKey, {
             output,
             isError,
@@ -4372,7 +4424,7 @@ export class Engine {
         // user-conversation turn), not the inner loop's turnNumber.
         // Aligns exec-log layout with dup detection lookback and the
         // T2 fallback-stub readTurn() call below.
-        if (!skipped) {
+        if (!skipped && !duplicateCallSuppressed) {
           this.#execLog.append(queryNumber, buildExecLogEntry({
             loopIdx: queryToolCount,
             toolName: tc.name,
@@ -4392,6 +4444,23 @@ export class Engine {
       for (const reminder of pendingDupReminders) {
         conversationMessages.push({ role: 'user', content: reminder });
       }
+      if (pendingDupReminders.length > 0) duplicateReminderAwaitingResponse = true;
+      if (terminateAfterDuplicateBatch) {
+        yield {
+          type: 'error',
+          error: 'Terminated repeated duplicate tool calls after bounded suppression attempts.',
+          code: 'duplicate_tool_loop',
+          retryable: false,
+        };
+        yield {
+          type: 'turn_end',
+          turnNumber,
+          stopReason: 'duplicate_tool_loop',
+          threadId,
+          terminal: true,
+        };
+        break;
+      }
 
       // A plan bootstrap that produced only a TodoWrite has no executable work
       // to feed back to the provider. Close it here. This is intentionally

package/yeaft/personas.js

@@ -37,12 +37,12 @@ let cached = null;
  * @returns {{ meta: object, body: string }}
  */
 export function parseFrontmatter(source) {
-  const match = source.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
   if (!match) return { meta: {}, body: source };
 
   const [, yaml, body] = match;
   const meta = {};
-  const lines = yaml.split('\n');
+  const lines = yaml.split(/\r?\n/);
   let currentKey = null;
   let currentList = null;
 

package/yeaft/prompts.js

@@ -462,8 +462,8 @@ const TOOL_GUIDANCE_GROUPS = Object.freeze([
   },
   {
     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`；改动保持小而可审查，独立读取应并行发出。',
+    en: 'Read existing files before editing. Use dedicated file/search tools instead of shell search or `sed -i`; make small, reviewable edits. Parallelize only proven-independent reads under the accuracy-first rule above.',
+    zh: '编辑前先读现有文件。文件搜索和修改优先使用专用工具，不用 shell 搜索或 `sed -i`；改动保持小而可审查。只有明确满足上述准确性优先判据的读取才可并行。',
   },
   {
     tools: ['Bash'],
@@ -472,13 +472,13 @@ const TOOL_GUIDANCE_GROUPS = Object.freeze([
   },
   {
     tools: ['TodoWrite'],
-    en: 'For non-trivial multi-step work, write a brief visible plan and call `TodoWrite` in the same assistant response as the first independent work tools. Do not spend a separate model round entering planning mode, and do not stop after planning unless user input genuinely blocks the first step.',
-    zh: '非平凡多步骤任务先写简短可见计划，并在同一个 assistant response 中把 `TodoWrite` 与第一批独立工作工具一起发出。不要用单独的模型回合进入规划模式；只有用户信息确实阻塞第一步时才在规划后停下。',
+    en: 'For non-trivial multi-step work, write a brief visible plan and call `TodoWrite` in the same assistant response as the first necessary work-tool call only when its arguments and safety do not depend on another result. Start with the smallest such call; do not speculative-batch the investigation or stop after planning unless user input genuinely blocks the first step.',
+    zh: '非平凡多步骤任务先写简短可见计划。只有第一个工作工具调用已经确定有必要，且其参数和安全性都不依赖其他结果时，才在同一个 assistant response 中把它与 `TodoWrite` 一起发出；先执行满足条件的最小调用，不要推测性批量展开调查。只有用户信息确实阻塞第一步时才在规划后停下。',
   },
   {
     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。',
+    en: 'Delegate only independent, bounded work. Keep ownership in the parent. After PromptAgent queues follow-up work, call WaitAgent in the same parent turn and collect the reply before ending. If a bounded wait times out, wait again with a larger bound unless the agent is stale/stalled. Relay the reply or continue the dependent work, then close the sub-agent when it is no longer needed.',
+    zh: '只委派边界清晰且独立的工作。父级保留任务所有权。PromptAgent 排队后续工作后，必须在同一个父级 turn 调用 WaitAgent 并拿到回复再结束；有界等待超时后，除非 Agent 已 stale/stalled，否则使用更大上限继续等待；随后转述结果或继续依赖该结果的工作，不再需要时关闭子 Agent。',
   },
   {
     tools: ['ListTasks', 'ReadTaskLog', 'CancelTask'],
@@ -500,6 +500,11 @@ const TOOL_GUIDANCE_GROUPS = Object.freeze([
 function renderActiveToolGuidance(toolNames, language) {
   const active = new Set(Array.isArray(toolNames) ? toolNames : []);
   const lines = [];
+  if (active.size > 0) {
+    lines.push(language === 'zh'
+      ? '- 准确性优先：先用能解决当前未知的最小定向调用。只有每个调用都已经确定有必要，且其参数和安全性都不依赖同批其他结果时，才在一个响应中发出多个工具调用；否则串行执行。不要推测性扇出、重复成功的读取/搜索，也不要默认抓取多个来源；先检查证据，再决定是否扩展。'
+      : '- Accuracy first: start with the smallest targeted call that can resolve the current uncertainty. Issue multiple tool calls in one response only when every call is already necessary and its arguments and safety do not depend on another call\'s result. Otherwise run them sequentially. Do not fan out speculatively, repeat a successful read/search, or fetch multiple sources by default; inspect evidence before expanding.');
+  }
   for (const group of TOOL_GUIDANCE_GROUPS) {
     if (!group.tools.some(name => active.has(name))) continue;
     lines.push(`- ${language === 'zh' ? group.zh : group.en}`);

package/yeaft/sub-agent/liveness.js

@@ -117,7 +117,14 @@ export function diagnoseAgentLiveness(agent, opts = {}) {
     : DEFAULT_STALL_THRESHOLD_MS;
   const liveness = snapshotLiveness(agent?.liveness, now);
   const fallbackAt = agent?.createdAt || agent?.usage?.startedAt || null;
-  const activityAt = liveness.lastEventAt || fallbackAt;
+  // Queueing a PromptAgent continuation starts a new collection window. Do not
+  // diagnose that fresh follow-up as stale merely because the retained child
+  // last emitted an event during an older turn.
+  const activityAt = Math.max(
+    liveness.lastEventAt || 0,
+    fallbackAt || 0,
+    agent?.promptReplyPendingAt || 0,
+  ) || null;
   const msSinceActivity = activityAt ? Math.max(0, now - activityAt) : null;
   const stale = agent?.status === 'running'
     && msSinceActivity !== null

package/yeaft/templates/personas/explorer.md

@@ -19,7 +19,7 @@ You are a fast, read-only **Explorer** sub-agent. Your job is to scout the codeb
 ## Operating Principles
 
 - **Read-only**: Never modify files, run bash, or spawn agents.
-- **Be fast**: Use `Grep` / `Glob` / `ListDir` to narrow the search, then `Read` only the needed ranges.
+- **Be targeted**: Use one focused `Grep` / `Glob` / `ListDir` call to narrow the search, inspect it, then `Read` only the ranges still needed. Do not speculative-batch alternative searches.
 - **Be specific**: Return concrete file paths, line numbers, and short excerpts.
 - **Respect the contract**: Match your output to the `expected_output` schema exactly.
 
@@ -36,7 +36,7 @@ Structured. Bullet points. File paths as backticked references with `path:line`.
 ## 操作原则
 
 - **只读**：不要修改文件，不要运行 bash，不要派生 Agent。
-- **要快**：先用 `Grep` / `Glob` / `ListDir` 缩小范围，再只 `Read` 必要行段。
+- **要定向**：先执行一个聚焦的 `Grep` / `Glob` / `ListDir` 调用缩小范围，检查结果后再只 `Read` 仍然必要的行段。不要推测性批量发出备选搜索。
 - **要具体**：返回明确的文件路径、行号和短摘录。
 - **遵守契约**：输出必须严格匹配 `expected_output` schema。
 

package/yeaft/templates/personas/researcher.md

@@ -18,7 +18,7 @@ You are a **Researcher** sub-agent. Your job is to gather information from the w
 ## Operating Principles
 
 - **Cite sources**: Every factual claim must link back to a URL or doc path.
-- **Triangulate**: Prefer multiple independent sources over one.
+- **Validate proportionally**: Start with the most authoritative relevant source. Add another source only when the claim is consequential, disputed, stale, or not established by the first source; do not fetch multiple sources by default.
 - **Summarize**: Return digest-form findings, not raw dumps.
 - **Track freshness**: Note publication dates when recency matters.
 
@@ -35,7 +35,7 @@ Short synthesis first, then bulleted sources with one-line summaries. No filler.
 ## 操作原则
 
 - **引用来源**：每个事实性判断都必须能回链到 URL 或文档路径。
-- **交叉验证**：优先使用多个独立来源，而不是只依赖一个来源。
+- **按风险验证**：先查最权威、最相关的来源。只有结论影响重大、存在争议、可能过时，或首个来源不能证明时才增加来源；不要默认抓取多个来源。
 - **做综合**：返回摘要式发现，不要倾倒原始材料。
 - **关注时效**：当新旧会影响判断时，标明发布时间。
 

package/yeaft/templates/plan-instruction.md

@@ -17,7 +17,7 @@ You have just entered **planning mode** for the topic below. Your job is to thin
 
 1. Write a short prose plan: problem, approach, risks.
 2. Call `TodoWrite` with the ordered steps. Mark exactly one item as `in_progress`.
-3. If the first-step tools and arguments are already known, emit `TodoWrite` and those independent tool calls in the same assistant response. Otherwise wait only for a result that genuinely determines the next action.
+3. Emit `TodoWrite` with a first work-tool call in the same assistant response only when that call is already necessary and its arguments and safety do not depend on another result. Start with the smallest such call. If its result can change the next action, inspect it before issuing more calls; do not speculative-batch the investigation.
 
 If the first step is to ask the user a blocking question, ask it and stop. Otherwise keep moving.
 
@@ -40,6 +40,6 @@ If the first step is to ask the user a blocking question, ask it and stop. Other
 
 1. 写一段简短计划：问题、方案、风险。
 2. 调用 `TodoWrite` 写入有序步骤，并且只能把一个条目标记为 `in_progress`。
-3. 如果第一步所需的工具和参数已经确定，应在同一个 assistant response 中发出 `TodoWrite` 和这些彼此独立的工具调用；否则只在确实需要某个结果来决定下一动作时等待。
+3. 只有第一个工作工具调用已经确定有必要，且其参数和安全性都不依赖其他结果时，才在同一个 assistant response 中把它与 `TodoWrite` 一起发出。先执行满足条件的最小调用；如果它的结果可能改变下一动作，应先检查结果，不要推测性批量展开调查。
 
 如果第一步是向用户询问阻塞问题，那就提问并停下。否则继续推进。

package/yeaft/tools/activation.js

@@ -52,7 +52,7 @@ export const CONDITIONAL_BUILTIN_TOOL_NAMES = new Set([
   'RouteForward',
   'CreateWorkItem',
   // Legacy compatibility only. New planning is a single provider response:
-  // visible prose + TodoWrite + the first independent work tools. Keeping the
+  // visible prose + TodoWrite + the first justified work-tool call. Keeping the
   // definition registered lets old direct callers resolve it without paying a
   // dedicated StartPlan -> provider -> TodoWrite round trip on every new task.
   'StartPlan',

package/yeaft/tools/agent.js

@@ -239,11 +239,15 @@ Async orchestration:
   2. Continue    — keep working in the parent VP; do not block just to poll.
   3. ListAgents  — non-blocking status check when you need progress/liveness.
   4. PromptAgent — optional follow-up if the sub-agent is idle and needs guidance.
+     After queueing it, call WaitAgent in the same parent turn and collect the
+     reply before ending. If a bounded wait times out, wait again with a larger
+     bound unless the agent is stale/stalled.
   5. CloseAgent  — stop or finalize a sub-agent when it is no longer needed.
 
 Completion/failure is delivered through sub-agent notifications on later parent
-turns. WaitAgent remains available only as a short compatibility poll; do not
-use it as the default workflow or call it repeatedly in a loop.`,
+turns, so do not call WaitAgent merely to poll a newly spawned running agent.
+After PromptAgent follow-up, however, the answer is required to complete that
+workflow; use bounded WaitAgent calls and inspect liveness instead of blind loops.`,
     zh: `创建一个子 Agent 并行处理独立任务。
 
 子 Agent 在独立上下文中运行，可给定具体 mission 和可选的 expected_output schema。
@@ -263,11 +267,14 @@ use it as the default workflow or call it repeatedly in a loop.`,
   1. SpawnAgent  — 启动子 Agent 作为后台任务并立即返回。
   2. Continue    — 父 VP 继续工作；不要仅仅为了轮询而阻塞。
   3. ListAgents  — 需要进度信息时的非阻塞状态检查。
-  4. WaitAgent   — 短轮询（<5s）或仅在真正需要结果时才明确长等待。
-  5. CloseAgent  — 完成后销毁子 Agent。
+  4. PromptAgent — 子 Agent 空闲且需要指导时，可选发送后续提示。
+     排队后必须在同一个父级 turn 调用 WaitAgent 并拿到回复再结束；有界等待超时后，除非 Agent
+     已 stale/stalled，否则使用更大的有界 timeout 再次等待。
+  5. CloseAgent  — 不再需要时停止或结束子 Agent。
 
-不要在循环中无终止条件地调用 WaitAgent。如果短检查后子 Agent 仍在运行，继续前进，
-让 notification 在下个 turn 告知你。`
+完成或失败会通过之后父级 turn 的 notification 送达，因此不要为了轮询刚创建且仍运行的
+Agent 调用 WaitAgent。但 PromptAgent 后续工作必须拿到答案才算完成；使用有界 WaitAgent 调用并检查
+liveness，不要盲目循环。`
   },
   parameters: {
     type: 'object',

package/yeaft/tools/file-read.js

@@ -88,7 +88,8 @@ Supports offset and limit for reading specific portions of large files.
 
 Guidelines:
 - Use absolute paths when possible
-- A file is "large" only at >3000 lines. Read the whole file by default; only use offset/limit above that threshold or when you already know the exact line range you need.
+- Read only the smallest range that answers the current question. A whole-file read is reasonable only when the file is at most 3000 lines and its full contents are actually needed.
+- Do not repeat a successful read with the same range. Continue only when the truncation marker or inspected content shows that another range is necessary.
 - Binary files are detected by extension and rejected
 - Maximum file size: 10MB
 - Default limit: 3000 lines (matches the "large file = >3000 lines" threshold)`,
@@ -98,7 +99,8 @@ Guidelines:
 
 使用指南：
 - 尽量使用绝对路径
-- 超过 3000 行才算大文件。默认读完整文件；仅在超过此阈值或已知精确行范围时使用 offset/limit
+- 只读取能回答当前问题的最小范围。只有文件不超过 3000 行且确实需要全部内容时，才适合整文件读取
+- 不要用相同范围重复成功的读取。只有截断标记或已检查的内容表明仍需其他范围时才继续
 - 二进制文件通过扩展名识别并拒绝
 - 最大文件大小：10MB
 - 默认行数限制：3000 行`

package/yeaft/tools/glob.js

@@ -123,6 +123,7 @@ Guidelines:
 - Use "**/" for recursive directory matching
 - Common directories (node_modules, .git, etc.) are skipped
 - Returns file paths relative to the search directory
+- Use the narrowest pattern and smallest useful limit; inspect the result before broadening or issuing alternative searches
 - Limited to 500 results by default`,
     zh: `查找匹配 glob 模式的文件。
 
@@ -132,6 +133,7 @@ Guidelines:
 - 用 "**/" 进行递归目录匹配
 - 常见目录（node_modules、.git 等）被跳过
 - 返回相对于搜索目录的文件路径
+- 使用最窄的模式和满足需要的最小 limit；先检查结果，再决定是否扩大或发出备选搜索
 - 默认限制 500 条结果`
   },
   parameters: {

package/yeaft/tools/grep.js

@@ -808,9 +808,10 @@ Guidelines:
 - Uses the JavaScript RegExp syntax supported by the running Node.js version
 - Escape special characters such as \\. and \\{
 - Skips symlinks, binary files, invalid UTF-8, and text files larger than 16 MiB
-- Use glob or type filters to narrow the search
+- Use glob or type filters and the smallest useful head_limit to narrow the search
+- Inspect one focused search before broadening or trying alternatives; do not repeat a successful equivalent search
 - Skips common large directories such as node_modules and .git
-- Results are limited to 500 matches by default`,
+- Results are limited to 250 matches by default`,
     zh: `用正则表达式搜索文件内容。
 
 优先使用 ripgrep (rg) 快速搜索，回退到 Node.js 实现。
@@ -824,9 +825,10 @@ Guidelines:
 - 使用当前 Node.js 版本支持的 JavaScript RegExp 语法
 - 特殊字符需转义，如 \\.、\\{
 - 跳过符号链接、二进制、无效 UTF-8 和超过 16 MiB 的文本文件
-- 用 glob 或 type 过滤缩小搜索范围
+- 用 glob 或 type 过滤，并设置满足需要的最小 head_limit 来缩小搜索范围
+- 先检查一个聚焦搜索的结果，再决定是否扩大或尝试其他搜索；不要重复成功的等价搜索
 - 跳过 node_modules、.git 等常见大目录
-- 默认结果限制 500 条`
+- 默认结果限制 250 条`
   },
   parameters: {
     type: 'object',

package/yeaft/tools/list-agents.js

@@ -58,6 +58,7 @@ stale/stalled 诊断、result 尾部和消息数量。将此作为异步子 Agen
   isConcurrencySafe: () => true,
   isReadOnly: () => true,
   cacheWithinQuery: false,
+  duplicateCallPolicy: () => 'allow',
   async execute(input, ctx) {
     const includeTerminal = Boolean(input?.include_closed || input?.include_terminal);
     const agents = getAgentRegistry();

package/yeaft/tools/read-task-log.js

@@ -24,6 +24,7 @@ export default defineTool({
   isConcurrencySafe: () => true,
   isReadOnly: () => true,
   cacheWithinQuery: false,
+  duplicateCallPolicy: () => 'allow',
   async execute(input = {}, ctx = {}) {
     if (!ctx.taskManager) return JSON.stringify({ error: 'task manager unavailable' });
     const taskId = input.taskId;

package/yeaft/tools/send-message.js

@@ -19,12 +19,13 @@ export default defineTool({
 Use this to give the sub-agent more work, additional instructions, or relay
 information. The prompt is queued for the agent to process on its next turn.
 
-IMPORTANT — PromptAgent only QUEUES the message; it does NOT block. After this
-returns you almost always want to call WaitAgent next to collect the reply.
-Do NOT end your turn after PromptAgent without either (a) calling WaitAgent,
-(b) explaining to the user what you just asked the sub-agent, or (c) calling
-CloseAgent. The orchestration loop is
-SpawnAgent → (PromptAgent ↔ WaitAgent)+ → CloseAgent → final reply to user.
+IMPORTANT — PromptAgent only QUEUES the message; it does NOT block. A follow-up
+is unfinished until you collect the reply. After PromptAgent returns, call
+WaitAgent in the same parent turn. If WaitAgent reports running/timedOut, call
+WaitAgent again with a larger bounded timeout unless the agent is stale/stalled.
+When the reply arrives, relay the result to the user or
+continue the work that depends on it. Do not end the parent turn immediately
+after PromptAgent.
 
 PromptAgent is rejected if the sub-agent is in a terminal state
 (completed/failed/closed/abandoned). Use SpawnAgent to start a fresh one.`,
@@ -32,10 +33,10 @@ PromptAgent is rejected if the sub-agent is in a terminal state
 
 用于给子 Agent 更多工作、额外指令或传递信息。提示会排队等待子 Agent 在其下一个 turn 处理。
 
-重要——PromptAgent 仅将消息排队，不阻塞。返回后你通常需要立即调用 WaitAgent 来收集回复。
-不要在 PromptAgent 后直接结束 turn，除非：(a) 调用 WaitAgent，(b) 向用户说明你刚让子 Agent
-做了什么，或 (c) 调用 CloseAgent。编排循环为：
-SpawnAgent -> (PromptAgent <-> WaitAgent)+ -> CloseAgent -> 最终回复给用户。
+重要——PromptAgent 仅将消息排队，不阻塞。后续任务只有拿到回复才算完成。PromptAgent 返回后，
+父级必须在同一个 turn 调用 WaitAgent。如果 WaitAgent 返回 running/timedOut，除非 Agent 已经
+stale/stalled，否则必须使用更大的有界 timeout 再次调用 WaitAgent。回复到达后，必须向用户转述结果或继续执行
+依赖该结果的工作。禁止在 PromptAgent 后立刻结束父级 turn。
 
 如果子 Agent 处于终止状态（completed/failed/closed/abandoned），PromptAgent 会被拒绝。
 用 SpawnAgent 启动新的。`
@@ -125,6 +126,11 @@ SpawnAgent -> (PromptAgent <-> WaitAgent)+ -> CloseAgent -> 最终回复给用
       content: message,
       timestamp: Date.now(),
     });
+    // WaitAgent uses this marker to distinguish an explicitly queued follow-up
+    // from an ordinary asynchronous SpawnAgent run. A bounded timeout must not
+    // silently downgrade the same-parent-turn collection contract.
+    agent.promptReplyPending = true;
+    agent.promptReplyPendingAt = Date.now();
     if (agent.status === STATUS.IDLE || agent.status === STATUS.CREATED) {
       agent.status = STATUS.RUNNING;
     }
@@ -132,15 +138,15 @@ SpawnAgent -> (PromptAgent <-> WaitAgent)+ -> CloseAgent -> 最终回复给用
     return JSON.stringify({
       next_steps:
         'Message is queued — the sub-agent has NOT replied yet. Call WaitAgent ' +
-        'next to collect the reply, then relay it to the user. Do NOT end your ' +
-        'turn here without either waiting for the reply or telling the user ' +
-        'what you just asked.',
+        'in this parent turn and collect the reply. If it is still running, call ' +
+        'WaitAgent again with a larger bounded timeout unless it is stale/stalled. ' +
+        'Relay the reply or continue the dependent work; do NOT end now.',
       success: true,
       agentId: agent_id,
       name: agent.name,
       messageCount: agent.messages.length,
       pending: agent.pendingPrompts.length,
-      message: `Message sent to agent "${agent.name}". Use WaitAgent to collect its reply.`,
+      message: `Message sent to agent "${agent.name}". Call WaitAgent now; the reply is still pending.`,
     });
   },
 });

package/yeaft/tools/skill.js

@@ -86,6 +86,7 @@ Actions:
   },
   isConcurrencySafe: () => true,
   isReadOnly: () => true,
+  duplicateCallPolicy: () => 'suppress',
   async execute(input, ctx) {
     const skillManager = ctx?.skillManager;
 

package/yeaft/tools/start-plan.js

@@ -46,7 +46,7 @@ export default defineTool({
 This tool returns a planning instruction. Use it to land a structured plan, then keep working in the same turn. The expected flow is:
 1. Produce a short prose plan (problem, approach, risks).
 2. Call \`TodoWrite\` with the ordered steps. Mark the first concrete step "in_progress", the rest "pending".
-3. When the first-step tools and arguments are already known, emit \`TodoWrite\` and those independent tool calls in the same assistant response. Wait only when a result genuinely determines the next action.
+3. Emit \`TodoWrite\` with a first work-tool call only when that call is already necessary and its arguments and safety do not depend on another result. Start with the smallest such call; inspect its result before issuing calls it could change or make unnecessary.
 
 WHEN TO USE:
 - Multi-step implementation (3+ steps), refactor, or open-ended investigation.
@@ -65,7 +65,7 @@ The tool takes the topic plus optional guiding fields (stuckAt, userProblem, exp
 此工具返回规划指令。用它产出一份结构化计划，然后在同一个 turn 中继续工作。预期流程是：
 1. 产出简短文字计划（问题、方法、风险）。
 2. 调用 TodoWrite 写出有序步骤。将第一个具体步骤标记为 "in_progress"，其余标记为 "pending"。
-3. 如果第一步所需的工具和参数已经确定，应在同一个 assistant response 中发出 TodoWrite 和这些彼此独立的工具调用；只有某个结果确实决定下一动作时才等待。
+3. 只有第一个工作工具调用已经确定有必要，且其参数和安全性都不依赖其他结果时，才在同一个 assistant response 中把它与 TodoWrite 一起发出。先执行满足条件的最小调用；如果结果可能改变或使后续调用不再必要，应先检查结果。
 
 何时使用：
 - 多步骤实现（3+ 步）、重构或开放式调查。
@@ -173,8 +173,8 @@ The tool takes the topic plus optional guiding fields (stuckAt, userProblem, exp
     }
     lines.push('');
     const nextInstruction = String(language).toLowerCase().startsWith('zh')
-      ? '下一步：产出计划并调用 `TodoWrite`。如果第一步的工具和参数已经确定，在同一个 assistant response 中一并发出这些彼此独立的工具调用。只有第一步必须询问用户时才在计划后停下。'
-      : 'Next: produce the plan and call `TodoWrite`. If the first-step tools and arguments are already known, emit those independent tool calls in the same assistant response. Stop after the plan only when the first step must ask the user.';
+      ? '下一步：产出计划并调用 `TodoWrite`。只有第一个工作工具调用已经确定有必要，且其参数和安全性都不依赖其他结果时，才在同一个 assistant response 中发出这个最小调用；如果结果可能改变后续调用，先检查结果。只有第一步必须询问用户时才在计划后停下。'
+      : 'Next: produce the plan and call `TodoWrite`. Emit only the smallest first work-tool call whose necessity, arguments, and safety do not depend on another result; inspect its result before calls it could change. Stop after the plan only when the first step must ask the user.';
     lines.push(nextInstruction);
 
     return lines.join('\n');

package/yeaft/tools/todo-write.js

@@ -36,7 +36,7 @@ WHEN TO USE:
 FIRST CALL — PLAN WITHOUT AN EXTRA MODEL ROUND:
 - Write a short visible prose plan in the same assistant response: problem, approach, and risks.
 - Call TodoWrite directly; do not call a separate planning-mode tool first.
-- If the first work tools and arguments are known, emit them beside TodoWrite in that same response.
+- Emit TodoWrite beside the first work-tool call only when that call is already necessary and its arguments and safety do not depend on another result. Start with the smallest such call.
 
 HOW TO USE:
 - First call: enumerate all the todos with status "pending", set exactly one to "in_progress".
@@ -45,8 +45,8 @@ HOW TO USE:
 - \`content\` is the imperative form ("Run tests"); \`activeForm\` is the present-continuous shown during execution ("Running tests").
 
 BATCH WITH WORK:
-- Avoid an intermediate TodoWrite-only model round when the next work tool and its arguments are already known. Emit TodoWrite and those independent work tool calls in the same assistant response.
-- This is batching, not speculative progress: mark work completed only after evidence. Keep calls separate when a pending result can change the next action, its arguments, or its safety.
+- Avoid an intermediate TodoWrite-only model round only when the next work-tool call passes the necessity, argument-independence, and safety-independence test. Emit that minimal call beside TodoWrite.
+- Do not speculative-batch an investigation. Mark work completed only after evidence, and inspect a pending result before issuing any call it could change, invalidate, or make unnecessary.
 - A standalone TodoWrite remains valid when no work tool should follow, including final completion or a blocking user question.
 
 WHEN NOT TO USE:
@@ -61,7 +61,7 @@ WHEN NOT TO USE:
 首次调用——不要浪费额外模型回合进入规划模式：
 - 在同一个 assistant response 中先写简短可见计划：问题、方案和风险。
 - 直接调用 TodoWrite，不要先调用单独的规划模式工具。
-- 如果第一批工作工具及参数已经确定，把它们和 TodoWrite 在同一响应中发出。
+- 只有第一个工作工具调用已经确定有必要，且其参数和安全性都不依赖其他结果时，才把它与 TodoWrite 在同一响应中发出；先执行满足条件的最小调用。
 
 如何使用：
 - 首次调用：枚举所有 todo，状态为 "pending"，将其中恰好一个设为 "in_progress"。
@@ -70,8 +70,8 @@ WHEN NOT TO USE:
 - content 是祈使形式（如 "Run tests"）；activeForm 是执行时显示的进行时态（如 "Running tests"）。
 
 和工作工具合批：
-- 如果下一项工作所用的工具和参数已经确定，不要让中间状态的 TodoWrite 单独占一个模型回合；应在同一个 assistant response 中发出 TodoWrite 和这些彼此独立的工作工具调用。
-- 这是合批，不是提前宣告进度：只有已有证据时才能把工作标记为完成。如果待返回结果可能改变下一动作、参数或安全性，就必须分开调用。
+- 只有下一个工作工具调用通过必要性、参数独立性和安全独立性检查时，才避免让中间状态的 TodoWrite 单独占一个模型回合；把这个最小调用与 TodoWrite 一起发出。
+- 不要推测性批量展开调查。只有已有证据时才能把工作标记为完成；如果待返回结果可能改变、否定或使后续调用不再必要，应先检查该结果。
 - 没有工作工具应继续执行时（包括记录最终完成态或询问阻塞问题），TodoWrite 仍可单独调用。
 
 何时不使用：

package/yeaft/tools/types.js

@@ -72,6 +72,10 @@
  * @property {boolean | ((input?: object) => boolean)} [cacheWithinQuery] — explicitly safe to reuse for identical calls in one query
  * @property {boolean | ((input?: object) => boolean)} [mayMutateWorkspaceAfterReturn] — may keep changing the workspace after execute() resolves; disables same-query read reuse
  * @property {(input?: object) => boolean} [isDestructive] — destructive operation?
+ * @property {(input?: object) => 'allow' | 'warn' | 'suppress'} [duplicateCallPolicy]
+ *   — repeated exact-call policy for one query. Use `allow` for polling/time-varying
+ *   tools and `suppress` only when the result is stable for the whole query.
+ *   Errors are never counted as successful duplicates.
  * @property {'json-error-envelope' | null} [errorOutput] — explicit returned-output error contract; null means only thrown errors fail
  * @property {string} [mcpServer] — owning MCP server for flattened MCP tools
  * @property {'external' | 'run'} [sideEffectScope] — whether mutations escape the current Run collector
@@ -90,6 +94,7 @@
  *   cacheWithinQuery?: boolean | ((input?: object) => boolean),
  *   mayMutateWorkspaceAfterReturn?: boolean | ((input?: object) => boolean),
  *   isDestructive?: (input?: object) => boolean,
+ *   duplicateCallPolicy?: (input?: object) => 'allow' | 'warn' | 'suppress',
  *   errorOutput?: 'json-error-envelope' | null,
  *   mcpServer?: string,
  *   sideEffectScope?: 'external' | 'run',
@@ -108,6 +113,7 @@ export function defineTool({
   cacheWithinQuery = false,
   mayMutateWorkspaceAfterReturn = false,
   isDestructive = () => false,
+  duplicateCallPolicy = () => 'warn',
   errorOutput = 'json-error-envelope',
   mcpServer,
   sideEffectScope = 'external',
@@ -126,6 +132,7 @@ export function defineTool({
     cacheWithinQuery,
     mayMutateWorkspaceAfterReturn,
     isDestructive,
+    duplicateCallPolicy,
     errorOutput,
     sideEffectScope,
   };

package/yeaft/tools/wait-agent.js

@@ -19,7 +19,7 @@
  *              processing. The envelope flags `runningInBackground:
  *              true` (the sub-agent IS continuing — it does NOT need
  *              another PromptAgent to keep going) and recommends either
- *              another WaitAgent or CloseAgent. `result` carries the
+ *              another bounded WaitAgent or CloseAgent. `result` carries the
  *              mid-stream preview (the driver keeps lastResult fresh
  *              from every text_delta).
  *
@@ -43,7 +43,7 @@ import { consumeNotificationForAgent } from '../sub-agent/notifications.js';
  * otherwise eat tail-positioned nudges when `result` is long).
  *
  * @param {string} status
- * @param {{ timedOut?: boolean, runningInBackground?: boolean, budgetExceeded?: boolean, stale?: boolean }} [opts]
+ * @param {{ timedOut?: boolean, budgetExceeded?: boolean, stale?: boolean, mustCollectReply?: boolean }} [opts]
  */
 function nextStepsFor(status, opts = {}) {
   if (opts.budgetExceeded) {
@@ -63,6 +63,15 @@ function nextStepsFor(status, opts = {}) {
       'task and start a fresh agent if needed.'
     );
   }
+  if (opts.timedOut && opts.mustCollectReply) {
+    return (
+      'The PromptAgent follow-up reply is still pending and must be collected ' +
+      'in this parent turn. Call WaitAgent again with a larger bounded timeout. ' +
+      'Do not end the turn or switch to ListAgents/notifications. Stop re-waiting ' +
+      'only if the agent becomes stale/stalled, the wait is cancelled, or the ' +
+      'agent returns idle/terminal.'
+    );
+  }
   if (opts.timedOut) {
     return (
       'Sub-agent is running in the background; it does not need another ' +
@@ -129,6 +138,11 @@ function errorNextSteps() {
  */
 function buildEnvelope(agent, { timedOut = false } = {}) {
   const status = agent.status;
+  const mustCollectReply = agent.promptReplyPending === true;
+  if (!timedOut && (status === STATUS.IDLE || isTerminalAgentStatus(status))) {
+    agent.promptReplyPending = false;
+    agent.promptReplyPendingAt = null;
+  }
   const liveness = diagnoseAgentLiveness(agent);
   const budgetResult = agent.result && typeof agent.result === 'object'
     && agent.result.status === 'budget_exceeded'
@@ -140,7 +154,12 @@ function buildEnvelope(agent, { timedOut = false } = {}) {
         ? agent.result
         : (agent.lastResult || ''));
   const env = {
-    next_steps: nextStepsFor(status, { timedOut, budgetExceeded: !!budgetResult, stale: liveness.stale }),
+    next_steps: nextStepsFor(status, {
+      timedOut,
+      budgetExceeded: !!budgetResult,
+      stale: liveness.stale,
+      mustCollectReply: mustCollectReply && !liveness.stale,
+    }),
     agentId: agent.id,
     name: agent.name,
     status,
@@ -154,6 +173,7 @@ function buildEnvelope(agent, { timedOut = false } = {}) {
     diagnostic: liveness.diagnostic,
     messages: Array.isArray(agent.messages) ? agent.messages.length : 0,
     turns: agent.usage?.turns || 0,
+    mustCollectReply: timedOut ? mustCollectReply : false,
   };
   if (timedOut) {
     env.timedOut = true;
@@ -192,15 +212,15 @@ Status semantics:
     another PromptAgent. Either WaitAgent again with a larger timeout,
     CloseAgent to cut it short, or tell the user it's still working.
 
-CRITICAL — after WaitAgent returns you MUST take one of these actions:
-  • status terminal: relay/retry/report.
-  • status idle:     reply to user OR PromptAgent OR CloseAgent.
-  • timedOut:        re-wait, cut short, or report progress.
-NEVER end your turn silently right after WaitAgent — the user has not seen
-the sub-agent's reply yet; only you have. The orchestration loop is
-SpawnAgent → (PromptAgent ↔ WaitAgent)+ → CloseAgent → final reply to user.
+After WaitAgent returns, act on the status. A non-stale timeout after PromptAgent
+has 'mustCollectReply=true': call WaitAgent again with a larger bounded timeout in
+the same parent turn until idle/terminal. A stale/stalled agent breaks that loop:
+inspect/report/close it instead. For ordinary SpawnAgent background work, use
+ListAgents or later completion notifications instead of repeatedly re-waiting.
 
-Compatibility tool. The default wait is a short 5000ms poll. Callers may request up to 300000ms (5 minutes), but this is no longer the primary sub-agent workflow; prefer SpawnAgent + ListAgents + completion notifications for async background work.`,
+The default wait is a bounded 5000ms poll; callers may request up to 300000ms
+(5 minutes). Never use an unbounded blind loop: every wait is capped, liveness is
+checked after each timeout, and stale/stalled is the explicit stop condition.`,
     zh: `等待子 Agent 的下一次状态变更（turn 结束、终止或等待超时）并获取状态信封。
 
 返回 JSON，含明确的 status、最新的 result 文本、liveness 计数器（toolUseCount、tokenCount、
@@ -215,11 +235,13 @@ msSinceLastEvent、recentTools）、可随时 Read 的持久化 outputFile 路
     仍在运行。不需要再 PromptAgent。要么用更大 timeout 再次 WaitAgent，要么 CloseAgent 中断，
     要么告知用户它仍在工作。
 
+PromptAgent 后若非 stale/stalled 的有界等待超时，必须在同一父级 turn 使用更大的有界 timeout
+再次调用 WaitAgent，直到 idle/terminal；不要改用 ListAgents/notification 丢下未收集的回复。
 关键——如果信封显示 stale/stalled，子 Agent 可能卡死或空转。不要反复调用 WaitAgent——向用户
 报告情况，决定是 CloseAgent（带 close_reason）还是重试。
 
-此工具保留用于向后兼容。现代异步流程请用 ListAgents 做非阻塞状态检查，依赖 turn 开始时的
-notification 获取完成事件。`
+普通 SpawnAgent 异步流程仍用 ListAgents 做非阻塞状态检查，并依赖后续 completion
+notification；不要对普通后台任务盲目循环等待。每次等待都有上限，stale/stalled 是停止条件。`
   },
   parameters: {
     type: 'object',
@@ -247,6 +269,7 @@ notification 获取完成事件。`
   isConcurrencySafe: () => true,
   isReadOnly: () => true,
   cacheWithinQuery: false,
+  duplicateCallPolicy: () => 'allow',
   async execute(input, ctx) {
     const { agent_id, timeout_ms = 5000 } = input;
     if (!agent_id) {
@@ -297,6 +320,13 @@ notification 获取完成事件。`
       await new Promise(r => setTimeout(r, 200));
     }
 
+    // Re-check after the final sleep. The status may have changed just before
+    // the deadline without another loop iteration.
+    if (isTerminalAgentStatus(agent.status) || agent.status === STATUS.IDLE) {
+      consumeNotificationForAgent(agent.id);
+      return JSON.stringify(buildEnvelope(agent));
+    }
+
     // Wait elapsed; the sub-agent is still running. Surface mid-stream
     // preview + liveness so the parent has actionable signal.
     return JSON.stringify(buildEnvelope(agent, { timedOut: true }));

package/yeaft/tools/web-fetch.js

@@ -42,7 +42,8 @@ Use this to read documentation, articles, or any web page.
 
 Guidelines:
 - Provide the full URL including protocol (https://)
-- Large pages will be truncated — use the offset parameter for pagination
+- Fetch one authoritative relevant page first; inspect it before fetching alternatives
+- Set max_length to the smallest useful content budget. Large pages are truncated; use a more targeted source rather than repeatedly fetching the same URL
 - For APIs, the raw response body is returned as-is
 - Respects the abort signal for cancellation`,
     zh: `获取并读取网页内容。
@@ -51,7 +52,8 @@ Guidelines:
 
 使用指南：
 - 提供完整 URL 含协议（https://）
-- 大页面会截断——用 offset 参数做分页
+- 先抓取一个最权威、最相关的页面；检查结果后再决定是否抓取备选页面
+- 将 max_length 设为满足需要的最小内容预算。大页面会截断；应改用更定向的来源，而不是重复抓取同一 URL
 - 对 API 请求，原始响应体原样返回
 - 尊重取消信号`
   },

package/yeaft/tools/web-search.js

@@ -32,17 +32,17 @@ Use this when you need up-to-date information that may not be in your training d
 Returns search results with titles, URLs, and snippets.
 
 Guidelines:
-- Use specific, targeted search queries
+- Use one specific, targeted query with the smallest useful result limit; inspect it before trying alternatives
 - Include the current year for time-sensitive queries
-- Combine with WebFetch to read full page content from results`,
+- Fetch the most authoritative relevant result first. Add another source only when the claim is consequential, disputed, stale, or not established by the first source`,
     zh: `搜索网页获取最新信息。
 
 当你需要训练数据中可能没有的最新信息时使用。返回搜索结果，含标题、URL 和摘要。
 
 使用指南：
-- 使用具体、有针对性的搜索关键词
+- 先执行一个具体、定向的查询，并使用满足需要的最小结果数；检查结果后再决定是否尝试其他查询
 - 时间敏感的查询要包含当前年份
-- 配合 WebFetch 读取搜索结果中的完整页面内容`
+- 优先抓取最权威、最相关的结果。只有结论影响重大、存在争议、可能过时，或首个来源不能证明时才增加来源`
   },
   parameters: {
     type: 'object',