mocode-ai 0.1.7 → 0.1.9

package/dist/session/compact.js

@@ -23,6 +23,47 @@ export function truncateMid(text, max) {
     const out = text.slice(0, head) + marker + text.slice(text.length - tail);
     return out.length > max ? out.slice(0, max) : out;
 }
+/**
+ * Provenance 压缩:旧 tool_calls.arguments 超长时,把大字符串字段替换为 "<N 字符,已省略>" stub,
+ * 保留 path(/rollback planRollback 靠 JSON.parse(arguments).path 找文件,见 rollback/index.ts)+ 其余短字段。
+ * 比 truncateMid 的 head+tail 片段更短且更易读:LLM/摘要器看到 "<5000 字符,已省略>" 即知"写过 5000 字符",
+ * 而非混乱的 head+tail 片段。
+ *
+ * 保:JSON 合法(parse/stringify 失败均原样返回)+ tool_call_id 配对不动(只改 arguments 内容,不改
+ * tool_calls 数组结构)+ path 永不省(rollback 依赖)。永不抛错(对齐「调度器永不抛错」契约)。
+ *
+ * 触发:整体 arguments > MAX_OLD_TOOL_STUB 才进(同原 truncateMid 门槛);字段级也 > MAX_OLD_TOOL_STUB 才 stub。
+ */
+function stubToolCallArguments(argsRaw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(argsRaw);
+    }
+    catch {
+        return argsRaw; // 非合法 JSON(模型偶发):不碰
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return argsRaw;
+    const obj = parsed;
+    let changed = false;
+    for (const k of Object.keys(obj)) {
+        if (k === 'path')
+            continue; // path 永不省:/rollback planRollback 靠它定位文件
+        const v = obj[k];
+        if (typeof v === 'string' && v.length > MAX_OLD_TOOL_STUB) {
+            obj[k] = `<${v.length} 字符,已省略>`;
+            changed = true;
+        }
+    }
+    if (!changed)
+        return argsRaw;
+    try {
+        return JSON.stringify(obj);
+    }
+    catch {
+        return argsRaw; // stringify 失败(理论不会):不碰
+    }
+}
 /**
  * push-time 第一层:工具结果进 history 前裁到 MAX_HISTORY_RESULT。
  * 显示层(summarizeToolResult)仍用原 output,不受影响。
@@ -208,8 +249,8 @@ export async function compactHistory(history, opts) {
     // 第一层:微压缩——旧区原地截短(保 tool_call_id,无 LLM 调用)
     // 覆盖三类大字段,均只裁模型/工具产物,不动 user 原话与 system(摘要):
     //   ① tool 结果 content;
-    //   ② 旧 assistant 的 tool_calls.arguments —— 保 JSON 合法:整体超长才进,
-    //     逐字段值裁中截后重新 stringify(不裸中截会劈断 JSON、严格后端 400);parse 失败跳过;
+    //   ② 旧 assistant 的 tool_calls.arguments —— provenance stub:整体超长才进,大字段
+    //     替换为 "<N 字符,已省略>"(保 path + JSON 合法,见 stubToolCallArguments);
     //   ③ 旧 assistant 正文 content(模型长解释,回看价值低)。
     let microcompactDone = false;
     for (const g of oldGroups) {
@@ -227,27 +268,17 @@ export async function compactHistory(history, opts) {
                 as.content = truncateMid(as.content, MAX_OLD_TOOL_STUB);
                 microcompactDone = true;
             }
-            // ② tool_calls 参数:整体超长才进,逐字段裁值,保 JSON 合法
+            // ② tool_calls 参数:整体超长才进,provenance stub 大字段(保 path + JSON 合法)。
+            //   stubToolCallArguments:大字符串字段 → "<N 字符,已省略>";path 永不省(/rollback 依赖)。
             if (Array.isArray(as.tool_calls)) {
                 for (const tc of as.tool_calls) {
                     const args = tc?.function?.arguments;
                     if (typeof args !== 'string' || args.length <= MAX_OLD_TOOL_STUB)
                         continue;
-                    try {
-                        const parsed = JSON.parse(args);
-                        if (parsed && typeof parsed === 'object') {
-                            for (const k of Object.keys(parsed)) {
-                                const v = parsed[k];
-                                if (typeof v === 'string' && v.length > MAX_OLD_TOOL_STUB) {
-                                    parsed[k] = truncateMid(v, MAX_OLD_TOOL_STUB);
-                                }
-                            }
-                            tc.function.arguments = JSON.stringify(parsed);
-                            microcompactDone = true;
-                        }
-                    }
-                    catch {
-                        // arguments 非合法 JSON(模型偶发):不裁,沿用「调度器永不抛错」
+                    const stubbed = stubToolCallArguments(args);
+                    if (stubbed !== args) {
+                        tc.function.arguments = stubbed;
+                        microcompactDone = true;
                     }
                 }
             }

package/dist/session/drop.js

@@ -0,0 +1,135 @@
+// 运行中上下文剔除(drop_context 工具的核心):把历史里无关的 tool 结果替换为存根。
+//
+// 与 compact 的区别:compact 是阈值触发的整体压缩(微截 + 摘要),drop_context 是 agent 主动、
+// 精准剔除"已判定无关"的具体 tool 结果——agent 检索到大量无关信息后主动调用,释放上下文。
+//
+// 不变量(对齐 compact.ts):
+//  - 永不动 history[0](system prompt)。
+//  - 永不动当前轮:从末尾向前找到最后一个 user 消息,该 user 及其之后的 tool 结果一律保留
+//    (agent 本轮还在用,踢了会丢失正在进行的上下文)。
+//  - tool_call_id 配对:只改 tool 消息的 content,不删消息、不动 tool_calls 数组结构、不改 id。
+//  - 原地修改 history(同 compact:length=0;push 重建,repl 持有同一引用)。
+//  - 永不抛错(对齐「调度器永不抛错」契约);无匹配 / 无可剔除 → 返 dropped=0。
+import { messageTokens, estimateTokens, } from '../llm/index.js';
+/** 把消息 content 拍平成字符串(OpenAI 可能 string / null / 多模态数组)。 */
+function toText(content) {
+    if (content == null)
+        return '';
+    if (typeof content === 'string')
+        return content;
+    try {
+        return JSON.stringify(content);
+    }
+    catch {
+        return String(content);
+    }
+}
+/**
+ * 从 history 末尾向前找最后一个 user 消息的索引;无 user 返 -1。
+ * 用于划定"当前轮保护区"——该 user 及其之后的消息一律不剔除。
+ */
+function lastUserIndex(history) {
+    for (let i = history.length - 1; i >= 1; i--) {
+        if (history[i].role === 'user')
+            return i;
+    }
+    return -1;
+}
+/** 取 tool 消息对应的工具名(从紧邻的前导 assistant.tool_calls 按 tool_call_id 配对找)。 */
+function toolNameOf(history, idx) {
+    const tcId = history[idx].tool_call_id;
+    if (!tcId)
+        return null;
+    for (let j = idx - 1; j >= 1; j--) {
+        const m = history[j];
+        if (m.role !== 'assistant')
+            continue;
+        const tcs = m
+            .tool_calls;
+        if (!tcs)
+            continue;
+        const hit = tcs.find((tc) => tc?.id === tcId);
+        if (hit)
+            return hit.function?.name ?? null;
+    }
+    return null;
+}
+/**
+ * 剔除历史里命中的旧 tool 结果(原地修改 history)。
+ *
+ * 筛选(各维度 AND 组合):
+ *  - toolNames:只剔除这些工具名的结果(空 = 不限)
+ *  - contains:只剔除内容包含所有这些词(AND、大小写不敏感)的结果(空 = 不限)
+ *
+ * 保护:history[0](system)+ 当前轮(最后一个 user 及其之后)永不剔除。
+ * 已是存根的 tool 消息(含「已剔除」标记)不重复剔除(幂等)。
+ *
+ * 永不抛错;无匹配返 dropped=0。
+ */
+export function dropContextFromHistory(history, filter) {
+    const toolNames = filter.toolNames && filter.toolNames.length > 0
+        ? new Set(filter.toolNames)
+        : null;
+    const contains = filter.contains && filter.contains.length > 0
+        ? filter.contains.map((s) => s.toLowerCase())
+        : null;
+    // 当前轮保护区:最后一个 user 及其之后一律保留(agent 还在用)。
+    const guard = lastUserIndex(history);
+    // guard <= 0 表示无 user 或 user 就是 history[0](不会):整段历史都可剔除(除 history[0])。
+    const protectedFrom = guard > 0 ? guard : 0; // < protectedFrom 的才可剔除(即 [1, protectedFrom)
+    const items = [];
+    let freedTokens = 0;
+    const STUB_PREFIX = '⌦[已剔除:与当前任务无关]';
+    for (let i = 1; i < protectedFrom; i++) {
+        const m = history[i];
+        if (m.role !== 'tool')
+            continue;
+        const content = toText(m.content);
+        // 幂等:已是存根(含标记)不重复剔除。
+        if (content.startsWith(STUB_PREFIX))
+            continue;
+        // 维度 1:工具名
+        const tname = toolNameOf(history, i);
+        if (toolNames && (!tname || !toolNames.has(tname)))
+            continue;
+        // 维度 2:内容关键词(AND)
+        if (contains) {
+            const lower = content.toLowerCase();
+            if (!contains.every((kw) => lower.includes(kw)))
+                continue;
+        }
+        // 命中 → 替换为存根(保 tool_call_id 不动,只改 content)
+        const before = messageTokens(m);
+        const id = m.tool_call_id ?? '';
+        const stub = `${STUB_PREFIX} 原 ${tname ?? 'tool'} 结果(${content.length} 字符,约 ${before} tokens)${id ? ` · id …${id.slice(-6)}` : ''}⌫`;
+        m.content = stub;
+        const after = messageTokens(m);
+        freedTokens += Math.max(0, before - after);
+        items.push({
+            toolName: tname ?? 'tool',
+            toolCallId: id.slice(-6),
+        });
+    }
+    return {
+        dropped: items.length,
+        freedTokens,
+        items,
+    };
+}
+/** 给 drop_context 工具结果格式化人类可读摘要(回灌给 agent)。 */
+export function formatDropResult(r) {
+    if (r.dropped === 0) {
+        return '未剔除任何工具结果(无匹配的旧 tool 消息,或均在当前轮保护区内不可剔除)。';
+    }
+    const lines = [
+        `已剔除 ${r.dropped} 条无关工具结果,释放约 ${r.freedTokens} tokens。`,
+        '被剔除项(已替换为存根,tool_call_id 配对不变):',
+    ];
+    for (const it of r.items) {
+        lines.push(`  - ${it.toolName} (id …${it.toolCallId})`);
+    }
+    lines.push('这些结果在后续上下文中仅保留存根标记,不再占用篇幅。');
+    return lines.join('\n');
+}
+// 供 drop_context 工具估算用(避免直接 import llm 的公开 API 造成耦合,这里重导出)。
+export { estimateTokens };

