@armadra/agent 0.7.3 → 0.7.5

package/dist/tools/task.js

@@ -12,6 +12,8 @@
  * - **parallel**：同一回复里的多个 task 真并行（会话注册表的池限流，缺省 4）；与 sequential 工具
  *   （edit 等）同批时仍按 tool-runner 的规则整批串行。
  * - 深度 ≤ 1：子会话的工具表里保留 task（与父字节一致，缓存前缀可复用），运行时在这里拒绝。
+ * - [ME-A] `context: "fork"`：子会话继承本会话已完成的回合（同模型、同前缀）；`details.context` 是实际
+ *   模式（不满足条件时回落 `fresh`）。
  * - 结果 = 子 Agent 的最终报告（> 50 KB 截头尾、全文落 outputs/，见 agents/result.ts）+ details。
  */
 import { AgentCatalog } from "../agents/catalog.js";
@@ -26,15 +28,20 @@ const THINKING = [
     "high",
     "xhigh",
 ];
+/**
+ * [ME-A] 两版描述共用的开头：fresh / fork 两种上下文。default+task 与 codemode-only 的预算余量都只有
+ * 几十 token，加 `context` 参数时整段改写、字符数基本不增（`agent` 参数的「Default general」也去掉，
+ * 清单里 general 已标 default）。
+ */
+export const TASK_CONTEXT_LEAD = "Delegate to a sub-agent (fresh context: give full instructions; context fork: inherits " +
+    "this conversation).";
 /** 缺省前台（`-p`、`subagents.background: never`）时的描述。 */
-export const FOREGROUND_DESCRIPTION = "Delegate to a sub-agent (fresh context; give full instructions). Returns its final report. " +
-    "Tasks in one reply run in parallel; writers should use isolation worktree. background: " +
-    "returns a taskId now (see task_ctl); taskId: continue that task.";
+export const FOREGROUND_DESCRIPTION = `${TASK_CONTEXT_LEAD} Returns its final report. Parallel in one reply; writers use isolation ` +
+    "worktree. background: returns a taskId (see task_ctl); taskId: continue it.";
 /** [W7-B1] 缺省后台（交互 / RPC / ACP，docs/agents-concurrency-plan.md §2.6）时的描述。 */
-export const BACKGROUND_DESCRIPTION = "Delegate to a sub-agent (fresh context; give full instructions). Runs in the background by " +
-    "default: returns a taskId; a <task-notification> follows when done, so keep working. " +
-    "background:false if your next step needs the result. taskId: continue a task. Tasks in one " +
-    "reply run in parallel; writers use isolation worktree.";
+export const BACKGROUND_DESCRIPTION = `${TASK_CONTEXT_LEAD} Runs in the background by default: returns a taskId; a ` +
+    "<task-notification> follows; keep working. background:false waits for the result. " +
+    "taskId: continue it. Parallel in one reply; writers use isolation worktree.";
 /** 描述里类型清单的标题（清单本身另有 400 token 预算，见 agents/catalog.ts）。 */
 export const TASK_AGENTS_HEADING = "\nAgents:\n";
 const catalogs = new WeakMap();
