@armadra/agent 0.7.4 → 0.7.6

package/dist/tools/background-jobs.js

@@ -5,7 +5,7 @@
  *   这里只拿到 ChildProcess；stdout / stderr 直接写进 `outputPath`（文件描述符交给子进程，ama 退出也不
  *   会因管道断开而 SIGPIPE）。POSIX 自成进程组并登记（进程退出时同步 SIGKILL 残留组）。
  * - `wait(id, timeoutMs)`：等到退出或超时；`stop(id)`：杀整棵树（SIGTERM → 宽限 → SIGKILL）；
- *   `output(id)`：读输出文件尾部（2000 行 / 50 KB）。
+ *   `output(id, options?)`：读输出文件尾部（缺省 2000 行 / 50 KB，调用方可传字节上限）。
  * - 生命周期事件经 `onChange` 发出（started / exited / stopped）；`takeExited()` 取走尚未通知的已退出
  *   任务（提醒通道 reminders.ts 据此告诉模型「后台命令 jobId 已退出（码 N）」）。
  * - 按会话 id 登记（`jobsForSession`）；`disposeSessionJobs` 在会话 dispose 时回收进程树。
@@ -119,8 +119,8 @@ export class BackgroundJobs {
         await entry.done;
         return entry.job;
     }
-    /** 输出文件尾部（2000 行 / 50 KB）。 */
-    output(id) {
+    /** 输出文件尾部（缺省 2000 行 / 50 KB；调用方可传字节上限，#155）。 */
+    output(id, options = {}) {
         const entry = this.entries.get(id);
         if (entry === undefined)
             return undefined;
@@ -132,7 +132,7 @@ export class BackgroundJobs {
         catch {
             // 输出文件被删：按空输出
         }
-        return { ...truncateTail(text), job: entry.job };
+        return { ...truncateTail(text, options), job: entry.job };
     }
     /** 取走已退出、尚未通知的任务（提醒通道用；wait 已看到退出的也算已知）。 */
     takeExited() {

package/dist/tools/bash.d.ts

@@ -9,7 +9,8 @@
  * - 注入 `AMA_*` 环境变量（shell.ts）。shell 退出后不等仍占着管道的后台进程。
  * - [W5-H2] 后台命令（§8.3 H6，不加新工具）：`{ command, background: true }` 立即返回
  *   `{ jobId, outputPath, pid }`；`{ job, action: "wait" | "output" | "stop" }` 查询 / 结束
- *   （background-jobs.ts，按会话登记，会话 dispose 时回收进程树；退出经提醒通道通知）。
+ *   （background-jobs.ts，按会话登记，会话 dispose 时回收进程树；退出经提醒通道通知）。查询输出同样按
+ *   会话结果上限尾截断（#155）。
  * - **进程只在 `spawnShell` 里创建**（前台与后台共用）。[S2] `sandbox.bash: auto` 且有能限制写入的
  *   OS 沙箱时在这一处包一层（src/sandbox/bash.ts）；`sandbox: false` 不包装（权限管线照常审批）。
  *   失败输出像是被沙箱拒绝时末尾追加一行说明。

package/dist/tools/bash.js

@@ -9,7 +9,8 @@
  * - 注入 `AMA_*` 环境变量（shell.ts）。shell 退出后不等仍占着管道的后台进程。
  * - [W5-H2] 后台命令（§8.3 H6，不加新工具）：`{ command, background: true }` 立即返回
  *   `{ jobId, outputPath, pid }`；`{ job, action: "wait" | "output" | "stop" }` 查询 / 结束
- *   （background-jobs.ts，按会话登记，会话 dispose 时回收进程树；退出经提醒通道通知）。
+ *   （background-jobs.ts，按会话登记，会话 dispose 时回收进程树；退出经提醒通道通知）。查询输出同样按
+ *   会话结果上限尾截断（#155）。
  * - **进程只在 `spawnShell` 里创建**（前台与后台共用）。[S2] `sandbox.bash: auto` 且有能限制写入的
  *   OS 沙箱时在这一处包一层（src/sandbox/bash.ts）；`sandbox: false` 不包装（权限管线照常审批）。
  *   失败输出像是被沙箱拒绝时末尾追加一行说明。
@@ -304,7 +305,7 @@ async function jobAction(input, ctx, options) {
     }
     if (action === "stop") {
         const job = (await jobs.stop(id));
-        const out = jobs.output(id);
+        const out = jobs.output(id, { maxBytes: toolOutputBytes(ctx.maxResultChars) });
         const text = out?.content ?? "";
         return {
             content: `${text === "" ? "(no output)" : text}\n\n${jobStatusLine(job)}`,
@@ -317,7 +318,7 @@ async function jobAction(input, ctx, options) {
             return fail(`timeoutMs must be between 1 and ${MAX_BASH_TIMEOUT_MS}`);
         await jobs.wait(id, waitMs, ctx.signal);
     }
-    const out = jobs.output(id);
+    const out = jobs.output(id, { maxBytes: toolOutputBytes(ctx.maxResultChars) });
     if (out === undefined)
         return fail(`Unknown background job ${id}`);
     const job = out.job;

package/dist/tools/read-lines.d.ts

@@ -10,6 +10,9 @@
  * - 按行解码：终止符都是 ASCII，不会落在多字节序列中间，无效字节的替换结果与整段解码相同；
  * - 窗口内单行超过 `maxBytes + LINE_SLACK` 字节时只留开头（这一行必然触发字节截断，
  *   `truncateHead` 至多取它开头 `maxBytes` 字节），超长行不会整行进内存。
+ *
+ * 解析状态机是 `LineScanner`，同步版 `readLineWindow` 与异步版 `readLineWindowAsync` 共用（#171）：
+ * 异步版每块一次 `await`，大文件扫描期间不独占事件循环；峰值内存相同（仍一块缓冲）。
  */
 /** 超过这个大小的文本文件走字节窗口；不超过的保留整读路径。 */
 export declare const STREAM_READ_THRESHOLD: number;
@@ -25,8 +28,44 @@ export interface LineWindow {
 }
 /** 文件开头至多 `bytes` 字节（一次 `readSync`，用于二进制嗅探）。 */
 export declare function readHead(abs: string, bytes: number): Buffer;
+/** `readHead` 的异步版（#171）。 */
+export declare function readHeadAsync(abs: string, bytes: number): Promise<Buffer>;
+/**
+ * 按块喂入文件字节的行扫描状态机：第 `first` 行（0 起）到第 `stop` 行（不含）之间的行被收集，
+ * 收集的行累计 `字节 + 1` 超过 `maxBytes` 后停止收集（含越界的那一行），其余行只计数。
+ */
+export declare class LineScanner {
+    private readonly first;
+    private readonly stop;
+    private readonly maxBytes;
+    private readonly lineCap;
+    private readonly lines;
+    private truncatedBy;
+    private collected;
+    private index;
+    private parts;
+    private partBytes;
+    private pending;
+    private skipLF;
+    private bom;
+    private firstChunk;
+    constructor(first: number, stop: number, maxBytes: number);
+    /**
+     * 处理 `buf[0, end)`；`eof` 表示这是最后一块。返回调用方下次读取前应保留在 `buf` 开头的字节数
+     * （只在首块不足 3 字节、还判断不了 BOM 时非零）。
+     */
+    feed(buf: Buffer, end: number, eof: boolean): number;
+    /** 文件读完：收尾最后一行并给出结果。 */
+    finish(): LineWindow;
+    private collecting;
+    private take;
+    private endLine;
+}
 /**
  * 读取 `abs` 第 `offset` 行（1 起）开始的至多 `limit` 行（`undefined` 不限，`0` 只计数）；
  * 收集的行累计 `字节 + 1` 超过 `maxBytes` 后停止收集（含越界的那一行）。`chunkBytes` 只供测试。
+ * 同步版，保留给单测与口径比对；`read` 工具用 `readLineWindowAsync`。
  */
 export declare function readLineWindow(abs: string, offset: number, limit: number | undefined, maxBytes: number, chunkBytes?: number): LineWindow;
+/** `readLineWindow` 的异步版（#171）：每块一次 `await`，结果与同步版相同。 */
+export declare function readLineWindowAsync(abs: string, offset: number, limit: number | undefined, maxBytes: number, chunkBytes?: number): Promise<LineWindow>;

package/dist/tools/read-lines.js

@@ -10,8 +10,12 @@
  * - 按行解码：终止符都是 ASCII，不会落在多字节序列中间，无效字节的替换结果与整段解码相同；
  * - 窗口内单行超过 `maxBytes + LINE_SLACK` 字节时只留开头（这一行必然触发字节截断，
  *   `truncateHead` 至多取它开头 `maxBytes` 字节），超长行不会整行进内存。
+ *
+ * 解析状态机是 `LineScanner`，同步版 `readLineWindow` 与异步版 `readLineWindowAsync` 共用（#171）：
+ * 异步版每块一次 `await`，大文件扫描期间不独占事件循环；峰值内存相同（仍一块缓冲）。
  */
 import { closeSync, openSync, readSync } from "node:fs";
+import { open } from "node:fs/promises";
 /** 超过这个大小的文本文件走字节窗口；不超过的保留整读路径。 */
 export const STREAM_READ_THRESHOLD = 1024 * 1024;
 const CHUNK_BYTES = 64 * 1024;
@@ -37,111 +41,184 @@ export function readHead(abs, bytes) {
         closeSync(fd);
     }
 }
+/** `readHead` 的异步版（#171）。 */
+export async function readHeadAsync(abs, bytes) {
+    const handle = await open(abs, "r");
+    try {
+        const buf = Buffer.alloc(bytes);
+        let got = 0;
+        while (got < bytes) {
+            const { bytesRead } = await handle.read(buf, got, bytes - got, null);
+            if (bytesRead === 0)
+                break;
+            got += bytesRead;
+        }
+        return buf.subarray(0, got);
+    }
+    finally {
+        await handle.close();
+    }
+}
 /**
- * 读取 `abs` 第 `offset` 行（1 起）开始的至多 `limit` 行（`undefined` 不限，`0` 只计数）；
- * 收集的行累计 `字节 + 1` 超过 `maxBytes` 后停止收集（含越界的那一行）。`chunkBytes` 只供测试。
+ * 按块喂入文件字节的行扫描状态机：第 `first` 行（0 起）到第 `stop` 行（不含）之间的行被收集，
+ * 收集的行累计 `字节 + 1` 超过 `maxBytes` 后停止收集（含越界的那一行），其余行只计数。
  */
-export function readLineWindow(abs, offset, limit, maxBytes, chunkBytes = CHUNK_BYTES) {
-    const first = offset - 1;
-    const stop = limit === undefined ? Infinity : first + limit;
-    const lineCap = maxBytes + LINE_SLACK;
-    const lines = [];
-    let truncatedBy;
-    let collected = 0;
-    let index = 0; // 已完成的行数
-    let parts = [];
-    let partBytes = 0;
-    let pending = false; // 最后一个终止符之后已有字节
-    let skipLF = false; // 上一块以 `\r` 结尾：下一块开头的 `\n` 属于同一终止符
-    let bom = false;
-    const collecting = () => truncatedBy === undefined && index >= first && index < stop;
-    const take = (buf, from, to) => {
-        if (to <= from || partBytes >= lineCap)
+export class LineScanner {
+    first;
+    stop;
+    maxBytes;
+    lineCap;
+    lines = [];
+    truncatedBy;
+    collected = 0;
+    index = 0; // 已完成的行数
+    parts = [];
+    partBytes = 0;
+    pending = false; // 最后一个终止符之后已有字节
+    skipLF = false; // 上一块以 `\r` 结尾：下一块开头的 `\n` 属于同一终止符
+    bom = false;
+    firstChunk = true;
+    constructor(first, stop, maxBytes) {
+        this.first = first;
+        this.stop = stop;
+        this.maxBytes = maxBytes;
+        this.lineCap = maxBytes + LINE_SLACK;
+    }
+    /**
+     * 处理 `buf[0, end)`；`eof` 表示这是最后一块。返回调用方下次读取前应保留在 `buf` 开头的字节数
+     * （只在首块不足 3 字节、还判断不了 BOM 时非零）。
+     */
+    feed(buf, end, eof) {
+        let pos = 0;
+        if (this.firstChunk) {
+            if (end < 3 && !eof)
+                return end;
+            this.firstChunk = false;
+            if (end >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf) {
+                this.bom = true;
+                pos = 3;
+            }
+        }
+        if (this.skipLF && pos < end) {
+            if (buf[pos] === LF)
+                pos++;
+            this.skipLF = false;
+        }
+        let nextLF = buf.indexOf(LF, pos);
+        let nextCR = buf.indexOf(CR, pos);
+        while (pos < end) {
+            if (nextLF !== -1 && nextLF < pos)
+                nextLF = buf.indexOf(LF, pos);
+            if (nextCR !== -1 && nextCR < pos)
+                nextCR = buf.indexOf(CR, pos);
+            const lf = nextLF === -1 || nextLF >= end ? end : nextLF;
+            const cr = nextCR === -1 || nextCR >= end ? end : nextCR;
+            const at = Math.min(lf, cr);
+            if (at > pos) {
+                this.pending = true;
+                if (this.collecting())
+                    this.take(buf, pos, at);
+            }
+            if (at === end)
+                break;
+            this.endLine();
+            pos = at + 1;
+            if (at === cr) {
+                if (pos < end) {
+                    if (buf[pos] === LF)
+                        pos++;
+                }
+                else {
+                    this.skipLF = true;
+                }
+            }
+        }
+        return 0;
+    }
+    /** 文件读完：收尾最后一行并给出结果。 */
+    finish() {
+        if (this.pending)
+            this.endLine();
+        const { lines, truncatedBy, bom } = this;
+        return { lines, totalLines: this.index, ...(truncatedBy ? { truncatedBy } : {}), bom };
+    }
+    collecting() {
+        return this.truncatedBy === undefined && this.index >= this.first && this.index < this.stop;
+    }
+    take(buf, from, to) {
+        if (to <= from || this.partBytes >= this.lineCap)
             return;
-        const end = Math.min(to, from + lineCap - partBytes);
-        parts.push(Buffer.from(buf.subarray(from, end)));
-        partBytes += end - from;
-    };
-    const finish = () => {
-        if (collecting()) {
+        const end = Math.min(to, from + this.lineCap - this.partBytes);
+        this.parts.push(Buffer.from(buf.subarray(from, end)));
+        this.partBytes += end - from;
+    }
+    endLine() {
+        if (this.collecting()) {
+            const { parts } = this;
             const line = (parts.length === 1 ? parts[0] : Buffer.concat(parts)).toString("utf8");
-            lines.push(line);
-            collected += Buffer.byteLength(line) + 1;
-            if (collected > maxBytes)
-                truncatedBy = "bytes";
+            this.lines.push(line);
+            this.collected += Buffer.byteLength(line) + 1;
+            if (this.collected > this.maxBytes)
+                this.truncatedBy = "bytes";
         }
-        if (partBytes > 0)
-            parts = []; // 窗口外的行不分配：40 万行时每行一个空数组就是十几 MB 临时垃圾
-        partBytes = 0;
-        pending = false;
-        index++;
-    };
+        if (this.partBytes > 0)
+            this.parts = []; // 窗口外的行不分配：40 万行时每行一个空数组就是十几 MB 临时垃圾
+        this.partBytes = 0;
+        this.pending = false;
+        this.index++;
+    }
+}
+function scanner(offset, limit, maxBytes) {
+    const first = offset - 1;
+    return new LineScanner(first, limit === undefined ? Infinity : first + limit, maxBytes);
+}
+/**
+ * 读取 `abs` 第 `offset` 行（1 起）开始的至多 `limit` 行（`undefined` 不限，`0` 只计数）；
+ * 收集的行累计 `字节 + 1` 超过 `maxBytes` 后停止收集（含越界的那一行）。`chunkBytes` 只供测试。
+ * 同步版，保留给单测与口径比对；`read` 工具用 `readLineWindowAsync`。
+ */
+export function readLineWindow(abs, offset, limit, maxBytes, chunkBytes = CHUNK_BYTES) {
+    const scan = scanner(offset, limit, maxBytes);
     const size = Math.max(3, chunkBytes);
     const fd = openSync(abs, "r");
     try {
         const buf = Buffer.alloc(size);
         let carry = 0; // 首块凑满 3 字节判断 BOM
-        let firstChunk = true;
         for (;;) {
             const n = readSync(fd, buf, carry, size - carry, null);
             const end = carry + n;
-            carry = 0;
-            if (n === 0 && end === 0)
+            if (end === 0)
                 break;
-            let pos = 0;
-            if (firstChunk) {
-                if (end < 3 && n > 0) {
-                    carry = end;
-                    continue;
-                }
-                firstChunk = false;
-                if (end >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf) {
-                    bom = true;
-                    pos = 3;
-                }
-            }
-            if (skipLF && pos < end) {
-                if (buf[pos] === LF)
-                    pos++;
-                skipLF = false;
-            }
-            let nextLF = buf.indexOf(LF, pos);
-            let nextCR = buf.indexOf(CR, pos);
-            while (pos < end) {
-                if (nextLF !== -1 && nextLF < pos)
-                    nextLF = buf.indexOf(LF, pos);
-                if (nextCR !== -1 && nextCR < pos)
-                    nextCR = buf.indexOf(CR, pos);
-                const lf = nextLF === -1 || nextLF >= end ? end : nextLF;
-                const cr = nextCR === -1 || nextCR >= end ? end : nextCR;
-                const at = Math.min(lf, cr);
-                if (at > pos) {
-                    pending = true;
-                    if (collecting())
-                        take(buf, pos, at);
-                }
-                if (at === end)
-                    break;
-                finish();
-                pos = at + 1;
-                if (at === cr) {
-                    if (pos < end) {
-                        if (buf[pos] === LF)
-                            pos++;
-                    }
-                    else {
-                        skipLF = true;
-                    }
-                }
-            }
+            carry = scan.feed(buf, end, n === 0);
             if (n === 0)
                 break;
         }
-        if (pending)
-            finish();
     }
     finally {
         closeSync(fd);
     }
-    return { lines, totalLines: index, ...(truncatedBy ? { truncatedBy } : {}), bom };
+    return scan.finish();
+}
+/** `readLineWindow` 的异步版（#171）：每块一次 `await`，结果与同步版相同。 */
+export async function readLineWindowAsync(abs, offset, limit, maxBytes, chunkBytes = CHUNK_BYTES) {
+    const scan = scanner(offset, limit, maxBytes);
+    const size = Math.max(3, chunkBytes);
+    const handle = await open(abs, "r");
+    try {
+        const buf = Buffer.alloc(size);
+        let carry = 0;
+        for (;;) {
+            const { bytesRead: n } = await handle.read(buf, carry, size - carry, null);
+            const end = carry + n;
+            if (end === 0)
+                break;
+            carry = scan.feed(buf, end, n === 0);
+            if (n === 0)
+                break;
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    return scan.finish();
 }

package/dist/tools/read.js

@@ -13,7 +13,7 @@ import { internImage } from "../ai/image-intern.js";
 import { displayPath, resolvePath } from "./paths.js";
 import { DEFAULT_MAX_LINES, formatSize, toolOutputBytes, truncateHead } from "./truncate.js";
 import { normalizeToLF, splitBom } from "./edit-fuzzy.js";
-import { STREAM_READ_THRESHOLD, readHead, readLineWindow } from "./read-lines.js";
+import { STREAM_READ_THRESHOLD, readHeadAsync, readLineWindowAsync } from "./read-lines.js";
 import { MAX_IMAGE_FILE_BYTES, fitImage, imageMimeFromPath, imageSize, sniffImageMime, } from "./image-file.js";
 export { imageSize } from "./image-file.js";
 const SNIFF_BYTES = 8000;
@@ -99,10 +99,10 @@ export async function executeRead(input, ctx, options = {}) {
     let selected;
     if (info.size > (options.streamThreshold ?? STREAM_READ_THRESHOLD)) {
         // [M-E] 大文件按字节窗口读：只解码要显示的行，结果与整读逐字节相同（D1）
-        if (isBinary(readHead(abs, SNIFF_BYTES)))
+        if (isBinary(await readHeadAsync(abs, SNIFF_BYTES)))
             return error(binaryMessage(shown));
         const want = Math.min(input.limit ?? Infinity, DEFAULT_MAX_LINES + 1);
-        const win = readLineWindow(abs, badOffset ? 1 : offset, badOffset || badLimit ? 0 : want, maxBytes);
+        const win = await readLineWindowAsync(abs, badOffset ? 1 : offset, badOffset || badLimit ? 0 : want, maxBytes);
         totalLines = win.totalLines;
         selected = win.lines;
     }

package/dist/tools/task-ctl.js

@@ -12,6 +12,7 @@
  */
 import { capTaskText, formatTokens, waitDetachedText } from "../agents/result.js";
 import { taskControl } from "../agents/task-control.js";
+import { nestedTaskRejection } from "./task.js";
 export const TASK_CTL_TOOL = "task_ctl";
 export const DEFAULT_WAIT_MS = 30_000;
 export const MAX_WAIT_MS = 600_000;
@@ -66,7 +67,7 @@ export function createTaskCtlTool() {
         annotations: { pollable: true },
         async execute(input, ctx) {
             if (ctx.depth >= 1)
-                return fail("task_ctl is not available inside a sub-agent.");
+                return fail(nestedTaskRejection(ctx, "task_ctl", "task_ctl is not available inside a sub-agent."));
             const control = taskControl(ctx.sessionId);
             if (input.action === "list") {
                 const tasks = control?.list() ?? ctx.tasks?.list() ?? [];

package/dist/tools/task.d.ts

@@ -20,6 +20,15 @@ import type { ModelThinkingLevel } from "../ai/types.js";
 import { AgentCatalog } from "../agents/catalog.js";
 import type { SubagentRequest, ToolContext, ToolDefinition } from "./types.js";
 export declare const MAX_TASK_DEPTH = 1;
+/** <task> 指令首个非空行，超长截断（#191：fork 子会话被拒时提醒模型回到子任务）。 */
+export declare function taskLine(prompt: string): string;
+/** fork 子会话的标记条目（custom，不进上下文）：`{ taskLine }`。 */
+export declare const FORK_CUSTOM_TYPE = "ama.fork";
+/**
+ * 子会话里 task / task_ctl 的拒绝文案（固定英文）。#191：fork 子会话（有 `ama.fork` 条目）说明身份并
+ * 附 <task> 首行；其它情况用 `fallback`（fresh 按深度拒绝的原文案）。
+ */
+export declare function nestedTaskRejection(ctx: ToolContext, tool: string, fallback: string): string;
 export declare const DEFAULT_TASK_MAX_TURNS = 30;
 export interface TaskInput {
     prompt: string;

package/dist/tools/task.js

@@ -19,6 +19,32 @@
 import { AgentCatalog } from "../agents/catalog.js";
 import { TASK_NOTIFICATION_RULE } from "../agents/result.js";
 export const MAX_TASK_DEPTH = 1;
+/** fork 子会话首条 custom 条目里 <task> 指令首行摘要的上限（字符）。 */
+const TASK_LINE_MAX = 120;
+/** <task> 指令首个非空行，超长截断（#191：fork 子会话被拒时提醒模型回到子任务）。 */
+export function taskLine(prompt) {
+    const line = prompt
+        .split("\n")
+        .find((text) => text.trim() !== "")
+        ?.trim() ?? "";
+    return line.length > TASK_LINE_MAX ? `${line.slice(0, TASK_LINE_MAX - 1)}…` : line;
+}
+/** fork 子会话的标记条目（custom，不进上下文）：`{ taskLine }`。 */
+export const FORK_CUSTOM_TYPE = "ama.fork";
+/**
+ * 子会话里 task / task_ctl 的拒绝文案（固定英文）。#191：fork 子会话（有 `ama.fork` 条目）说明身份并
+ * 附 <task> 首行；其它情况用 `fallback`（fresh 按深度拒绝的原文案）。
+ */
+export function nestedTaskRejection(ctx, tool, fallback) {
+    const mark = ctx.session.lastCustom(FORK_CUSTOM_TYPE);
+    if (mark === undefined || mark === null)
+        return fallback;
+    const line = typeof mark.taskLine === "string" ? mark.taskLine : "";
+    return (`${tool} rejected: you are a sub-agent forked from the main conversation and cannot start ` +
+        "or manage sub-agents. Do not call task or task_ctl again; complete the sub-task in your " +
+        "<task> block yourself with your other tools, then end with your report." +
+        (line !== "" ? ` Your task begins: "${line}"` : ""));
+}
 export const DEFAULT_TASK_MAX_TURNS = 30;
 const THINKING = [
     "off",
@@ -143,7 +169,7 @@ export function createTaskTool(_options = {}) {
         promptGuidelines: [TASK_NOTIFICATION_RULE],
         async execute(input, ctx) {
             if (ctx.depth >= MAX_TASK_DEPTH || ctx.spawnSubagent === undefined) {
-                return fail("Sub-agents are not available here (nested tasks are not allowed).");
+                return fail(nestedTaskRejection(ctx, "task", "Sub-agents are not available here (nested tasks are not allowed)."));
             }
             const request = buildSubagentRequest(input, ctx);
             if (typeof request === "string")

package/docs/acp.md

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

package/docs/agents.md

@@ -158,12 +158,15 @@ worktree 里与父 cwd 对应的目录。结束时没有改动（工作区干净
   看得到父的计划、提醒与读过的文件内容，但 `read` 记录从空开始（编辑前照旧要先读）。
 - 类型声明了 `tools` / `disallowed-tools`（或参数给了 `tools`）时，工具表不变，不可用的工具在执行层拒绝
   （`Tool "X" is not available in this session.`），并在 `<task>` 里列出。只读类型照旧走只读管线。
+- `<task>` 同时列出按深度拒绝的 `task` / `task_ctl` 并要求不要调用它们（执行层仍是深度拒绝的文案）。实测仍有模型把父消息里
+  「调用 task」的指令当成自己的：调一次被拒，多一轮请求，有时随后只回报失败、不做子任务（见 [benchmarks](benchmarks/efficiency-2026-10.md)「F2」）。
 - `isolation: "worktree"` 时子会话的 cwd 是 worktree，`<task>` 里说明上文的相对路径指父目录；cwd 节变化以尾部补丁发送，
   不影响已缓存的前缀。
 
 以下情况回落为 fresh（日志记一条 info，结果 `details.context` 标 `fresh`）：调用参数或类型指定了与父不同的模型或思考级别；
-父会话还没有发出过请求；父上一次请求的输入超过（窗口 − `compaction.reserveTokens`）的一半。续聊（`taskId`）与 resume
-照原文件重开，不受影响。只在请求了 fork 时 `details.context` 才出现。
+父会话还没有发出过请求；父上一次请求的输入超过（窗口 − `compaction.reserveTokens`）× `subagents.forkMaxContextRatio`
+（缺省 0.5）。续聊（`taskId`）与 resume 照原文件重开，不受影响。只在请求了 fork 时 `details.context` 才出现；后台任务的
+`running` 结果也带它，任务排队或 worktree 隔离尚未就绪时该结果不带，`get_tasks` / 完成通知的 `TaskInfo.context` 仍有。
 
 何时用 fork：子任务需要你已经读过、讨论过的内容时。fork 的首个请求把父上下文整段带上，按命中价计费；fresh 只发系统提示、
 工具表与任务说明，但你得在 `prompt` 里写清全部背景，子 Agent 往往还要重新读文件。
@@ -175,7 +178,14 @@ worktree 里与父 cwd 对应的目录。结束时没有改动（工作区干净
 | OpenAI 系（经中转，不发路由键） | 两次分别 0% 与 85%，取决于中转把请求路由到哪个上游                                    | 视中转而定                   |
 | Anthropic（1/10，写入 1.25×）   | 未实测；前缀相同，命中应与父的下一回合相同                                            | 需要父上下文时               |
 
-`explore` 这类只需要定位文件的任务建议保持 fresh；内置类型都缺省 fresh。
+fork 的成本不止首请求：子会话**每一回合**都重读整段父前缀。按命中价折算，8k 父上下文 × 30 回合在 DeepSeek（1/50）上约
+4.8k 全价 token，在 Kimi / Anthropic（1/4–1/10）上约 24k–60k，中转落空时全价。所以 DeepSeek 上子任务只要重读 ≥ 1 份
+已读文件就划算；Kimi / Anthropic 上只在子任务**主要**依赖父上下文时用；经不发路由键的中转不建议。窗口很大的模型上可以调低
+`subagents.forkMaxContextRatio`，免得几十万 token 的父上下文被每回合重读。
+
+`explore` 这类只需要定位文件的任务建议保持 fresh；内置类型（包括 `general`）都缺省 fresh：`general` 的典型任务（按指令
+改某处代码）通常不需要父上下文、回合又多，而且长会话里 fork 会按上面的比例静默回落，缺省 fork 会让同一类型在不同时刻拿到
+不同的上下文。需要时在调用参数或类型定义里写 `context: fork`。
 
 ### 事件与统计
 
@@ -191,6 +201,7 @@ RPC `get_tasks` / `get_agents` 返回任务快照与可用类型（来源、定
 | `subagents.maxPending`            | 排队上限，缺省 16                                                                |
 | `subagents.retainSessions`        | 保留在内存里的已结束子会话数（LRU），缺省 4，0 = 结束即释放；只认用户级          |
 | `subagents.defaultModel`          | 子 Agent 缺省模型，不设继承父会话                                                |
+| `subagents.forkMaxContextRatio`   | fork 回落比例（见「fork 模式」），0.05–0.95，缺省 0.5；只认用户级                |
 | `subagents.background`            | `auto`（缺省）\| `always` \| `never`，见「前台与后台」；用户 / 项目 / 宿主级都认 |
 | `subagents.autoBackgroundAfterMs` | 前台任务运行超过该毫秒数自动转后台，缺省 0（关闭）；用户 / 项目级都认            |
 | `agents.dirs`                     | 追加的定义目录                                                                   |

package/docs/en/acp.md

@@ -47,9 +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 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), and its transcript, images and subagent handles can then be garbage-collected; the session object created at process start is held by the process until exit. 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/permissions.md

@@ -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`); 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.
+- **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. For relays and custom providers: when the session model inherits an official catalog entry by id and the provider's model table (config `models[]`, the discovery cache) lists a small model of the same vendor (one that also inherits that catalog's `small` entry by id, e.g. a packy `deepseek-v4-pro` session → `deepseek-v4-flash`), that model is used, otherwise the session model; entries synthesized outside the model table are never used. Setting `permission.autoModel` is still recommended. 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.