@yeaft/webchat-agent 1.0.513 → 1.0.515

package/yeaft/tools/agent.js

@@ -14,8 +14,11 @@
  *     budget?: {
  *       max_tokens?: number,
  *       max_turns?: number,
+ *       max_tool_calls?: number,
+ *       max_llm_calls?: number,
  *       wall_time_ms?: number
  *     },
+ *     allow_tools?: string[],          // extra parent tool grants beyond persona defaults
  *     cwd?: string
  *   }
  */
@@ -24,7 +27,8 @@ import { defineTool } from './types.js';
 import { randomUUID } from 'crypto';
 import { getPersona, listPersonaIds } from '../personas.js';
 import { startSubAgent } from '../sub-agent/runner.js';
-import { resolveSubAgentBudget } from '../sub-agent/execution-control.js';
+import { resolveSubAgentBudget, validateBudget } from '../sub-agent/execution-control.js';
+import { validateToolGrants } from '../sub-agent/tool-access.js';
 import { STATUS, isTerminalAgentStatus } from '../sub-agent/status.js';
 import { diagnoseAgentLiveness, makeLiveness } from '../sub-agent/liveness.js';
 import { TASK_RESULT_DELIVERY } from '../tasks/store.js';
@@ -108,15 +112,8 @@ export function validateSpec(input) {
     return { ok: false, error: 'expected_output must be a JSON schema object' };
   }
   if (budget !== undefined) {
-    if (typeof budget !== 'object' || budget === null) {
-      return { ok: false, error: 'budget must be an object' };
-    }
-    for (const k of ['max_tokens', 'max_turns', 'wall_time_ms', 'max_tool_calls']) {
-      if (budget[k] !== undefined && (!Number.isFinite(budget[k]) || budget[k] <= 0
-          || (['max_turns', 'max_tool_calls'].includes(k) && !Number.isSafeInteger(budget[k])))) {
-        return { ok: false, error: `budget.${k} must be finite and positive (counts must be integers)` };
-      }
-    }
+    const error = validateBudget(budget);
+    if (error) return { ok: false, error };
   }
   return {
     ok: true,
@@ -237,8 +234,10 @@ Pick a preset persona to pre-wire a tool subset and model tier:
 Guidelines:
 - Give a clear, focused mission — what "done" looks like
 - Use expected_output when the return shape matters
-- Delegate only a bounded independent result; do simple work directly. Set scope, evidence and stopping conditions in mission.
-- Inspect execution counters and partial evidence before extending budgets; do not respawn the same exhausted mission automatically.
+- Delegate one clear result with the workspace/base and completion evidence. Let the child choose its steps; do simple work directly. Split unrelated goals, not individual reads.
+- Usually omit budget: defaults are safety ceilings, not targets. Do not impose a tiny tool limit on a multi-file review. Tool exhaustion reserves one tool-free handoff within the remaining time/token limits; unfinished work stays budget_exceeded.
+- Persona tools are defaults, not task boundaries: reviewer has GitRead; grant Bash or write tools explicitly via allow_tools only when needed. Bash is not a read-only sandbox; isolate concurrent writable tasks.
+- Use UpdateAgent to adjust a live child's time/tool/LLM ceilings or extra grants after inspecting evidence; counters and context are retained. Do not extend stalled work blindly or respawn the same exhausted mission automatically.
 
 Async orchestration:
   1. SpawnAgent  — starts the sub-agent as a background task and returns immediately.
@@ -268,8 +267,10 @@ max_tokens 在 provider usage 到达时检查；max_turns 是 query turn 数，
 使用指南：
 - 给出清晰聚焦的 mission——"完成"是什么样子
 - 当返回结构重要时使用 expected_output
-- 只委派有界且独立的结果；简单工作直接做。在 mission 中写清范围、证据和停止条件。
-- 扩大预算前检查实际执行计数和已有证据；不要自动重启同一个耗尽预算的任务。
+- 一次只委派一个明确结果，提供工作目录/基线和完成证据，让子 Agent 自主选择步骤；简单工作直接做。拆分不相关目标，不要拆成逐个读取任务。
+- 通常省略 budget：默认值是安全上限，不是执行目标。不要给多文件 review 人为设置极小的工具额度。工具耗尽后会在剩余时间/token预算内留一次无工具交付机会，未完成仍返回 budget_exceeded。
+- Persona 是默认工具集，不是任务死边界：reviewer 有 GitRead；按需用 allow_tools 显式授予 Bash/写工具。Bash 并非只读沙箱；并行写任务应隔离 workspace。
+- 检查已有证据后，用 UpdateAgent 原地调整活跃子任务的时间/工具/LLM 上限或额外授权，保留计数与上下文；不要盲目扩额停滞任务，也不要自动重启同一个耗尽任务。
 
 异步编排流程：
   1. SpawnAgent  — 启动子 Agent 作为后台任务并立即返回。
@@ -333,6 +334,10 @@ liveness，不要盲目循环。`
           max_turns: { type: 'number', description: {
           en: 'Optional turn ceiling; no default limit is applied',
           zh: '可选 turn 上限；默认不设限制',
+        } },
+          max_llm_calls: { type: 'integer', minimum: 1, description: {
+          en: 'Optional actual Engine provider-dispatch ceiling (including retries); distinct from query turns. One extra tool-free reporting request is reserved and separately counted.',
+          zh: '可选实际 Engine 模型请求上限（含重试），不同于 query turn；另保留并单独统计一次无工具报告请求。',
         } },
           max_tool_calls: { type: 'integer', minimum: 1, description: {
           en: 'Actual tool execution ceiling; default 64, or 128 for implementer. Includes parallel and discovered tools.',
@@ -348,6 +353,13 @@ liveness，不要盲目循环。`
           zh: '覆盖默认工具/时间安全上限；token/turn 限制可选。截止时返回 { status: "budget_exceeded", partial_output, reason }，不代表任务成功。',
         },
       },