package/dist/session/index.js

@@ -5,4 +5,5 @@
  * 依赖方向:session → {llm(摘要复用 chat), config, ui};llm 不反向依赖 session。
  */
 export { compactHistory, maybeCompact, capToolResultForHistory, truncateMid, contextState, } from './compact.js';
+export { dropContextFromHistory, formatDropResult, } from './drop.js';
 export { newSessionId, saveSession, loadSession, listSessions, sessionDir, } from './persist.js';

package/dist/tools/builtins/ask-human.js

@@ -3,10 +3,10 @@ import { promptIntervention } from '../../ui/intervention.js';
 export const askHumanTool = {
     name: 'ask_human',
     description: [
-        'Call this tool when you hit a decision point during a task that requires human input — it pops up a question panel in the terminal for the user to choose.',
-        'Use when: multiple implementation approaches need a user decision, user intent is unclear and needs clarification, or extra info is needed to proceed.',
-        'Blocks until the user responds; the user can pick a preset option or choose "custom input" to answer freely; the result is returned as the tool result.',
-        'Do not call frequently when the task is clear and you can decide yourself — it interrupts the user. When options is omitted or empty, it becomes free-text input instead.',
+        'Ask the user for input at a decision point (blocks until they respond).',
+        ' Use when: multiple approaches need a user decision, intent is unclear, or extra info is needed.',
+        ' Don\'t call when the task is clear and you can decide — it interrupts the user.',
+        ' Options (2-6) let the user pick; omit/empty for free-text input. Their answer is returned as the result.',
     ].join(''),
     parameters: {
         type: 'object',

package/dist/tools/builtins/codegraph.js

@@ -50,9 +50,9 @@ function runCodegraph(args) {
 }
 export const codegraphTool = {
     name: 'codegraph',
-    description: 'Preferred tool for understanding/locating code, tracing call chains, and assessing the impact of changes in repos with a code index (.codegraph/).' +
-        ' Returns relevant symbol source + call paths in one shot — more accurate and economical than piecing together via read_file/grep.' +
-        ' Returns a hint when .codegraph/ is absent (build it first with `codegraph init`).',
+    description: 'Preferred for understanding/locating code, tracing call chains, assessing impact of changes in repos with a code index (.codegraph/).' +
+        ' Returns symbol source + call paths in one shot — more accurate/economical than read_file/grep.' +
+        ' Hints to run `codegraph init` when .codegraph/ is absent.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/drop-context.js

@@ -0,0 +1,68 @@
+// ---------- drop_context ----------
+/**
+ * 运行中上下文剔除工具:agent 检索到大量无关信息后,主动把历史里无关的 tool 结果替换为存根,
+ * 释放上下文空间(保 tool_call_id 配对不变量,只改 content)。
+ *
+ * 与 compact 的区别:compact 是阈值触发的整体压缩(微截 + 摘要);drop_context 是 agent 主动、
+ * 精准剔除"已判定无关"的具体 tool 结果。
+ *
+ * 保护:history[0](system)与当前轮(最后一个 user 及其之后)永不剔除——agent 还在用。
+ * 已是存根的不重复剔除(幂等)。永不抛错。
+ *
+ * 筛选(各维度 AND 组合,全部可选;不传 = 剔除所有可剔除的旧 tool 结果):
+ *  - toolNames:只剔除这些工具名的结果(如 ["grep","read_file"])
+ *  - contains:只剔除内容包含所有这些词(AND、大小写不敏感)的结果
+ *
+ * plan 模式不禁用:纯上下文管理,无文件 / 命令副作用。
+ */
+export const dropContextTool = {
+    name: 'drop_context',
+    description: [
+        'Drop (stub-replace) irrelevant OLDER tool results from history to free context.',
+        'COST-AWARE: ~300-token round-trip; only call if freed tokens clearly exceed it — i.e. MULTIPLE bulky results (e.g. a wide grep/read sweep of mostly-irrelevant hits), not a single small one or near done.',
+        'Never dropped: system prompt and the CURRENT turn (last user message onward). Idempotent. Filters AND-combine; omit both = drop all droppable. Returns dropped count, freed tokens, tool names.',
+    ].join(' '),
+    parameters: {
+        type: 'object',
+        properties: {
+            toolNames: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Only drop results from these tool names (e.g. ["grep","read_file"]). Empty/omitted = no tool-name filter.',
+            },
+            contains: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Only drop results whose content contains ALL of these keywords (AND, case-insensitive). Empty/omitted = no content filter.',
+            },
+        },
+        required: [],
+    },
+    async execute(args, ctx) {
+        const dropContext = ctx?.dropContext;
+        if (!dropContext) {
+            // 无注入(理论上不会:runAgentCore 总注入)。降级:不改 history,告知 agent。
+            return '错误:上下文剔除回调不可用(未由 agent 循环注入),无法剔除。';
+        }
+        const filter = {};
+        if (Array.isArray(args.toolNames)) {
+            filter.toolNames = args.toolNames
+                .filter((v) => typeof v === 'string' && v.length > 0)
+                .map((v) => String(v));
+        }
+        if (Array.isArray(args.contains)) {
+            filter.contains = args.contains
+                .filter((v) => typeof v === 'string' && v.length > 0)
+                .map((v) => String(v));
+        }
+        const result = dropContext(filter);
+        return result.dropped === 0
+            ? '未剔除任何工具结果(无匹配的旧 tool 消息,或均在当前轮保护区内不可剔除)。'
+            : [
+                `已剔除 ${result.dropped} 条无关工具结果,释放约 ${result.freedTokens} tokens。`,
+                '被剔除项(已替换为存根,tool_call_id 配对不变):',
+                ...result.items.map((it) => `  - ${it.toolName} (id …${it.toolCallId})`),
+                '这些结果在后续上下文中仅保留存根标记,不再占用篇幅。',
+            ].join('\n');
+    },
+};

package/dist/tools/builtins/edit-file.js

@@ -3,7 +3,7 @@ import { resolve } from 'node:path';
 // ---------- edit_file ----------
 export const editFileTool = {
     name: 'edit_file',
-    description: 'Make a precise string replacement in a file. old_string must occur exactly once in the file and match exactly (including indentation/newlines). Use write_file for new files.',
+    description: 'Replace a string in a file. old_string must occur exactly once and match exactly (including indentation/newlines). Use write_file for new files.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/glob.js

@@ -4,8 +4,8 @@ import { getSandboxRoot, isInsideRoot } from '../../sandbox/index.js';
 // ---------- glob ----------
 export const globTool = {
     name: 'glob',
-    description: 'Find file paths matching a glob pattern (e.g. **/*.ts). Returns a list of matches (auto-excludes node_modules / .git).' +
-        ' Note: when understanding code architecture/call chains, if a .codegraph/ index exists, prefer the codegraph tool over piecing together via glob one file at a time.',
+    description: 'Find files matching a glob pattern (e.g. **/*.ts). Auto-excludes node_modules/.git.' +
+        ' For architecture/call chains, prefer codegraph.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/grep.js

@@ -5,8 +5,8 @@ import { getSandboxRoot, isInsideRoot, jailResolve } from '../../sandbox/index.j
 // ---------- grep ----------
 export const grepTool = {
     name: 'grep',
-    description: 'Search file contents by regex, returning file:line: matched lines. Recursively searches the current directory by default (excluding node_modules/.git). Optional glob to restrict file types.' +
-        ' Note: when understanding code architecture/call chains, if a .codegraph/ index exists, prefer the codegraph tool over piecing together via grep one file at a time.',
+    description: 'Search file contents by regex, returning file:line: matched lines. Recursively searches cwd excluding node_modules/.git. Optional glob restricts file types.' +
+        ' For architecture/call chains, prefer codegraph.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/index.js

@@ -10,6 +10,7 @@ import { useSkillTool } from './use-skill.js';
 import { askHumanTool } from './ask-human.js';
 import { codegraphTool } from './codegraph.js';
 import { switchModeTool } from './switch-mode.js';
+import { dropContextTool } from './drop-context.js';
 import { memorySaveTool } from './memory-save.js';
 import { memorySearchTool } from './memory-search.js';
 import { memoryListTool } from './memory-list.js';
@@ -33,6 +34,7 @@ export const builtinTools = [
     useSkillTool,
     askHumanTool,
     switchModeTool, // plan↔auto 自切(两模式都可见,不进 PLAN_DISABLED_TOOLS;副作用控制工具→串行分支)
+    dropContextTool, // 运行中剔除无关 tool 结果(上下文管理,无副作用;两模式都可见,串行分支)
     memorySaveTool,
     memorySearchTool,
     memoryListTool,

package/dist/tools/builtins/memory-forget.js

@@ -3,7 +3,7 @@ import { forgetEntry } from '../../memory/store.js';
 // 遗忘:默认归档(archived,从索引/默认搜索隐藏,可复活);mode=delete 硬删。pinned 拒删。
 export const memoryForgetTool = {
     name: 'memory_forget',
-    description: 'Forget a memory entry: by default archives (archived, hidden from index and default search, can be revived via memory_update); mode=delete hard-deletes. Pinned entries cannot be deleted (first memory_update pinned=false to unpin).',
+    description: 'Forget a memory entry: default archive (hidden, revivable via memory_update); mode=delete hard-deletes. Pinned entries can\'t be deleted (unpin first).',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/memory-list.js

@@ -3,7 +3,7 @@ import { listEntries } from '../../memory/store.js';
 // 列索引(id/name/summary,无正文、不 bump recall)。用于浏览有哪些、拿 id 再 memory_search 取正文。
 export const memoryListTool = {
     name: 'memory_list',
-    description: 'List the memory index (id/name/summary, no body). Defaults to active. Get an id, then use memory_search to retrieve the full body.',
+    description: 'List the memory index (id/name/summary, no body). Get an id, then use memory_search for the full body.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/memory-save.js

@@ -4,7 +4,7 @@ import { saveEntry } from '../../memory/store.js';
 // 撞库(name→id 已存在)拒绝,引导用 memory_update。
 export const memorySaveTool = {
     name: 'memory_save',
-    description: 'Save a long-term memory entry (cross-session). Store only non-obvious, long-term-useful facts/decisions/pitfalls. The title goes into the startup index; retrieve full body on demand via memory_search.',
+    description: 'Save a cross-session long-term memory entry. Store only non-obvious, useful facts/decisions/pitfalls. Title enters the startup index; retrieve body via memory_search.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/memory-search.js

@@ -4,7 +4,7 @@ import { searchEntries } from '../../memory/store.js';
 // 结果走 capToolResultForHistory 的放宽上限(同 use_skill,保正文完整)。
 export const memorySearchTool = {
     name: 'memory_search',
-    description: 'Search memory entries by keyword (multi-word substring match, ranked by relevance), returning full body of matching entries. A hit bumps recall count (affects forgetting decay).',
+    description: 'Search memory entries by keyword (substring match), returning full body.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/memory-update.js

@@ -3,7 +3,7 @@ import { updateEntry } from '../../memory/store.js';
 // 原地改一条记忆(id 不变)。反思的弱意义:干活时发现事实变了/过时即纠正。
 export const memoryUpdateTool = {
     name: 'memory_update',
-    description: 'Update a memory entry in place (id unchanged). Use when facts changed / correcting outdated info / updating summary or body / toggling pinned. Get id from memory_list or memory_search.',
+    description: 'Update a memory entry in place (id unchanged). Use when facts changed / correcting outdated info / toggling pinned. Get id from memory_list or memory_search.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/read-file.js

@@ -4,8 +4,8 @@ import { MAX_FILE_LINES } from '../constants.js';
 // ---------- read_file ----------
 export const readFileTool = {
     name: 'read_file',
-    description: 'Read file content, returning text with line numbers. Read before editing code. Optional offset (start line, 1-based, default 1) and limit (number of lines, default 2000).' +
-        ' Note: when understanding code architecture/call chains, if a .codegraph/ index exists, prefer the codegraph tool over piecing together via read_file one file at a time.',
+    description: 'Read file content with line numbers. Read before editing. offset (1-based, default 1), limit (default 2000).' +
+        ' For architecture/call chains, prefer codegraph over reading files one at a time.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/run-command.js

@@ -4,7 +4,7 @@ import { getSandboxRoot, filterEnv, isCommandDenied } from '../../sandbox/index.
 // ---------- run_command ----------
 export const runCommandTool = {
     name: 'run_command',
-    description: 'Execute a shell command, returning combined stdout+stderr. Default timeout 120s. Use for running tests, builds, git, etc.',
+    description: 'Run a shell command, merging stdout+stderr. Default timeout 120s. For tests, builds, git, etc.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/switch-mode.js

@@ -3,11 +3,9 @@ import { setAgentMode, getAgentMode } from '../../agent/mode.js';
 export const switchModeTool = {
     name: 'switch_mode',
     description: [
-        'Switch the agent mode between "plan" (read-only investigation + planning) and "auto" (full tool execution).',
-        'In plan mode, write_file / edit_file / run_command / memory_save / memory_update / memory_forget are disabled; in auto mode, all tools are available.',
-        'Use this to autonomously transition from planning to execution WITHIN THE SAME TURN: investigate in plan mode, produce a plan, then call switch_mode("auto") and continue implementing it in the same turn — ONLY when the user has explicitly asked you to "plan first then execute" / "先 plan 再 auto" / autonomous execution.',
-        'Do NOT switch to auto if the user entered plan mode manually (via /plan or Shift+Tab) for a safety review — in that case present the plan and STOP; the user will approve via a prompt and execution happens in a follow-up turn.',
-        'Switching to plan from auto is rarely needed; do it only if you realize you should investigate before changing anything.',
+        'Switch agent mode between "plan" (read-only investigation) and "auto" (full tool execution).',
+        'Use to transition from planning to execution WITHIN THE SAME TURN: in plan, after presenting a plan, call switch_mode("auto") and continue — ONLY when the user asked for autonomous execution ("先 plan 再 auto" etc.).',
+        'If the user entered plan mode manually (/plan or Shift+Tab) for review, do NOT switch to auto — present the plan and STOP for approval.',
     ].join(' '),
     parameters: {
         type: 'object',

package/dist/tools/builtins/task.js

@@ -9,10 +9,9 @@ import { MAX_OUTPUT } from '../constants.js';
 export const taskTool = {
     name: 'task',
     description: [
-        'Spawn a sub-agent to handle an isolated sub-task with its own conversation history (independent of the main thread). The sub-agent runs to completion and returns a concise summary.',
-        'Use when: a task can be decomposed into independent sub-tasks, you want to explore multiple files/areas without polluting the main history, or a sub-task involves many tool calls that would bloat the main context window.',
-        'The sub-agent has its own history; only its final summary is returned to you as the tool result. It cannot recursively spawn further sub-agents (no "task" tool available to it).',
-        'Optionally restrict the sub-agent to a subset of tools (e.g. read-only tools for pure investigation) via the "tools" parameter.',
+        'Spawn a sub-agent for an isolated sub-task (independent history; only its final summary returns to you).',
+        'Use when a task splits into independent parts or its many tool calls would bloat your context.',
+        'Cannot recursively spawn sub-agents.',
     ].join(''),
     parameters: {
         type: 'object',
@@ -24,7 +23,7 @@ export const taskTool = {
             tools: {
                 type: 'array',
                 items: { type: 'string' },
-                description: 'Optional whitelist of tool names the sub-agent is allowed to use (e.g. ["read_file","glob","grep","codegraph"] for read-only investigation). Omit to allow all tools.',
+                description: 'Optional whitelist of tool names the sub-agent is allowed to use (e.g. ["read_file","glob","grep","codegraph"] for read-only investigation). Omit to allow all tools. If the sub-task needs verification/build/test (running scripts, typecheck, etc.), remember to include "run_command".',
             },
             maxSteps: {
                 type: 'number',

package/dist/tools/builtins/use-skill.js

@@ -4,7 +4,7 @@ import { getSkillBody } from '../../skills/index.js';
 // 系统提示里已列出可用 skill 的 name + description(何时用),模型据此决定调用。
 export const useSkillTool = {
     name: 'use_skill',
-    description: 'Load and return the full SKILL.md instructions for a given skill (pass name). See the skill list in the system prompt for when to use each.',
+    description: 'Load the full SKILL.md instructions for a given skill. See the skill list in the system prompt for when to use each.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/web-fetch.js

@@ -4,7 +4,7 @@ const UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML,
 // ---------- web_fetch ----------
 export const webFetchTool = {
     name: 'web_fetch',
-    description: 'Fetch the web page at a given URL and clean it into plain text (strips HTML tags/scripts/styles, keeps the body). Use to read a link from search results, or a specific URL given by the user.',
+    description: 'Fetch a URL and clean HTML to body text. Use to read a link from search results or a URL given by the user.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/web-search.js

@@ -6,7 +6,7 @@ const MAX_CONTENT_CHARS = 800;
 // ---------- web_search ----------
 export const webSearchTool = {
     name: 'web_search',
-    description: 'Search the web (AnySearch). Returns title/url/snippet/body for each result. Optional tag to switch sub-domain capability (see tag param).',
+    description: 'Search the web (AnySearch). Returns title/url/snippet/body per result. Optional tag for sub-domain capability.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/write-file.js

@@ -3,7 +3,7 @@ import { resolve, dirname } from 'node:path';
 // ---------- write_file ----------
 export const writeFileTool = {
     name: 'write_file',
-    description: 'Create or overwrite a file, creating parent directories as needed.',
+    description: 'Create or overwrite a file; parent dirs created.',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/registry.js

@@ -11,6 +11,7 @@ export const tools = builtinTools;
  * signal 透传给 tool.execute(经 ctx):长任务工具(run_command/web_fetch)abort 即时取消,
  * 让用户 Ctrl+C 能跟手中断工具执行(而非等命令跑完 / 超时)。
  * opts.skipRollback:子 agent 逻辑隔离用——跳过 recordMutation,子 agent 改动不进主回滚快照链。
+ * opts.dropContext:上下文剔除回调(drop_context 工具用),透传给 tool.execute 经 ctx。
  */
 export async function executeTool(name, argsRaw, signal, opts) {
     const tool = tools.find((t) => t.name === name);
@@ -38,7 +39,11 @@ export async function executeTool(name, argsRaw, signal, opts) {
             args.path) {
             recordMutation(args.path);
         }
-        return await tool.execute(args, { signal, skipRollback: opts?.skipRollback });
+        return await tool.execute(args, {
+            signal,
+            skipRollback: opts?.skipRollback,
+            dropContext: opts?.dropContext,
+        });
     }
     catch (e) {
         return `错误:工具 ${name} 执行失败: ${e instanceof Error ? e.message : String(e)}`;