@@ -68,6 +75,8 @@ export function buildSubagentRequest(input, ctx) {
         return 'isolation must be "none" or "worktree"';
     if (input.budgetUsd !== undefined && !(input.budgetUsd > 0))
         return "budgetUsd must be > 0";
+    if (input.context !== undefined && input.context !== "fork" && input.context !== "fresh")
+        return 'context must be "fork" or "fresh"';
     const request = {
         prompt: input.prompt,
         parentToolCallId: ctx.toolCallId,
@@ -96,6 +105,8 @@ export function buildSubagentRequest(input, ctx) {
         request.model = input.model;
     if (input.thinkingLevel !== undefined)
         request.thinkingLevel = input.thinkingLevel;
+    if (input.context !== undefined)
+        request.context = input.context;
     return request;
 }
 export function createTaskTool(_options = {}) {
@@ -111,7 +122,7 @@ export function createTaskTool(_options = {}) {
             type: "object",
             properties: {
                 prompt: { type: "string" },
-                agent: { type: "string", description: "Default general" },
+                agent: { type: "string" },
                 description: { type: "string" },
                 background: { type: "boolean" },
                 taskId: { type: "string" },
@@ -121,6 +132,7 @@ export function createTaskTool(_options = {}) {
                 model: { type: "string" },
                 thinkingLevel: { type: "string", enum: [...THINKING] },
                 maxTurns: { type: "integer" },
+                context: { type: "string", enum: ["fork", "fresh"] },
             },
             required: ["prompt"],
             additionalProperties: false,
@@ -145,6 +157,7 @@ export function createTaskTool(_options = {}) {
                     ...(result.status !== undefined ? { status: result.status } : {}),
                     ...(result.sessionFile !== undefined ? { sessionFile: result.sessionFile } : {}),
                     ...(result.outputFile !== undefined ? { outputFile: result.outputFile } : {}),
+                    ...(result.context !== undefined ? { context: result.context } : {}),
                     usage: result.usage,
                     stopReason: result.stopReason,
                 };

package/dist/tools/truncate.d.ts

@@ -8,6 +8,13 @@
  */
 export declare const DEFAULT_MAX_LINES = 2000;
 export declare const DEFAULT_MAX_BYTES: number;
+/** [ME-D] 自截时给说明行留的余量（字符）。 */
+export declare const RESULT_NOTE_RESERVE = 512;
+/**
+ * [ME-D] 工具自截的字节上限（D11）：会话的结果上限（`ToolContext.maxResultChars`）减去说明行余量，
+ * 不超过 50 KB——一次截到位，不再被会话层二次截中段。字节数 ≤ N 时字符数必然 ≤ N。
+ */
+export declare function toolOutputBytes(maxResultChars: number | undefined): number;
 /** grep 匹配行的字符上限。 */
 export declare const GREP_MAX_LINE_CHARS = 500;
 export interface TruncateOptions {

package/dist/tools/truncate.js

@@ -11,6 +11,17 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 export const DEFAULT_MAX_LINES = 2000;
 export const DEFAULT_MAX_BYTES = 50 * 1024;
+/** [ME-D] 自截时给说明行留的余量（字符）。 */
+export const RESULT_NOTE_RESERVE = 512;
+/**
+ * [ME-D] 工具自截的字节上限（D11）：会话的结果上限（`ToolContext.maxResultChars`）减去说明行余量，
+ * 不超过 50 KB——一次截到位，不再被会话层二次截中段。字节数 ≤ N 时字符数必然 ≤ N。
+ */
+export function toolOutputBytes(maxResultChars) {
+    if (maxResultChars === undefined)
+        return DEFAULT_MAX_BYTES;
+    return Math.max(1024, Math.min(DEFAULT_MAX_BYTES, maxResultChars - RESULT_NOTE_RESERVE));
+}
 /** grep 匹配行的字符上限。 */
 export const GREP_MAX_LINE_CHARS = 500;
 export function byteLength(text) {

package/dist/tools/types.d.ts

@@ -102,6 +102,8 @@ export interface SubagentRequest {
     isolation?: "none" | "worktree";
     /** [W5-C0] 外部 Agent 的美元预算。 */
     budgetUsd?: number;
+    /** [ME-C0] `fork`：继承父会话已完成的回合（同模型、同前缀）；缺省 `fresh`。 */
+    context?: "fork" | "fresh";
 }
 /** [W5-C0] 子 Agent 任务的终态（`subagent_end.status`）。 */
 export type SubagentStatus = "completed" | "failed" | "aborted" | "max_turns" | "interrupted";
@@ -133,6 +135,8 @@ export interface SubagentResult {
     /** [W5-C0] 结果全文（> 50 KB 截断时、后台任务的输出文件）。 */
     outputFile?: string;
     sessionRef?: SubagentSessionRef;
+    /** [ME-A] 请求了 `context: "fork"` 时的实际模式（回落为 `fresh`）；未请求 fork 时缺省。 */
+    context?: "fork" | "fresh";
 }
 /** runner 上报的进度（由注册表转成 `subagent_update` 事件）。 */
 export type SubagentEvent = {
@@ -173,6 +177,11 @@ export type SubagentEvent = {
     type: "notice";
     level: "info" | "warn";
     text: string;
+}
+/** [ME-A] ama 子会话请求了 `context: "fork"` 时的实际模式（注册表写进 `TaskInfo.context`）。 */
+ | {
+    type: "context";
+    mode: "fork" | "fresh";
 };
 export interface SubagentRunRequest {
     prompt: string;
@@ -225,6 +234,8 @@ export interface TaskInfo {
     contextWindow?: number;
     outputFile?: string;
     sessionRef?: SubagentSessionRef;
+    /** [ME-C0] 子会话的实际上下文模式（fork 回落为 fresh 时记 `fresh`）；外部 Agent 缺省。 */
+    context?: "fork" | "fresh";
 }
 /** [W5-C0] 任务注册表的只读视图（W5-G 的 `SubagentRegistry` 提供）。 */
 export interface TaskRegistryView {
@@ -243,6 +254,8 @@ export interface ToolContext {
     readonly thinkingLevel?: ModelThinkingLevel;
     /** 截断全文的落盘目录（`<sessionDir>/outputs`）；内存会话为 undefined。 */
     readonly outputDir?: string;
+    /** [ME-C0] 会话层的工具结果上限（字符）；工具据此一次截到位。宿主 / SDK 自建上下文可不给。 */
+    readonly maxResultChars?: number;
     onUpdate(partial: string): void;
     /** 本会话已 read 的绝对路径（write / edit 先读后写检查）。 */
     readonly readFiles: ReadonlySet<string>;

package/dist/trace/build-index.js

@@ -33,7 +33,17 @@ export function traceData(entry) {
         ? data
         : undefined;
 }
+/** [ME-A] fork 式子会话从父复制来的条目（首条 `ama.task{context:"fork"}` 之后到 forkedFrom 为止）。 */
+function forkInherited(entries) {
+    const head = entries[0];
+    const data = head?.type === "custom" && head.customType === TASK_CUSTOM_TYPE ? head.data : {};
+    if (!isObject(data) || data["context"] !== "fork" || typeof data["forkedFrom"] !== "string")
+        return new Set();
+    const end = entries.findIndex((entry) => entry.id === data["forkedFrom"]);
+    return new Set(entries.slice(1, end + 1).map((entry) => entry.id));
+}
 export function buildIndex(entries) {
+    const inherited = forkInherited(entries);
     const index = {
         stepByAssistant: new Map(),
         toolTiming: new Map(),
@@ -52,9 +62,11 @@ export function buildIndex(entries) {
         }
         if (entry.type === "custom" && entry.customType === TASK_CUSTOM_TYPE) {
             const data = entry.data;
-            // 子会话自己的首条没有 status，不是父会话的快照
+            // 子会话自己的首条没有 status，不是父会话的快照；fork 继承来的父快照也不算
             if (!isObject(data) || typeof data["taskId"] !== "string" || data["status"] === undefined)
                 continue;
+            if (inherited.has(entry.id))
+                continue;
             const parent = typeof data["parentToolCallId"] === "string" ? data["parentToolCallId"] : "";
             const byTask = index.tasks.get(parent) ?? new Map();
             byTask.set(data["taskId"], { data: data, entryId: entry.id });

package/dist/tui/ansi.d.ts

@@ -7,6 +7,8 @@
  * - 所有截断 / 切片在保留 SGR 样式的同时，于末尾补 `\x1b[0m`，保证「每行末尾重置样式」。
  */
 export declare const SGR_RESET = "\u001B[0m";
+/** 字素切分器，首次用到才构造（-p / RPC / ACP / --version 不付 ICU 断字数据的初始化）。 */
+export declare function graphemeSegmenter(): Intl.Segmenter;
 /** 单个码点的列宽（0 / 1 / 2）。 */
 export declare function codePointWidth(cp: number): 0 | 1 | 2;
 /** 一个字素簇的列宽：首码点决定基础宽度；VS16（U+FE0F）把文本型 emoji 升为 2 列。 */

package/dist/tui/ansi.js

@@ -7,7 +7,11 @@
  * - 所有截断 / 切片在保留 SGR 样式的同时，于末尾补 `\x1b[0m`，保证「每行末尾重置样式」。
  */
 export const SGR_RESET = "\x1b[0m";
-const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+let segmenter;
+/** 字素切分器，首次用到才构造（-p / RPC / ACP / --version 不付 ICU 断字数据的初始化）。 */
+export function graphemeSegmenter() {
+    return (segmenter ??= new Intl.Segmenter(undefined, { granularity: "grapheme" }));
+}
 /** 东亚宽（W）与全角（F）区段，含常见 emoji 区块；按起点升序，二分查找。 */
 const WIDE_RANGES = [
     [0x1100, 0x115f],
@@ -193,7 +197,7 @@ function textWidth(text) {
     if (isPlainAscii(text))
         return text.length;
     let width = 0;
-    for (const { segment } of segmenter.segment(text))
+    for (const { segment } of graphemeSegmenter().segment(text))
         width += graphemeWidth(segment);
     return width;
 }
@@ -221,7 +225,7 @@ function* pieces(s) {
                 yield { text: ch, width: 1, escape: false };
         }
         else {
-            for (const { segment } of segmenter.segment(run)) {
+            for (const { segment } of graphemeSegmenter().segment(run)) {
                 yield { text: segment, width: graphemeWidth(segment), escape: false };
             }
         }

package/dist/tui/components/editor-buffer.js

@@ -7,10 +7,10 @@
  * - 撤销：每次编辑前存快照；连续输入同类字符合并为一步；上限 50 步。
  * - 不做选区（无鼠标、无 kill ring，§12.9）。
  */
-const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+import { graphemeSegmenter } from "../ansi.js";
 function graphemeStarts(line) {
     const starts = [];
-    for (const { index } of segmenter.segment(line))
+    for (const { index } of graphemeSegmenter().segment(line))
         starts.push(index);
     starts.push(line.length);
     return starts;

package/dist/tui/components/editor.js

@@ -15,7 +15,7 @@
  */
 import { msg } from "../../i18n/index.js";
 import { CURSOR_MARKER } from "../component.js";
-import { truncateToWidth, visibleWidth } from "../ansi.js";
+import { graphemeSegmenter, truncateToWidth, visibleWidth } from "../ansi.js";
 import { defaultKeybindings } from "../keybindings.js";
 import { isPasteData, isPrintableText, unwrapPaste } from "../keys.js";
 import { plainTheme } from "../theme.js";
@@ -24,7 +24,6 @@ import { appendHistoryFile, loadHistoryFile } from "./editor-history.js";
 import { PasteStore } from "./editor-paste.js";
 import { SelectList } from "./select-list.js";
 export { loadHistoryFile } from "./editor-history.js";
-const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 /** 提示符 `› ` / 续行缩进的宽度。 */
 const PROMPT_WIDTH = 2;
 export class Editor {
@@ -290,7 +289,7 @@ export class Editor {
         const line = this.buffer.getLines()[row.line];
         let col = row.start;
         let width = 0;
-        for (const { segment, index } of segmenter.segment(line.slice(row.start, row.end))) {
+        for (const { segment, index } of graphemeSegmenter().segment(line.slice(row.start, row.end))) {
             const w = visibleWidth(segment);
             if (width + w > targetWidth)
                 break;
@@ -304,7 +303,7 @@ export class Editor {
     }
     prevGrapheme(line, col) {
         let prev = 0;
-        for (const { index } of segmenter.segment(line)) {
+        for (const { index } of graphemeSegmenter().segment(line)) {
             if (index >= col)
                 break;
             prev = index;
@@ -403,7 +402,7 @@ export class Editor {
             let start = 0;
             let used = 0;
             let pos = 0;
-            const graphemes = [...segmenter.segment(text)];
+            const graphemes = [...graphemeSegmenter().segment(text)];
             let gi = 0;
             while (gi < graphemes.length) {
                 const g = graphemes[gi];
@@ -521,7 +520,7 @@ export class Editor {
     }
 }
 function nextGrapheme(text, pos) {
-    const first = segmenter
+    const first = graphemeSegmenter()
         .segment(text.slice(pos, pos + 32))[Symbol.iterator]()
         .next();
     return first.done ? " " : first.value.segment;

package/dist/tui/keys.js

@@ -8,6 +8,7 @@
  * KeyId 形如 `ctrl+shift+up`：修饰键按 ctrl → alt → shift 排序，键名小写；
  * 可打印字符的键名就是字符本身（`a`、`/`、`中`），空格为 `space`。
  */
+import { graphemeSegmenter } from "./ansi.js";
 export const PASTE_START = "\x1b[200~";
 export const PASTE_END = "\x1b[201~";
 const NO_MODS = { ctrl: false, alt: false, shift: false };
@@ -212,10 +213,9 @@ export function parseKey(data) {
         return undefined;
     return withAlt(inner);
 }
-const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 function isSingleGrapheme(data) {
     let count = 0;
-    for (const _ of graphemeSegmenter.segment(data)) {
+    for (const _ of graphemeSegmenter().segment(data)) {
         count++;
         if (count > 1)
             return false;

package/dist/tui/stdin-buffer.js

@@ -8,6 +8,7 @@
  * - 块末尾的不完整转义序列先挂起；在 `AMA_TUI_ESC_TIMEOUT` 毫秒内没有后续数据就原样发出
  *   （孤立 ESC 即 Escape 键）。缺省：SSH / tmux 下 100 ms，本地 10 ms。
  */
+import { graphemeSegmenter } from "./ansi.js";
 import { PASTE_END, PASTE_START } from "./keys.js";
 /** 读环境：`AMA_TUI_ESC_TIMEOUT` 优先；否则 SSH / tmux 100 ms，本地 10 ms。 */
 export function defaultEscTimeout(env = process.env) {
@@ -21,7 +22,6 @@ export function defaultEscTimeout(env = process.env) {
         return 100;
     return 10;
 }
-const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 /** 从 0 开始扫描一个转义序列（buf[0] === ESC）。 */
 function scanEscape(buf) {
     if (buf.length === 1)
@@ -74,7 +74,7 @@ function scanEscape(buf) {
     }
     // Alt 前缀 + 单个字素
     const rest = buf.slice(1);
-    const first = segmenter.segment(rest.slice(0, 64))[Symbol.iterator]().next();
+    const first = graphemeSegmenter().segment(rest.slice(0, 64))[Symbol.iterator]().next();
     const segment = first.done ? rest[0] : first.value.segment;
     return { kind: "complete", length: 1 + segment.length };
 }
@@ -180,7 +180,7 @@ export class StdinBuffer {
         const c = buf.charCodeAt(0);
         if (c < 0x20 || c === 0x7f)
             return 1;
-        const first = segmenter.segment(buf.slice(0, 64))[Symbol.iterator]().next();
+        const first = graphemeSegmenter().segment(buf.slice(0, 64))[Symbol.iterator]().next();
         if (first.done)
             return 1;
         // 字素簇不能吞掉后面的 ESC 或控制字符

package/docs/acp.md

@@ -47,8 +47,15 @@ ama --mode acp                      # 与 -p 互斥；其余参数（--model、-
   「本会话允许」的记忆（切回来要重新允许，与 TUI `/resume` 一致）。
 - 权限模式按会话记：对前台会话 `set_mode` 立即生效；对其它会话只记下（照样发 `current_mode_update`），轮到它跑时
   再应用到权限管线，并再发一条 `current_mode_update`。所以对排队中的会话改模式不会影响正在跑的那个。
+- 后台子 Agent 完成后的通知回合不经这个队列，在会话空闲时自己开始；它在跑时，对同一会话的 `session/prompt` 也等它
+  结束再开始（不报 busy），等待期间客户端先收到通知回合的 `session/update`。等待中 `session/cancel` 会中断通知回合，
+  这条提示回 `cancelled`，之后也不会再被发出。这条提示答复里的 `usage` 只算它自己的回合，不含之前的通知回合。
 - 每个回合结束后发 `session_info_update`（`updatedAt`，标题变了才带 `title`）。
-- 关掉一个会话只释放它（跑 SessionEnd Hook）；stdin 关闭时排队的提示回 `cancelled`，等在跑的结束，再依次释放全部会话。
+- 关掉一个会话只释放它（跑 SessionEnd Hook），它的转录、图片与子 Agent 句柄随之可被回收，进程启动时建的那个会话
+  也一样。关闭前先让它安静下来：它的排队提示回 `cancelled`、在跑的后台子 Agent 停掉（不再发完成通知）、在跑的回合
+  （含通知回合）被中断，已排着的通知也不再开回合；`session/close` 之后该会话不再有 `session/update`。被中断的
+  通知回合与 `session/cancel` 一样在会话文件里留下中断标记。stdin 关闭时排队的提示回 `cancelled`，等在跑的提示结束，
+  通知回合与后台子 Agent 按上面的方式停下，再依次释放全部会话。
 
 ### 事件映射
 

package/docs/agents.md

@@ -39,6 +39,7 @@ thinking: low
 max-turns: 20 # 缺省 30
 isolation: none # none（缺省）| worktree
 background: false # 不写 = 按 config subagents.background
+context: fresh # fresh（缺省）| fork：继承父会话已完成的回合，见「fork 模式」
 runner: ama # ama（缺省）| claude | codex | acp:<程序>
 ---
 
@@ -69,6 +70,7 @@ runner: ama # ama（缺省）| claude | codex | acp:<程序>
 | `taskId`                                         | 续聊：向已有任务的子会话追加一条消息（忽略 `agent` / `tools` / `model`）                                                                                 |
 | `isolation`                                      | `worktree`：在独立 git worktree 里运行                                                                                                                   |
 | `budgetUsd`                                      | 外部 Agent 的美元预算                                                                                                                                    |
+| `context`                                        | `fresh`（缺省）：子会话从空白开始；`fork`：继承本会话已完成的回合（同模型、同前缀），见「fork 模式」。缺省取类型的 `context`                             |
 | `tools` / `model` / `thinkingLevel` / `maxTurns` | 保留的高级参数（描述里不展开）                                                                                                                           |
 
 同一条回复里的多个 `task` **并行**执行，由会话的任务池限流（`subagents.maxConcurrent`，缺省 4）；排队超过
@@ -77,7 +79,8 @@ runner: ama # ama（缺省）| claude | codex | acp:<程序>
 
 结果是子 Agent 的最终报告，前面带 `[task tN]`。超过 50 KB 时保留开头 70% 与结尾 30%，中间注明省略了多少字节，
 全文写到会话目录的 `outputs/<会话 id>-<taskId>.md`（内存会话写到系统临时目录）。轮数用尽且最后一步停在工具结果上时，
-ama 以「不允许调用工具」再跑一轮要最终报告，结果前加 `[Turn limit reached; …]`，状态 `max_turns`。
+ama 再跑一轮、在消息里要求「不要调用工具、直接给最终报告」，结果前加 `[Turn limit reached; …]`，状态 `max_turns`。这一轮的请求
+不发 `toolChoice`（改动它会让缓存前缀失效）；模型仍调用工具时这一轮就此结束，结果为「(the sub-agent returned no text)」。
 
 ### 前台与后台
 
@@ -127,11 +130,12 @@ ama 以「不允许调用工具」再跑一轮要最终报告，结果前加 `[T
 
 ### 续聊、保留与 resume
 
-每个任务有会话内唯一的 `taskId`（`t1`、`t2` …）。子会话结束后不立即释放，最多保留 16 个（最久未用的先释放内存；
-JSONL 一直在）。`task{taskId}` / `task_ctl send` 续聊时，保留中的直接追加消息，已释放的按会话文件重新打开再追加——
+每个任务有会话内唯一的 `taskId`（`t1`、`t2` …）。子会话结束后不立即释放，最多保留 4 个（`subagents.retainSessions`；
+最久未用的先释放内存，JSONL 一直在）。`task{taskId}` / `task_ctl send` 续聊时，保留中的直接追加消息，已释放的按会话文件重新打开再追加——
 同一个任务始终写同一个 JSONL。父会话在任务开始、每次续聊与结束时写一条 `custom{ama.task}`
 （[session-format.md](session-format.md)）；`--resume` 时据此重建任务列表，当时还在运行的标 `interrupted`，仍可续聊。
-内存会话（`--no-session`）的任务被释放后不能续聊。
+内存会话（`--no-session`）的任务被释放后不能续聊。子会话转录常达数十 MB，保留得越多常驻内存越大；频繁轮换续聊
+5 个以上任务时可调大保留数，代价只是被释放的任务续聊时多一次从磁盘重开。
 
 ### worktree 隔离
 
@@ -140,7 +144,38 @@ JSONL 一直在）。`task{taskId}` / `task_ctl send` 续聊时，保留中的
 worktree 里与父 cwd 对应的目录。结束时没有改动（工作区干净且没有新提交）就删掉 worktree 与分支；有改动则保留，结果末尾给出
 分支名、路径与 `git diff --stat`（含未跟踪文件），由你决定是否合并。`.ama/worktrees/` 下自动写一个 `.gitignore`（`*`），
 父仓库的 `git status` 与 grep / glob 都看不到这些目录。不在 git 仓库里时直接报错，不会退回共享目录。
-worktree 里的编辑不记进父会话的检查点。注意：worktree 不共享依赖（`node_modules` 等），不保证能直接构建或运行测试。
+多个隔离任务同时开始或结束时，同一仓库的 worktree 增删与删分支按顺序执行（它们都会改 `.git/worktrees`）；另一个 ama 进程同时操作时遇到的瞬时错误会短暂重试。worktree 里的编辑不记进父会话的检查点。注意：worktree 不共享依赖（`node_modules` 等），不保证能直接构建或运行测试。
+
+### fork 模式
+
+`context: "fork"`（调用参数或类型 frontmatter）的子会话**继承父会话到发起这次 `task` 之前的全部对话**：
+
+- 子会话文件复制父分支到发起调用的那条 assistant 之前（同一回复里并行的多个 fork 任务共用这个点），首条仍是
+  `custom{ama.task}`，data 多 `context: "fork"` 与 `forkedFrom`（复制的最后一条条目 id）；`parentSession` 指回父文件。
+- 系统提示与工具表与父**逐字节相同**（不加 `role` 节，`task` / `task_ctl` 仍在表里、按深度拒绝），所以子会话的首个请求
+  就是父上一次请求的前缀加一条 `<task>` 消息，前缀按读价计费；`prompt_cache_key` 沿用父链的根会话 id。
+- 角色说明与任务写在 `<task>` 消息里，声明「上面的请求属于主 Agent、只做这项任务、本块优先于上文的计划与提醒」。子会话
+  看得到父的计划、提醒与读过的文件内容，但 `read` 记录从空开始（编辑前照旧要先读）。
+- 类型声明了 `tools` / `disallowed-tools`（或参数给了 `tools`）时，工具表不变，不可用的工具在执行层拒绝
+  （`Tool "X" is not available in this session.`），并在 `<task>` 里列出。只读类型照旧走只读管线。
+- `isolation: "worktree"` 时子会话的 cwd 是 worktree，`<task>` 里说明上文的相对路径指父目录；cwd 节变化以尾部补丁发送，
+  不影响已缓存的前缀。
+
+以下情况回落为 fresh（日志记一条 info，结果 `details.context` 标 `fresh`）：调用参数或类型指定了与父不同的模型或思考级别；
+父会话还没有发出过请求；父上一次请求的输入超过（窗口 − `compaction.reserveTokens`）的一半。续聊（`taskId`）与 resume
+照原文件重开，不受影响。只在请求了 fork 时 `details.context` 才出现。
+
+何时用 fork：子任务需要你已经读过、讨论过的内容时。fork 的首个请求把父上下文整段带上，按命中价计费；fresh 只发系统提示、
+工具表与任务说明，但你得在 `prompt` 里写清全部背景，子 Agent 往往还要重新读文件。
+
+| 供应商（命中价 / 未命中价）     | 8k 父上下文 fork 一次（实测，见 [benchmarks](benchmarks/efficiency-2026-10.md)「F」） | 适合                         |
+| ------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------- |
+| DeepSeek（约 1/50）             | 命中 77%，与父自己的下一回合相同；折合约 1.9k 全价 token                              | 需要父上下文时几乎总划算     |
+| Kimi（约 1/4–1/10）             | 命中 97.5%                                                                            | 需要父上下文、且要重读较多时 |
+| OpenAI 系（经中转，不发路由键） | 两次分别 0% 与 85%，取决于中转把请求路由到哪个上游                                    | 视中转而定                   |
+| Anthropic（1/10，写入 1.25×）   | 未实测；前缀相同，命中应与父的下一回合相同                                            | 需要父上下文时               |
+
+`explore` 这类只需要定位文件的任务建议保持 fresh；内置类型都缺省 fresh。
 
 ### 事件与统计
 
@@ -154,6 +189,7 @@ RPC `get_tasks` / `get_agents` 返回任务快照与可用类型（来源、定
 | --------------------------------- | -------------------------------------------------------------------------------- |
 | `subagents.maxConcurrent`         | 同时运行的子 Agent，缺省 4                                                       |
 | `subagents.maxPending`            | 排队上限，缺省 16                                                                |
+| `subagents.retainSessions`        | 保留在内存里的已结束子会话数（LRU），缺省 4，0 = 结束即释放；只认用户级          |
 | `subagents.defaultModel`          | 子 Agent 缺省模型，不设继承父会话                                                |
 | `subagents.background`            | `auto`（缺省）\| `always` \| `never`，见「前台与后台」；用户 / 项目 / 宿主级都认 |
 | `subagents.autoBackgroundAfterMs` | 前台任务运行超过该毫秒数自动转后台，缺省 0（关闭）；用户 / 项目级都认            |
@@ -165,7 +201,7 @@ RPC `get_tasks` / `get_agents` 返回任务快照与可用类型（来源、定
 
 - 子 Agent 不能再委派（深度 1）；协调多个 Agent 的场景交给宿主（如 Armadra 画布）。
 - 只读类型的 bash 只放行 plan 模式认可的只读命令，识别不了的一律拒绝，宁可少用。
-- 不读取 `.claude/agents`；不支持 fork 模式（继承父对话的子 Agent）。
+- 不读取 `.claude/agents`。fork 模式只用父的模型与思考级别（不同则回落 fresh），外部 Agent 不支持 fork。
 
 ## 外部 Agent
 

package/docs/codemode.md

@@ -34,7 +34,7 @@
 { "version": 1, "tools": { "preset": "codemode-only" }, "permission": { "allow": ["codemode"] } }
 ```
 
-其它配置：`codemode.inlineBudget`（`only` 模式在描述里内联声明的预算，估算 token，缺省 3000，超出只列名字；`on` 模式不内联）、`codemode.requireStrict`（见下文沙箱）。项目级配置只能把 `codemode.mode` 设为 `off`。
+其它配置：`codemode.inlineBudget`（`only` 模式在描述里内联声明的预算，估算 token，缺省 3000，超出只列名字；`on` 模式不内联）、`codemode.requireStrict`（见下文沙箱）、`codemode.maxHeapMb`（脚本子进程的堆上限，见下文沙箱）。项目级配置只能把 `codemode.mode` 设为 `off`。
 
 `on` 模式的前缀开销：去重前 `codemode` 描述把已直接暴露的六个工具的声明又内联一遍，其它工具各追加一行提示，系统提示 + 工具表比 `off` 多约 1356 token；现在只多约 390 token（字符 / 4 估算，测试锁定 ≤ 500）。升级后续接的旧会话因为描述字节变化会有一次缓存未命中。
 
@@ -94,9 +94,11 @@
 每次执行起一个子进程：
 
 ```text
-<node> --permission --allow-fs-read=<ama-sandbox.cjs> --disallow-code-generation-from-strings <ama-sandbox.cjs> --ama-codemode-sandbox
+<node> --max-old-space-size=256 --permission --allow-fs-read=<ama-sandbox.cjs> --disallow-code-generation-from-strings <ama-sandbox.cjs> --ama-codemode-sandbox
 ```
 
+- 堆上限：`--max-old-space-size` 取 `codemode.maxHeapMb`（缺省 256 MB，0 不加；只认用户级）。脚本超出时子进程 OOM 退出，工具结果是脚本错误 `Script exceeded the codemode memory limit (256 MB); process the data in smaller pieces`，宿主进程内存不受影响；需要一次处理大数据时调大或分片。
+
 - 空环境启动，拿不到密钥、会话文件与环境变量（Windows 上 libuv 会从父进程补入 PATH、SYSTEMROOT、USERPROFILE 等系统变量，不含密钥）；不授予文件写、子进程、worker、addon、inspector 权限；Node 22.0–22.12 用 `--experimental-permission`；嵌入 Electron 时设 `ELECTRON_RUN_AS_NODE=1`。
 - 子进程里用 `node:vm` 建只含 ECMAScript 内建对象的上下文（`codeGeneration: { strings: false, wasm: false }`，沙箱对象空原型）；全局函数都在上下文内定义，只经一个宿主函数交换 JSON 字符串；子进程主 realm 也禁止字符串生成代码，经构造器链逃逸拿不到 `Function("return process")`。
 - `tools.*` 经 stdin / stdout 的 JSON 行协议回调父进程执行。

package/docs/en/acp.md

@@ -2,7 +2,7 @@
 
 English · [简体中文](../acp.md)
 
-> Translated from the Chinese [docs/acp.md](../acp.md) as of commit `bd37706`. When the two differ, the Chinese version is
+> Translated from the Chinese [docs/acp.md](../acp.md) as of commit `f6419be`. When the two differ, the Chinese version is
 > authoritative.
 
 ama works on both sides of ACP:
@@ -47,8 +47,9 @@ One `ama --mode acp` process can keep several sessions open (Zed's threads share
 - **One turn runs at a time**: while another session runs, `session/prompt` goes into a FIFO queue and starts when the previous turn ends; it no longer fails busy. `session/new`, `load`, `resume`, `list`, `set_mode`, `set_config_option` and `close` can be called at any time.
 - When a turn starts, its session becomes the "foreground" session: the host (`HostApi.session.*`), the common fields of hooks and the session seen by tools all switch to it, and "allowed for this session" grants are cleared (switching back means allowing again, as with `/resume` in the TUI).
 - Permission modes are kept per session: `set_mode` on the foreground session applies at once; on another session it is only recorded (a `current_mode_update` is still sent) and applied to the permission pipeline when that session's turn starts, with another `current_mode_update`. So changing the mode of a queued session does not affect the one that is running.
+- The notification turn that follows a finished background subagent does not go through this queue; it starts on its own once the session is idle. While it runs, `session/prompt` on the same session also waits for it to end (no busy error), and the client sees the notification turn's `session/update` first. `session/cancel` while waiting interrupts the notification turn; the prompt answers `cancelled` and is not sent later either. The `usage` in that prompt's answer covers only its own turn, not the notification turn before it.
 - After every turn a `session_info_update` is sent (`updatedAt`; `title` only when it changed).
-- Closing a session releases only that session (running the SessionEnd hook); when stdin closes, queued prompts answer `cancelled`, the running turn is allowed to finish, then all sessions are released in turn.
+- Closing a session releases only that session (running the SessionEnd hook), and its transcript, images and subagent handles can then be garbage-collected, including the session created at process start. The session is quieted first: its queued prompts answer `cancelled`, running background subagents are stopped (no completion notification), the running turn (notification turns included) is interrupted and notifications already queued no longer start a turn; after `session/close` that session sends no more `session/update`. An interrupted notification turn leaves an interruption marker in the session file, as `session/cancel` does. When stdin closes, queued prompts answer `cancelled`, running prompts are allowed to finish, notification turns and background subagents are stopped as above, then all sessions are released in turn.
 
 ### Event mapping
 

package/docs/en/host-api.md

@@ -2,7 +2,7 @@
 
 English · [简体中文](../host-api.md)
 
-> Translated from the Chinese [docs/host-api.md](../host-api.md) as of commit `0065cf4`. When the two differ, the Chinese
+> Translated from the Chinese [docs/host-api.md](../host-api.md) as of commit `979608b`. When the two differ, the Chinese
 > version is authoritative.
 
 A host adapter is a local JS module that ama loads at startup and hands a `HostApi`. With it the adapter can register tools, append to the system prompt, observe events, answer approvals, inject user messages and show notifications and status in the interface. The Armadra canvas plugs in as a host adapter (the canvas tools `canvas_*` / `context_*` are all registered by the adapter). The types are defined in `src/host/types.ts` and exported from `@armadra/agent/host`; `HOST_API_VERSION = 1`. The design rationale is in [design.md](../design.md) §6.2, §6.3 and §11.1 step 13 (Chinese).

package/docs/en/permissions.md

@@ -2,7 +2,7 @@
 
 English · [简体中文](../permissions.md)
 
-> Translated from the Chinese [docs/permissions.md](../permissions.md) as of commit `ee89edb`. When the two differ, the
+> Translated from the Chinese [docs/permissions.md](../permissions.md) as of commit `6b5455a`. When the two differ, the
 > Chinese version is authoritative.
 
 This document covers ama's six permission modes, the decision order for every tool call, and how the three tiers of `auto` mode, "rule tier → static judgement → model classifier", decide between allowing and asking. The overall design is in [design.md](../design.md) §6.3 and §7 (Chinese); hook input and output are in [hooks.md](../hooks.md) (Chinese).
@@ -172,7 +172,7 @@ It only handles calls neither ① nor ② decided (e.g. `rm old.txt`, `node scri
 - **A separate request**: it never enters the session transcript and does not change the main session's messages or prefix (the main session's prompt cache is unaffected), and does not trigger warming; the request purpose is `purpose: "classify"`.
 - **Input**: tool name, arguments (JSON, truncated to 4000 characters), cwd, project root, and a summary of the latest user message (truncated to 600 characters). Arguments and the user message sit inside a `<tool_call_data>` … `</tool_call_data>` data block, with end markers inside the block escaped; the system prompt requires treating everything inside as data and ignoring instructions in it (including things like "ignore previous instructions" or "respond allow"), leaning to ask when such text appears.
 - **Output**: strict JSON `{"decision":"allow"|"ask","reason":"…"}`. A parse failure, a timeout (10 s) or a request error → ask.
-- **Model**: `permission.autoModel` (`provider/model`); defaults to the current session model. A cheap, fast model is recommended, e.g. `packy/qwen3.8-flash`. `maxTokens` 256, thinking off.
+- **Model**: `permission.autoModel` (`provider/model`); when unset (or not found), the small model from the session provider's catalog (the file-level `small`: deepseek → `deepseek-flash`, anthropic → `claude-haiku-4-5`, openai → `gpt-6-luna`, google → `gemini-3.5-flash-lite`, moonshot → `kimi-k2.6` and so on; it must be found and have a key), otherwise the current session model; the chosen model is logged once at debug level. Relays and custom providers have no catalog small model and keep the session model. A cheap, fast model is recommended, e.g. `packy/qwen3.8-flash`. `maxTokens` 256, thinking off.
 - **Caching**: successful decisions are cached within the session by "tool name + normalized arguments" (bash collapses whitespace, others use JSON with sorted keys), so identical calls are classified once; errors and timeouts are not cached.
 - **Cost**: each classification records a `usage` entry with `kind: "permission_classify"`, counted in `/session` cost and RPC stats, never in the context.
 - The classifier can only judge undecided calls as allow or ask; it cannot overturn ①'s deny or ask.