+      allow_tools: {
+        type: 'array', items: { type: 'string' }, maxItems: 32,
+        description: {
+          en: 'Explicit extra parent tools beyond persona defaults (e.g. Bash, FileEdit). Bash permits arbitrary shell/writes, not a read-only sandbox. Grant only necessary tools and isolate writable workspaces; child orchestration stays forbidden.',
+          zh: '在 persona 默认工具之外显式授予父级工具（如 Bash、FileEdit）。Bash 可执行任意 Shell/写入，并非只读沙箱。仅授予必要工具并隔离写入 workspace；子级编排仍禁止。',
+        },
+      },
       cwd: {
         type: 'string',
         description: {
@@ -379,6 +391,8 @@ liveness，不要盲目循环。`
       return JSON.stringify({ next_steps: ERROR_NEXT_STEPS, error: validation.error });
     }
     const spec = validation.spec;
+    const grants = validateToolGrants(input.allow_tools === undefined ? [] : input.allow_tools, ctx?.parentEngineDeps?.parentToolRegistry);
+    if (!grants.ok) return JSON.stringify({ next_steps: ERROR_NEXT_STEPS, error: grants.error });
     const { name, cwd } = input;
     const callerScope = getCallerAgentScope(ctx);
 
@@ -411,6 +425,7 @@ liveness，不要盲目循环。`
       // Capture at the tool boundary, before fire-and-forget startup can yield.
       parentEffortDecision: captureParentEffortDecision(ctx),
       budget: spec.budget,
+      allowTools: grants.tools,
       cwd: cwd || ctx?.cwd || process.cwd(),
       status: STATUS.CREATED,
       messages: [],
@@ -499,6 +514,7 @@ liveness，不要盲目循环。`
       name,
       persona: spec.persona || null,
       budget: spec.budget || null,
+      allow_tools: agent.allowTools,
       status: agent.status,
       outputFile: agent.outputFile || null,
       taskId: agent.taskId || null,

package/yeaft/tools/file-read.js

@@ -27,11 +27,10 @@ const BINARY_EXTS = new Set([
 /** Max file size to read (10 MB). */
 const MAX_FILE_SIZE = 10 * 1024 * 1024;
 
-/** Default number of lines to read. Aligned with the "large file = >3000
- *  lines" rule in templates/{base,common-rules,tool-guidance}.md so a
- *  ≤3000-line file is returned in one call (no silent truncation that
- *  would trigger a follow-up `offset:3000` call — that's exactly the
- *  round-trip this tool's prompt guidance promises to avoid). */
+/** Default number of lines to read. Aligned with the FileRead tool schema's
+ *  "large file = >3000 lines" rule so a ≤3000-line file is returned in one
+ *  call (no silent truncation that would trigger a follow-up `offset:3000`
+ *  call — exactly the round-trip the tool guidance avoids). */
 const DEFAULT_LIMIT = 3000;
 
 /** Keep raw output close to the model-facing 32 KiB budget while leaving

package/yeaft/tools/git-read.js

@@ -0,0 +1,266 @@
+import { resolve } from 'node:path';
+import { defineTool } from './types.js';
+import { runProcess } from './process-runner.js';
+
+const MAX_RESULT_BYTES = 30 * 1024;
+const MAX_CAPTURE_BYTES = 64 * 1024;
+const MAX_PATHS = 50;
+const MAX_VALUE_LENGTH = 4096;
+const DEFAULT_LOG_LIMIT = 20;
+const MAX_LOG_LIMIT = 50;
+const TIMEOUT_MS = 30_000;
+const RUN_PROCESS_OVERRIDE = Symbol('runProcessOverride');
+
+const COMMON_ARGS = Object.freeze([
+  '--no-pager',
+  '--no-optional-locks',
+  '--literal-pathspecs',
+  '--no-replace-objects',
+  '-c', 'color.ui=false',
+  '-c', 'core.fsmonitor=false',
+  '-c', 'log.showSignature=false',
+  '-c', 'submodule.recurse=false',
+  '-c', 'diff.submodule=short',
+  '-c', 'protocol.allow=never',
+]);
+
+// Worktree status/diff may invoke clean/process filters even with textconv and
+// external diff disabled. Discover their keys, never values, and override them
+// for this process only. Incomplete discovery fails closed.
+async function filterOverrides(run, options) {
+  const result = await run('git', [
+    ...COMMON_ARGS, 'config', '--null', '--name-only', '--get-regexp',
+    '^filter\\..*\\.(clean|smudge|process|required)$',
+  ], options);
+  if (result.truncated || result.timedOut || (result.code !== 0 && result.code !== 1)) {
+    throw new Error('Cannot safely inspect Git content filters');
+  }
+  if (result.code === 1) return [];
+  const keys = [...new Set(result.stdout.split('\0').filter(Boolean))];
+  if (keys.length > 200) throw new Error('Too many Git content filters for a bounded read');
+  return keys.flatMap(key => {
+    if (!/^filter\..*\.(clean|smudge|process|required)$/.test(key) || /[=\r\n]/.test(key)) {
+      throw new Error('Unsupported Git filter key; refusing an unsafe read');
+    }
+    return ['-c', `${key}=${key.endsWith('.required') ? 'false' : ''}`];
+  });
+}
+
+function errorOutput(message) {
+  return JSON.stringify({ error: message });
+}
+
+function validateValue(value, name) {
+  if (typeof value !== 'string' || !value) return `${name} must be a non-empty string`;
+  if (value.length > MAX_VALUE_LENGTH) return `${name} must be at most ${MAX_VALUE_LENGTH} characters`;
+  if (value.startsWith('-')) return `${name} must not start with "-"`;
+  if (/\0|[\r\n]/u.test(value)) return `${name} must not contain NUL or newlines`;
+  return null;
+}
+
+function validatePaths(paths) {
+  if (paths === undefined) return null;
+  if (!Array.isArray(paths)) return 'paths must be an array of strings';
+  if (paths.length > MAX_PATHS) return `paths must contain at most ${MAX_PATHS} entries`;
+  for (let index = 0; index < paths.length; index += 1) {
+    const error = validateValue(paths[index], `paths[${index}]`);
+    if (error) return error;
+    if (paths[index].includes(':(attr:')) return `paths[${index}] must not use pathspec attributes`;
+  }
+  return null;
+}
+
+function unexpectedInput(input, allowed) {
+  const unexpected = Object.keys(input).filter(key => !allowed.has(key));
+  return unexpected.length > 0 ? `Unexpected parameter(s) for ${input.operation}: ${unexpected.join(', ')}` : null;
+}
+
+export function buildGitReadArgs(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    return { error: 'input must be an object' };
+  }
+
+  const { operation } = input;
+  if (!['status', 'diff', 'show', 'log'].includes(operation)) {
+    return { error: 'operation must be one of: status, diff, show, log' };
+  }
+
+  if (operation === 'status') {
+    const error = unexpectedInput(input, new Set(['operation']));
+    if (error) return { error };
+    return { args: [...COMMON_ARGS, 'status', '--short', '--branch', '--untracked-files=normal', '--ignore-submodules=all'] };
+  }
+
+  if (operation === 'diff') {
+    const error = unexpectedInput(input, new Set(['operation', 'base', 'head', 'paths']))
+      || validatePaths(input.paths)
+      || (input.base !== undefined ? validateValue(input.base, 'base') : null)
+      || (input.head !== undefined ? validateValue(input.head, 'head') : null);
+    if (error) return { error };
+    if (input.head !== undefined && input.base === undefined) {
+      return { error: 'head requires base' };
+    }
+    const revision = input.base === undefined
+      ? 'HEAD'
+      : `${input.base}...${input.head || 'HEAD'}`;
+    return {
+      args: [
+        ...COMMON_ARGS,
+        'diff', '--no-ext-diff', '--no-textconv', '--no-color', '--ignore-submodules=dirty',
+        revision, '--', ...(input.paths || []),
+      ],
+    };
+  }
+
+  if (operation === 'show') {
+    const error = unexpectedInput(input, new Set(['operation', 'revision', 'paths']))
+      || validatePaths(input.paths)
+      || (input.revision !== undefined ? validateValue(input.revision, 'revision') : null);
+    if (error) return { error };
+    return {
+      args: [
+        ...COMMON_ARGS,
+        'show', '--no-ext-diff', '--no-textconv', '--no-color', '--format=fuller',
+        input.revision || 'HEAD', '--', ...(input.paths || []),
+      ],
+    };
+  }
+
+  const error = unexpectedInput(input, new Set(['operation', 'revision', 'limit']))
+    || (input.revision !== undefined ? validateValue(input.revision, 'revision') : null);
+  if (error) return { error };
+  const limit = input.limit === undefined ? DEFAULT_LOG_LIMIT : input.limit;
+  if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LOG_LIMIT) {
+    return { error: `limit must be an integer between 1 and ${MAX_LOG_LIMIT}` };
+  }
+  return {
+    args: [
+      ...COMMON_ARGS,
+      'log', '--no-color', `--max-count=${limit}`, '--date=iso-strict',
+      '--format=%H%x09%ad%x09%an%x09%s', input.revision || 'HEAD', '--',
+    ],
+  };
+}
+
+function takeUtf8(text, maxBytes) {
+  const buffer = Buffer.from(String(text), 'utf8');
+  if (buffer.length <= maxBytes) return String(text);
+  let end = maxBytes;
+  while (end > 0 && (buffer[end] & 0xc0) === 0x80) end -= 1;
+  return buffer.subarray(0, end).toString('utf8');
+}
+
+export function formatGitReadResult(operation, result) {
+  const timedOut = Boolean(result.timedOut);
+  const runnerTruncated = Boolean(result.truncated);
+  const sections = [];
+  if (result.stdout) sections.push(`STDOUT:\n${result.stdout}`);
+  if (result.stderr) sections.push(`STDERR:\n${result.stderr}`);
+  const body = sections.join('\n');
+  const baseHeader = truncated => [
+    `operation: ${operation}`,
+    `exitCode: ${runnerTruncated ? 'not observed (output limit reached)' : result.code}`,
+    `timedOut: ${timedOut}`,
+    `truncated: ${truncated}`,
+  ].join('\n');
+  const initial = `${baseHeader(runnerTruncated)}\n\n${body || '(no output)'}`;
+  if (!runnerTruncated && Buffer.byteLength(initial, 'utf8') <= MAX_RESULT_BYTES) return initial;
+
+  const marker = '\n\n[Output truncated by GitRead; narrow the revision or paths.]';
+  const header = `${baseHeader(true)}\n\n`;
+  const bodyBudget = Math.max(
+    0,
+    MAX_RESULT_BYTES - Buffer.byteLength(header, 'utf8') - Buffer.byteLength(marker, 'utf8'),
+  );
+  return header + takeUtf8(body || '(no output)', bodyBudget) + marker;
+}
+
+const gitReadTool = defineTool({
+  name: 'GitRead',
+  description: {
+    en: `Read bounded local Git evidence without a shell or network access.
+
+Supported operations are intentionally limited:
+- status: compact branch and working-tree status.
+- diff: tracked changes against HEAD by default, or an explicit base...head range; optional paths narrow the result.
+- show: one commit (HEAD by default), optionally narrowed by paths.
+- log: a compact bounded commit list (20 entries by default, maximum 50).
+
+GitRead never fetches, writes Git state, or creates worktrees. It disables pagers, external diff, textconv, content filters, optional locks, fsmonitor, and submodule traversal. Filter-normalized files (such as LFS) show raw worktree bytes; submodule status needs separate inspection. Revisions and paths beginning with "-" are rejected. Output reports whether it was truncated.`,
+    zh: `有界读取本地 Git 证据，不使用 shell，也不访问网络。
+
+操作范围刻意限制为：
+- status：紧凑显示分支和工作区状态。
+- diff：默认显示相对 HEAD 的已跟踪改动，也可指定 base...head；可用 paths 缩小范围。
+- show：显示一个提交（默认 HEAD），可用 paths 缩小范围。
+- log：紧凑且有界的提交列表（默认 20 条，最多 50 条）。
+
+GitRead 不 fetch、不写 Git 状态、不创建 worktree。它禁用 pager、external diff、textconv、内容 filter、optional locks、fsmonitor 和子模块遍历。LFS 等 filter 文件显示原始工作区字节，子模块状态需单独检查。拒绝以 "-" 开头的 revision 与路径；结果明确标识是否截断。`,
+  },
+  parameters: {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      operation: { type: 'string', enum: ['status', 'diff', 'show', 'log'] },
+      base: { type: 'string', maxLength: MAX_VALUE_LENGTH, description: 'Diff base revision; omitted for working-tree changes against HEAD' },
+      head: { type: 'string', maxLength: MAX_VALUE_LENGTH, description: 'Diff head revision; requires base and defaults to HEAD' },
+      revision: { type: 'string', maxLength: MAX_VALUE_LENGTH, description: 'Revision for show or log (default: HEAD)' },
+      paths: {
+        type: 'array',
+        maxItems: MAX_PATHS,
+        items: { type: 'string', minLength: 1, maxLength: MAX_VALUE_LENGTH },
+        description: 'Optional repository-relative paths for diff or show',
+      },
+      limit: { type: 'integer', minimum: 1, maximum: MAX_LOG_LIMIT, description: 'Maximum log entries' },
+    },
+    required: ['operation'],
+  },
+  timeoutMs: 0,
+  isConcurrencySafe: () => true,
+  isReadOnly: () => true,
+  async execute(input, ctx) {
+    const built = buildGitReadArgs(input);
+    if (built.error) return errorOutput(built.error);
+    const cwd = resolve(ctx?.cwd || process.cwd());
+    try {
+      const run = ctx?.[RUN_PROCESS_OVERRIDE] || runProcess;
+      const startedAt = Date.now();
+      const options = {
+        cwd,
+        signal: ctx?.signal,
+        timeoutMs: TIMEOUT_MS,
+        maxBytes: MAX_CAPTURE_BYTES,
+        env: {
+          ...process.env,
+          GIT_PAGER: 'cat',
+          PAGER: 'cat',
+          GIT_EXTERNAL_DIFF: '',
+          GIT_NO_LAZY_FETCH: '1',
+          GIT_OPTIONAL_LOCKS: '0',
+          GIT_TERMINAL_PROMPT: '0',
+          NO_COLOR: '1',
+        },
+      };
+      const overrides = await filterOverrides(run, options);
+      const result = await run('git', [...overrides, ...built.args], {
+        ...options, timeoutMs: Math.max(1, TIMEOUT_MS - (Date.now() - startedAt)),
+      });
+      return formatGitReadResult(input.operation, result);
+    } catch (error) {
+      if (error?.name === 'AbortError') throw error;
+      return errorOutput(`GitRead failed: ${error?.message || String(error)}`);
+    }
+  },
+});
+
+export function createGitReadTool({ runProcessImpl = runProcess } = {}) {
+  return {
+    ...gitReadTool,
+    execute(input, ctx) {
+      return gitReadTool.execute(input, { ...ctx, [RUN_PROCESS_OVERRIDE]: runProcessImpl });
+    },
+  };
+}
+
+export { MAX_RESULT_BYTES };
+export default gitReadTool;

package/yeaft/tools/index.js

@@ -33,6 +33,7 @@ import discoverTools from './discover-tools.js';
 
 // --- P0 File tools ---
 import bash from './bash.js';
+import gitRead from './git-read.js';
 import fileRead from './file-read.js';
 import fileWrite from './file-write.js';
 import fileEdit from './file-edit.js';
@@ -47,6 +48,7 @@ import cancelTask from './cancel-task.js';
 
 // --- P1 Agent tools ---
 import agentTool from './agent.js';
+import updateAgent from './update-agent.js';
 import sendMessage from './send-message.js';
 import waitAgent from './wait-agent.js';
 import closeAgent from './close-agent.js';
@@ -101,6 +103,7 @@ export const allTools = [
 
   // P0 File
   bash,
+  gitRead,
   fileRead,
   fileWrite,
   fileEdit,
@@ -115,6 +118,7 @@ export const allTools = [
 
   // P1 Agent
   agentTool,
+  updateAgent,
   sendMessage,
   waitAgent,
   closeAgent,

package/yeaft/tools/update-agent.js

@@ -0,0 +1,79 @@
+/** Parent-owned, in-place child controls; never resumes a terminal or reporting child. */
+import { defineTool } from './types.js';
+import { getAgentRegistry, agentBelongsToCaller } from './agent.js';
+import { isTerminalAgentStatus } from '../sub-agent/status.js';
+import { validateBudget } from '../sub-agent/execution-control.js';
+import { validateToolGrants } from '../sub-agent/tool-access.js';
+import { diagnoseAgentLiveness } from '../sub-agent/liveness.js';
+
+export default defineTool({
+  name: 'UpdateAgent',
+  description: {
+    en: 'Adjust a live child in place after inspecting its progress: absolute lifetime time/tool/LLM budgets and explicit extra tool grants. Does not queue a prompt, reset usage, or revive a terminal/reporting child. Give evidence and the remaining task in reason; do not extend stalled or repeating work blindly. Bash permits arbitrary shell and writes, not a read-only sandbox; grant only necessary parent tools and isolate writable workspaces. Already dispatched work is not undone by revocation.',
+    zh: '检查进展后原地调整活跃子 Agent：累计时间/工具/LLM 上限及额外工具授权。不排队提示、不清零用量、不复活终止或收尾中的任务。reason 说明已有证据和剩余工作，勿盲目给停滞/重复任务扩额。Bash 可执行任意 Shell 和写入，并非只读沙箱；只授予必要的父级工具，写任务隔离 workspace。撤销不撤回已执行操作。',
+  },
+  parameters: {
+    type: 'object',
+    properties: {
+      agent_id: { type: 'string' },
+      reason: { type: 'string', description: { en: 'Observed progress, remaining work and why this adjustment is necessary', zh: '实际进展、剩余工作及调整原因' } },
+      budget: {
+        type: 'object',
+        properties: {
+          max_tokens: { type: 'number', minimum: 1 },
+          max_turns: { type: 'integer', minimum: 1 },
+          max_tool_calls: { type: 'integer', minimum: 1 },
+          max_llm_calls: { type: 'integer', minimum: 1 },
+          wall_time_ms: { type: 'integer', minimum: 1 },
+        },
+        description: { en: 'Partial absolute lifetime ceilings, not added quota. Unspecified limits stay unchanged. LLM cap excludes one reserved reporting request; time is measured from original spawn.', zh: '部分累计上限，不是增加的额度；未指定项不变。LLM 上限之外保留一次报告请求；时间从最初启动计算。' },
+      },
+      allow_tools: {
+        type: 'array', items: { type: 'string' }, maxItems: 32,
+        description: { en: 'Replace extra persona grants with these canonical parent tool names (e.g. Bash, FileEdit); [] revokes extras, omission leaves grants unchanged', zh: '替换 persona 额外授权（如 Bash、FileEdit）；[] 撤销额外授权，省略则不变' },
+      },
+    },
+    required: ['agent_id', 'reason'],
+  },
+  isReadOnly: () => false,
+  isConcurrencySafe: () => false,
+  mayMutateWorkspaceAfterReturn: () => true,
+  async execute(input, ctx) {
+    const fail = error => JSON.stringify({ error, next_steps: 'Inspect the current agent state and correct the request; do not respawn or repeat blindly.' });
+    const agent = getAgentRegistry().get(input.agent_id);
+    if (!agent || !agentBelongsToCaller(agent, ctx)) return fail(`Agent not found: ${input.agent_id}`);
+    if (isTerminalAgentStatus(agent.status) || agent.budgetReportStarted || agent.budgetStopReason
+        || agent.abortController?.signal.aborted) return fail('Agent is terminal, stopping or already reporting; it cannot be extended');
+    if (typeof input.reason !== 'string' || !input.reason.trim() || input.reason.length > 2000) return fail('reason must contain 1..2000 characters of evidence and remaining work');
+    if (input.budget === undefined && input.allow_tools === undefined) return fail('budget or allow_tools is required');
+    if (input.budget !== undefined) {
+      const error = validateBudget(input.budget);
+      if (error) return fail(error);
+    }
+    const parentRegistry = ctx?.parentEngineDeps?.parentToolRegistry;
+    const grants = input.allow_tools === undefined ? null : validateToolGrants(input.allow_tools, parentRegistry);
+    if (grants && !grants.ok) return fail(grants.error);
+    const previousBudget = { ...agent.budget };
+    const previousTools = [...(agent.allowTools || [])];
+    // All validation precedes mutation. Original usage/deadline origin are retained.
+    agent.budget = { ...agent.budget, ...input.budget };
+    if (grants) agent.allowTools = grants.tools;
+    agent.controlRevision = (agent.controlRevision || 0) + 1;
+    if (agent.execution && agent.execution.toolCalls < agent.budget.max_tool_calls * 0.75) agent.execution.warning = null;
+    if (!agent.budgetReportStarted) {
+      agent.toolBudgetReason = null;
+      agent.executionBudgetReason = null;
+    }
+    agent.refreshToolPolicy?.();
+    agent.rearmWallTimeWatchdog?.();
+    const event = { type: 'sub_agent_control_updated', at: Date.now(), reason: input.reason.trim(),
+      previousBudget, budget: { ...agent.budget }, previousTools, allowTools: [...(agent.allowTools || [])] };
+    agent.diagnostics ||= [];
+    agent.diagnostics.push(event);
+    if (agent.diagnostics.length > 100) agent.diagnostics.shift();
+    try { agent.outputLog?.write(event); } catch { /* diagnostics must not fail the applied update */ }
+    return JSON.stringify({ success: true, agentId: agent.id, status: agent.status,
+      budget: agent.budget, allow_tools: agent.allowTools || [], liveness: diagnoseAgentLiveness(agent),
+      next_steps: 'Adjustment applied without restarting work. Continue the parent task; use PromptAgent only if new guidance is needed, then collect its reply. Revocation does not cancel already dispatched work.' });
+  },
+});

package/yeaft/web-bridge.js

@@ -86,6 +86,7 @@ import {
 import {
   SessionCrudError,
   createSessionFromSpec,
+  copySession,
   renameSession,
   updateSessionAnnouncement,
   archiveSession,
@@ -759,25 +760,6 @@ function legacyProjectContext(yeaftDir, sessionId) {
   }, sessionId);
 }
 
-function buildProjectSharedBlock(projectContext, summaries = '') {
-  const context = normalizeProjectContext(projectContext, null);
-  const body = typeof summaries === 'string' ? summaries.trim() : '';
-  if (!context?.projectId && !body) return '';
-  const lines = ['[Project Shared Context]'];
-  if (context?.projectId) {
-    const label = context.projectName
-      ? `${context.projectName} (${context.projectId})`
-      : context.projectId;
-    lines.push(`Project: ${label}`);
-    lines.push('Sharing boundary: sibling Sessions in this Project on this Agent only.');
-  } else {
-    lines.push('Sharing boundary: sibling Sessions in the same Project on this Agent only.');
-  }
-  lines.push('Read-only memory summaries preserve each source Session identity.');
-  if (body) lines.push('', body);
-  return lines.join('\n');
-}
-
 function vpKey(sessionId, vpId) {
   return `${sessionId}::${vpId}`;
 }
@@ -3699,6 +3681,28 @@ export function handleYeaftCreateSession(msg) {
   }
 }
 
+export function handleYeaftCopySession(msg) {
+  const requestId = msg && msg.requestId;
+  const sessionId = msg && (msg.sessionId || msg.groupId);
+  try {
+    const yeaftDir = ctx.CONFIG?.yeaftDir;
+    const source = decorateSessionsWithRuntimeState(snapshotSessions(yeaftDir))
+      .find(session => session?.id === sessionId);
+    if (!source) throw new SessionCrudError('not_found', sessionId);
+    if (source.running) throw new SessionCrudError('session_running', sessionId, 'Cannot copy a running Session');
+    const session = copySession(yeaftDir, sessionId, {
+      ...configuredVpPaths(),
+      name: msg && msg.name,
+    });
+    recordAgentSessionCreated();
+    session.config = loadSessionConfig(yeaftDir, session.id);
+    sendSessionCrudResult({ op: 'copy', requestId, ok: true, session });
+    sendSessionSnapshotBroadcast();
+  } catch (err) {
+    sendSessionCrudResult({ op: 'copy', requestId, ok: false, error: sessionErrorPayload(err) });
+  }
+}
+
 /**
  * `yeaft_scan_workdir_sessions` — compatibility endpoint for the retired
  * workdir Session scan flow. Session data now lives under the user-level
@@ -5698,16 +5702,9 @@ async function runVpTurn({ prompt, promptParts = null, sessionId, vpId, threadId
           ? `${projectContext.projectName} (${projectContext.projectId})`
           : (projectContext?.projectId || '');
         queryOpts.projectInstruction = projectContext?.projectInstruction || '';
-        // Related Session summaries now enter through Engine's single AMS
-        // memory outlet. Keep this announcement limited to Project identity and
-        // sharing boundaries so parent VP prompts do not duplicate the same prose
-        // that sub-agents receive through memory.
-        const sharedBlock = buildProjectSharedBlock(projectContext);
-        if (sharedBlock) {
-          queryOpts.sessionAnnouncement = queryOpts.sessionAnnouncement
-            ? `${queryOpts.sessionAnnouncement}\n\n${sharedBlock}`
-            : sharedBlock;
-        }
+        // Project sibling identity remains available to Engine memory recall via
+        // projectSessionIds. Do not mirror internal sharing metadata into the
+        // user-authored Session announcement shown to the model.
       }
       let turnSessionMeta = null;
       try { turnSessionMeta = sessionCoordinator?.group?.getMeta?.() || null; } catch { turnSessionMeta = null; }
@@ -8215,7 +8212,6 @@ export function handleYeaftMcpReload(msg = {}) {
 export const __testHooks = {
   loadProjects,
   sharedProjectContext,
-  buildProjectSharedBlock,
   normalizeProjectContext,
   handleProjectContextSyncForTest(msg) {
     handleYeaftProjectContextSync(msg);

package/yeaft/templates/tool-guidance.md

@@ -1,11 +0,0 @@
-<!-- lang:en -->
-
-## Active Tool Guidance
-
-{{guidance}}
-
-<!-- lang:zh -->
-
-## 当前工具指引
-
-{{guidance}}