@yeaft/webchat-agent 1.0.512 → 1.0.514

package/yeaft/sub-agent/spawned-prompt.js

@@ -25,7 +25,7 @@
  * @param {'en'|'zh'} [args.language='en']
  * @returns {string} preamble block (already ## headed, ready to concat)
  */
-export function buildSpawnedPreamble({ parentName, parentVpId, agentName, mission, expectedOutput, presetPrompt, budget, language = 'en' } = {}) {
+export function buildSpawnedPreamble({ parentName, parentVpId, agentName, mission, expectedOutput, presetPrompt, budget, allowTools = [], language = 'en' } = {}) {
   // Resolve template markers before embedding: the outer VP renderer treats
   // markers as sections of the whole soul and would drop the parent + contract.
   const locale = language === 'zh' || language === 'zh-CN' ? 'zh' : 'en';
@@ -35,8 +35,9 @@ export function buildSpawnedPreamble({ parentName, parentVpId, agentName, missio
     : presetPrompt;
   const contract = [
     rolePrompt || '',
+    `## Tool authority\nDefault persona tools plus explicit parent grants: ${JSON.stringify(allowTools)}. Parent grants override a default read-only role only within the mission's scope. Bash permits arbitrary shell/writes; it is not a sandbox. You cannot grant yourself tools or budget; report blockers to the parent. UpdateAgent is parent-only.`,
     expectedOutput ? `## expected_output\nReturn the requested structure; mark unverified facts and blockers honestly.\n${JSON.stringify(expectedOutput)}` : '',
-    budget ? `## Execution budget\n${JSON.stringify(budget)}\nLimits are ceilings, not targets. Stop once the mission is answered. Return partial findings before exhausting the budget; do not automatically restart the same work.` : '',
+    budget ? `## Execution budget\n${JSON.stringify(budget)}\nLimits are ceilings, not targets. Complete the assigned result, then stop; do not stop with a plan or promise to continue. If a tool or prerequisite is unavailable, return the evidence and blocker instead of searching for unavailable capabilities. Near the tool limit, prioritize a supported conclusion. At the limit, one tool-free report may be requested within the remaining time/token budget; do not automatically restart the work.` : '',
   ].filter(Boolean).join('\n\n');
   const m = [(mission || '').trim(), contract].filter(Boolean).join('\n\n');
   if (language === 'zh') {

package/yeaft/sub-agent/tool-access.js

@@ -0,0 +1,138 @@
+/**
+ * Child tool authorization policy.
+ *
+ * Persona tools are the baseline. `agent.allowTools` is an additional,
+ * replaceable allowlist of canonical tools from the parent registry. Bash is
+ * deliberately not wrapped or narrowed here: granting Bash grants the actual
+ * parent shell tool, including its write capabilities.
+ */
+import { getPersona } from '../personas.js';
+
+const MAX_TOOL_GRANTS = 32;
+const TOOL_NAME_RE = /^[A-Za-z0-9_][A-Za-z0-9_-]{0,127}$/;
+
+export const RESTRICTED_TOOLS = new Set([
+  'SpawnAgent',
+  'Agent',          // legacy alias
+  'UpdateAgent',
+  'PromptAgent',
+  'SendMessage',    // legacy alias
+  'WaitAgent',
+  'CloseAgent',
+  'ListAgents',
+  'RouteForward',
+  'AskUser',
+  'CreateWorkItem',
+]);
+
+function canonicalTool(parentRegistry, name) {
+  if (!parentRegistry || typeof parentRegistry.get !== 'function') return null;
+  const tool = parentRegistry.get(name);
+  return tool && typeof tool.name === 'string' ? tool : null;
+}
+
+function isRestricted(tool, requestedName = null) {
+  return RESTRICTED_TOOLS.has(tool?.name) || (requestedName && RESTRICTED_TOOLS.has(requestedName));
+}
+
+/**
+ * Validate and canonicalize explicit child grants.
+ *
+ * @param {unknown} names
+ * @param {import('../tools/registry.js').ToolRegistry|null} parentRegistry
+ * @returns {{ ok: true, tools: string[] }|{ ok: false, error: string }}
+ */
+export function validateToolGrants(names, parentRegistry) {
+  if (!Array.isArray(names)) {
+    return { ok: false, error: 'allow_tools must be an array of tool names' };
+  }
+  if (names.length > MAX_TOOL_GRANTS) {
+    return { ok: false, error: `allow_tools may contain at most ${MAX_TOOL_GRANTS} names` };
+  }
+  if (!parentRegistry || typeof parentRegistry.get !== 'function') {
+    return names.length === 0
+      ? { ok: true, tools: [] }
+      : { ok: false, error: 'parent tool registry is unavailable' };
+  }
+
+  const tools = [];
+  const seen = new Set();
+  for (const value of names) {
+    if (typeof value !== 'string' || !value.trim()) {
+      return { ok: false, error: 'allow_tools entries must be non-empty tool names' };
+    }
+    const name = value.trim();
+    if (!TOOL_NAME_RE.test(name)) {
+      return { ok: false, error: `Invalid tool name: ${name}` };
+    }
+    const tool = canonicalTool(parentRegistry, name);
+    if (!tool) return { ok: false, error: `Parent tool is not available: ${name}` };
+    if (isRestricted(tool, name)) {
+      return { ok: false, error: `Tool cannot be granted to a child agent: ${tool.name}` };
+    }
+    if (!seen.has(tool.name)) {
+      seen.add(tool.name);
+      tools.push(tool.name);
+    }
+  }
+  return { ok: true, tools };
+}
+
+function unregisterTool(registry, tool) {
+  registry.unregister(tool.name);
+  for (const alias of tool.aliases || []) registry.unregister(alias);
+}
+
+/**
+ * Create a live policy for one child. `refresh()` reconciles only the child
+ * registry; the parent registry is used as the source of canonical ToolDef
+ * objects and is never mutated.
+ *
+ * @param {import('../tools/registry.js').ToolRegistry|null} parentRegistry
+ * @param {object|null} agent
+ * @returns {{ allows(tool: object): boolean, refresh(childRegistry: import('../tools/registry.js').ToolRegistry): void }}
+ */
+export function createChildToolPolicy(parentRegistry, agent) {
+  const preset = agent?.personaData || getPersona(agent?.persona);
+  const baseline = preset && preset.id !== 'implementer'
+    ? new Set([
+      ...preset.tools.map(name => canonicalTool(parentRegistry, name)?.name || (name === 'Read' ? 'FileRead' : name)),
+      'DiscoverTools',
+    ])
+    : null;
+
+  const allows = (tool) => {
+    if (!tool || typeof tool.name !== 'string' || isRestricted(tool)) return false;
+
+    // Require the exact ToolDef owned by the parent. This prevents aliases or a
+    // child-local/MCP hot registration from manufacturing an allowed name.
+    if (canonicalTool(parentRegistry, tool.name) !== tool) return false;
+    if (baseline === null || baseline.has(tool.name)) return true;
+
+    for (const name of agent?.allowTools || []) {
+      const granted = canonicalTool(parentRegistry, name);
+      if (granted === tool && !isRestricted(granted, name)) return true;
+    }
+    return false;
+  };
+
+  const refresh = (childRegistry) => {
+    if (!childRegistry
+        || typeof childRegistry.getAllTools !== 'function'
+        || typeof childRegistry.register !== 'function'
+        || typeof childRegistry.unregister !== 'function') return;
+
+    for (const tool of childRegistry.getAllTools()) {
+      if (!allows(tool)) unregisterTool(childRegistry, tool);
+    }
+    if (!parentRegistry || typeof parentRegistry.getAllTools !== 'function') return;
+    for (const tool of parentRegistry.getAllTools()) {
+      if (!allows(tool)) continue;
+      const current = childRegistry.get(tool.name);
+      if (current && current !== tool) unregisterTool(childRegistry, current);
+      if (childRegistry.get(tool.name) !== tool) childRegistry.register(tool);
+    }
+  };
+
+  return { allows, refresh };
+}

package/yeaft/templates/personas/reviewer.md

@@ -4,6 +4,7 @@ name: Reviewer
 description: Critical read-only reviewer for code changes and designs
 modelTier: primary
 tools:
+  - GitRead
   - Read
   - Grep
   - Glob
@@ -18,7 +19,8 @@ You are a **Reviewer** sub-agent. Your job is to audit code or designs and surfa
 
 ## Operating Principles
 
-- **Read-only**: Never modify files.
+- **Read-only by default**: Do not modify files unless the parent explicitly grants the necessary tools for a scoped edit/verification task. Bash is not a read-only sandbox; keep it within the assigned scope.
+- **Diff first**: Start with `GitRead` status/diff to establish the actual change set, then inspect only the relevant files and lines.
 - **Evidence-based**: Every finding must cite `path:line`.
 - **Severity-tagged**: Label each finding `blocker | major | minor | nit`.
 - **Constructive**: Suggest fixes, not just complaints.
@@ -35,7 +37,8 @@ Structured list of findings. For each: severity, location, description, suggeste
 
 ## 操作原则
 
-- **只读**：不要修改文件。
+- **默认只读**：只有父级为明确的编辑/验证任务显式授予必要工具后，才可在该范围内写入。Bash 并非只读沙箱，不得扩大任务范围。
+- **先读 diff**：先用 `GitRead` 的 status/diff 确认实际改动范围，再只检查相关文件和行段。
 - **证据优先**：每个 finding 都必须引用 `path:line`。
 - **标注严重度**：每个 finding 标为 `blocker | major | minor | nit`。
 - **建设性**：不仅指出问题，也要给出修复建议。

package/yeaft/tools/activation.js

@@ -31,6 +31,7 @@ export const BACKGROUND_TASK_TOOL_NAMES = Object.freeze([
 ]);
 
 export const SUB_AGENT_MANAGEMENT_TOOL_NAMES = Object.freeze([
+  'UpdateAgent',
   'PromptAgent',
   'WaitAgent',
   'CloseAgent',
@@ -45,6 +46,7 @@ export const CONDITIONAL_BUILTIN_TOOL_NAMES = new Set([
   'ReadTaskLog',
   'CancelTask',
   'SpawnAgent',
+  'UpdateAgent',
   'PromptAgent',
   'WaitAgent',
   'CloseAgent',

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/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,