@armadra/agent 0.4.0 → 0.5.1

package/dist/tools/image-resize.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 可选的图片缩放（docs/wave5-plan.md §4、D12）。[W5-I]
+ *
+ * 零依赖不能解码像素，只能调系统工具：macOS 依次试 `sips`、`magick`、`convert`；Linux 试
+ * `magick`、`convert`；Windows 只试 `magick`（`convert.exe` 是系统的磁盘转换工具）。都没有就返回
+ * `no_tool`，调用方按原规则拒绝并提示。只在超限时调用（`images.resize: "auto"`，缺省）。
+ *
+ * 输出写临时目录，读回后删掉；JPEG 保持 JPEG，其余格式输出 PNG（GIF 取第一帧）。边长先取
+ * min(目标边长, 原长边)，体积仍超限就按 0.7 逐次缩小，最多 5 次。
+ */
+import { type ImageSize } from "./image-file.js";
+export interface CommandResult {
+    /** 进程退出码；命令不存在 / 无法启动为 null。 */
+    code: number | null;
+    stdout: Buffer;
+    stderr: string;
+    /** 命令不存在（ENOENT）。 */
+    missing?: boolean;
+}
+export type RunCommand = (command: string, args: readonly string[], options?: {
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+}) => Promise<CommandResult>;
+/** 缺省的命令执行器：execFile，stdout 按 Buffer 收，30 s 超时。 */
+export declare const runCommand: RunCommand;
+export interface ResizeTarget {
+    /** 长边上限（像素）。 */
+    maxEdge: number;
+    /** base64 后的体积上限（字节）。 */
+    maxBase64Bytes: number;
+    mimeType: string;
+    /** 原图尺寸（已知时用来定起始边长）。 */
+    size?: ImageSize | undefined;
+}
+export interface ResizeDeps {
+    platform?: NodeJS.Platform;
+    run?: RunCommand;
+    /** 临时目录的父目录；缺省 os.tmpdir()。 */
+    tmpDir?: string;
+}
+export interface ResizedImage {
+    ok: true;
+    buf: Buffer;
+    mimeType: string;
+    size?: ImageSize;
+    /** 用到的工具（`sips` / `magick` / `convert`）。 */
+    tool: string;
+}
+export interface ResizeFailure {
+    ok: false;
+    reason: "no_tool" | "failed";
+}
+/** 按平台的候选工具，靠前的先试。 */
+export declare function resizeTools(platform: NodeJS.Platform): string[];
+/**
+ * 把 `input` 缩到目标以内。`no_tool`：一个可用工具都没有；`failed`：工具能用但缩不到目标。
+ */
+export declare function resizeImage(input: string, target: ResizeTarget, deps?: ResizeDeps): Promise<ResizedImage | ResizeFailure>;

package/dist/tools/image-resize.js

@@ -0,0 +1,97 @@
+/**
+ * 可选的图片缩放（docs/wave5-plan.md §4、D12）。[W5-I]
+ *
+ * 零依赖不能解码像素，只能调系统工具：macOS 依次试 `sips`、`magick`、`convert`；Linux 试
+ * `magick`、`convert`；Windows 只试 `magick`（`convert.exe` 是系统的磁盘转换工具）。都没有就返回
+ * `no_tool`，调用方按原规则拒绝并提示。只在超限时调用（`images.resize: "auto"`，缺省）。
+ *
+ * 输出写临时目录，读回后删掉；JPEG 保持 JPEG，其余格式输出 PNG（GIF 取第一帧）。边长先取
+ * min(目标边长, 原长边)，体积仍超限就按 0.7 逐次缩小，最多 5 次。
+ */
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { base64Size } from "../ai/image-limits.js";
+import { imageSize } from "./image-file.js";
+/** 缺省的命令执行器：execFile，stdout 按 Buffer 收，30 s 超时。 */
+export const runCommand = (command, args, options = {}) => new Promise((resolvePromise) => {
+    execFile(command, [...args], {
+        encoding: "buffer",
+        maxBuffer: 128 * 1024 * 1024,
+        timeout: options.timeoutMs ?? 30_000,
+        windowsHide: true,
+        ...(options.env !== undefined ? { env: options.env } : {}),
+    }, (error, stdout, stderr) => {
+        const err = error;
+        const missing = err !== null && err.code === "ENOENT";
+        const code = err === null ? 0 : typeof err.code === "number" ? err.code : missing ? null : 1;
+        resolvePromise({
+            code,
+            stdout: Buffer.isBuffer(stdout) ? stdout : Buffer.alloc(0),
+            stderr: Buffer.isBuffer(stderr) ? stderr.toString("utf8") : String(stderr ?? ""),
+            ...(missing ? { missing: true } : {}),
+        });
+    });
+});
+const MAX_ATTEMPTS = 5;
+const SHRINK = 0.7;
+const MIN_EDGE = 64;
+/** 按平台的候选工具，靠前的先试。 */
+export function resizeTools(platform) {
+    if (platform === "darwin")
+        return ["sips", "magick", "convert"];
+    if (platform === "win32")
+        return ["magick"];
+    return ["magick", "convert"];
+}
+function resizeArgs(tool, input, output, edge, format) {
+    if (tool === "sips")
+        return ["-Z", String(edge), "-s", "format", format, input, "--out", output];
+    // ImageMagick：`[0]` 取第一帧，`>` 只缩小不放大
+    return [`${input}[0]`, "-resize", `${edge}x${edge}>`, output];
+}
+/**
+ * 把 `input` 缩到目标以内。`no_tool`：一个可用工具都没有；`failed`：工具能用但缩不到目标。
+ */
+export async function resizeImage(input, target, deps = {}) {
+    const run = deps.run ?? runCommand;
+    const format = target.mimeType === "image/jpeg" ? "jpeg" : "png";
+    const mimeType = format === "jpeg" ? "image/jpeg" : "image/png";
+    const long = target.size !== undefined ? Math.max(target.size.width, target.size.height) : 0;
+    const start = long > 0 ? Math.min(target.maxEdge, long) : target.maxEdge;
+    const dir = await mkdtemp(join(deps.tmpDir ?? tmpdir(), "ama-resize-"));
+    try {
+        for (const tool of resizeTools(deps.platform ?? process.platform)) {
+            let edge = start;
+            let worked = false;
+            for (let attempt = 0; attempt < MAX_ATTEMPTS && edge >= MIN_EDGE; attempt++) {
+                const output = join(dir, `out-${attempt}.${format === "jpeg" ? "jpg" : "png"}`);
+                const result = await run(tool, resizeArgs(tool, input, output, edge, format));
+                if (result.missing === true || result.code !== 0)
+                    break;
+                let buf;
+                try {
+                    buf = await readFile(output);
+                }
+                catch {
+                    break;
+                }
+                worked = true;
+                const size = imageSize(buf, mimeType);
+                const longOut = size !== undefined ? Math.max(size.width, size.height) : 0;
+                if (base64Size(buf.length) <= target.maxBase64Bytes && longOut <= target.maxEdge) {
+                    return { ok: true, buf, mimeType, tool, ...(size !== undefined ? { size } : {}) };
+                }
+                edge = Math.round(Math.min(edge, longOut > 0 ? longOut : edge) * SHRINK);
+            }
+            // 工具能用但缩不到目标：换工具也不会更好
+            if (worked)
+                return { ok: false, reason: "failed" };
+        }
+        return { ok: false, reason: "no_tool" };
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}

package/dist/tools/presets.d.ts

@@ -12,6 +12,11 @@
  *   `--tools a,b,c` 整组替换（之后只用列出的名字）。
  * - `tools.default`：`+name` / `-name` 在预设上增减；不带前缀的名字整组替换预设的内置工具，
  *   之后再应用带前缀的项。未注册的名字记 warning 并忽略。
+ * - （D20）`todo` 不在 `default` 里：W5-C0 曾把它加进来，以 `bench-presets` 复测为门（费用增幅 ≤ 5% 且
+ *   成功率不降）；W5-Z 用多步长任务复测（docs/benchmarks/presets-todo-2026-10-03.md）成功数下降 1、估价
+ *   +4.6%、保守计价 +11.3%，按门撤回。计划批准后的进度改用 `[DONE:n]` 文本标记（plan/done-markers.ts）；
+ *   要 todo 就 `tools.default: ["+todo"]`。
+ * - （W5-C0）`task_ctl` 与 `task` 同进退：`+task` 一起暴露、`-task` 一起去掉（`pairCompanions`）。
  * - `codemode` 是 `codemode-only` 的旧名（0.3.0），配置合并与命令行解析时折成规范名。
  * - codemode 开关跟随预设（`presetCodemodeMode`）：`default` → `on`（只在沙箱 strict，即 Node ≥ 25 隔离
  *   网络时；Node 22 / 24 → `off`），`codemode-only` → `only`，`minimal` / `coordinator` → `off`。
@@ -43,9 +48,9 @@ export interface CodemodeModeResolution {
     strict: boolean;
 }
 /** 生效的 codemode 模式及其来源；`strict` 缺省按运行时探测（测试与组装根可注入）。 */
-export declare function resolveCodemodeMode(config: Pick<AmaConfig, "tools" | "codemode">, strict?: boolean): CodemodeModeResolution;
+export declare function resolveCodemodeMode(config: Pick<AmaConfig, "tools" | "codemode" | "sandbox">, strict?: boolean): CodemodeModeResolution;
 /** 生效的 codemode 模式：显式配置优先，否则跟随预设。 */
-export declare function effectiveCodemodeMode(config: Pick<AmaConfig, "tools" | "codemode">, strict?: boolean): CodemodeMode;
+export declare function effectiveCodemodeMode(config: Pick<AmaConfig, "tools" | "codemode" | "sandbox">, strict?: boolean): CodemodeMode;
 /**
  * codemode 脚本里可调用工具的范围：`coordinator` 预设只能调活动集里的工具（`"active"`），其它预设
  * 不限（`undefined`；`on` 模式下脚本还能调没直接暴露的 ls / task / todo 等）。

package/dist/tools/presets.js

@@ -12,6 +12,11 @@
  *   `--tools a,b,c` 整组替换（之后只用列出的名字）。
  * - `tools.default`：`+name` / `-name` 在预设上增减；不带前缀的名字整组替换预设的内置工具，
  *   之后再应用带前缀的项。未注册的名字记 warning 并忽略。
+ * - （D20）`todo` 不在 `default` 里：W5-C0 曾把它加进来，以 `bench-presets` 复测为门（费用增幅 ≤ 5% 且
+ *   成功率不降）；W5-Z 用多步长任务复测（docs/benchmarks/presets-todo-2026-10-03.md）成功数下降 1、估价
+ *   +4.6%、保守计价 +11.3%，按门撤回。计划批准后的进度改用 `[DONE:n]` 文本标记（plan/done-markers.ts）；
+ *   要 todo 就 `tools.default: ["+todo"]`。
+ * - （W5-C0）`task_ctl` 与 `task` 同进退：`+task` 一起暴露、`-task` 一起去掉（`pairCompanions`）。
  * - `codemode` 是 `codemode-only` 的旧名（0.3.0），配置合并与命令行解析时折成规范名。
  * - codemode 开关跟随预设（`presetCodemodeMode`）：`default` → `on`（只在沙箱 strict，即 Node ≥ 25 隔离
  *   网络时；Node 22 / 24 → `off`），`codemode-only` → `only`，`minimal` / `coordinator` → `off`。
@@ -23,12 +28,13 @@
  *   warning**（不报错：零配置用户不应因此起不来），显式 `on` 同样忽略；跟随预设得到的 `on` 静默回退。
  * - `only` 模式活动集独占：宿主 / SDK 工具也不直接暴露，只能在脚本里调用（`exclusive`）。
  */
-import { detectSandboxCapability } from "../codemode/capability.js";
+import { sandboxCapabilityFor } from "../codemode/capability.js";
 import { canonicalPreset, } from "../config/types.js";
-import { ToolRegistry } from "./registry.js";
+import { ToolRegistry, pairCompanions } from "./registry.js";
 export const CODEMODE_TOOL = "codemode";
 /** 各预设下模型直接看到的内置工具（codemode-only 预设见 `resolvePreset`）。 */
 export const PRESET_TOOLS = Object.freeze({
+    // D20：todo 不在 default（W5-Z 复测未过门，见文件头）
     default: ["bash", "edit", "glob", "grep", "read", "write"],
     minimal: ["bash", "edit", "read", "write"],
     "codemode-only": [CODEMODE_TOOL],
@@ -50,7 +56,7 @@ export function presetCodemodeMode(preset, strict) {
     }
 }
 /** 生效的 codemode 模式及其来源；`strict` 缺省按运行时探测（测试与组装根可注入）。 */
-export function resolveCodemodeMode(config, strict = detectSandboxCapability().strict) {
+export function resolveCodemodeMode(config, strict = sandboxCapabilityFor(config).strict) {
     const preset = canonicalPreset(config.tools?.preset) ?? "default";
     const explicit = config.codemode?.mode;
     if (explicit !== undefined)
@@ -113,7 +119,8 @@ export function resolvePreset(input) {
             base.push(CODEMODE_TOOL);
     }
     const names = [];
-    for (const name of applyToolAdjustments(base, input.config.tools?.default)) {
+    const adjusted = applyToolAdjustments(base, input.config.tools?.default);
+    for (const name of pairCompanions(adjusted, input.available)) {
         if (input.available(name))
             names.push(name);
         else

package/dist/tools/read.d.ts

@@ -3,10 +3,11 @@
  *
  * 文本按 `cat -n` 形状返回（行号右对齐 6 位 + Tab）；头截断 2000 行 / 50 KB 先到者，末尾提示
  * `offset` 续读；NUL 嗅探判二进制并拒绝；png / jpg / gif / webp 作为 ImageBlock 返回（MIME 按文件头，
- * 与 `--image` / `@图片` 共用 image-file.ts；模型不支持图片或超过 5 MB 时只给路径与尺寸）；成功后
- * `ctx.markRead(abs)`。
+ * 与 `--image` / `@图片` 共用 image-file.ts；模型不支持图片、超过当前端点的单图上限（base64 后，
+ * [W5-I] 按端点分档）或任一边 > 8000 px 时只给路径与尺寸）；成功后 `ctx.markRead(abs)`。
  */
 import type { ToolContext, ToolDefinition, ToolResult } from "./types.js";
+import { type ImageFitOptions } from "./image-file.js";
 export { imageSize, type ImageSize } from "./image-file.js";
 export interface ReadInput {
     path: string;
@@ -16,6 +17,8 @@ export interface ReadInput {
 export interface ReadToolOptions {
     /** 当前模型是否接受图片输入；缺省 true。 */
     supportsImages?(ctx: ToolContext): boolean;
+    /** [W5-I] 当前模型的单图上限与缩放设置；缺省 5 MB（base64 后）。 */
+    imageOptions?(ctx: ToolContext): ImageFitOptions;
 }
 export declare function isBinary(buf: Buffer): boolean;
 /** `cat -n` 形状。 */

package/dist/tools/read.js

@@ -3,14 +3,14 @@
  *
  * 文本按 `cat -n` 形状返回（行号右对齐 6 位 + Tab）；头截断 2000 行 / 50 KB 先到者，末尾提示
  * `offset` 续读；NUL 嗅探判二进制并拒绝；png / jpg / gif / webp 作为 ImageBlock 返回（MIME 按文件头，
- * 与 `--image` / `@图片` 共用 image-file.ts；模型不支持图片或超过 5 MB 时只给路径与尺寸）；成功后
- * `ctx.markRead(abs)`。
+ * 与 `--image` / `@图片` 共用 image-file.ts；模型不支持图片、超过当前端点的单图上限（base64 后，
+ * [W5-I] 按端点分档）或任一边 > 8000 px 时只给路径与尺寸）；成功后 `ctx.markRead(abs)`。
  */
 import { readFile, stat } from "node:fs/promises";
 import { displayPath, resolvePath } from "./paths.js";
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateHead } from "./truncate.js";
 import { normalizeToLF, splitBom } from "./edit-fuzzy.js";
-import { MAX_IMAGE_BYTES, imageMimeFromPath, imageSize, sniffImageMime } from "./image-file.js";
+import { MAX_IMAGE_FILE_BYTES, fitImage, imageMimeFromPath, imageSize, sniffImageMime, } from "./image-file.js";
 export { imageSize } from "./image-file.js";
 const SNIFF_BYTES = 8000;
 export function isBinary(buf) {
@@ -38,15 +38,18 @@ async function readImage(abs, shown, ctx, options) {
     if (options.supportsImages && !options.supportsImages(ctx)) {
         return { content: `${caption}\n[The current model does not accept image input.]`, details };
     }
-    if (buf.length > MAX_IMAGE_BYTES) {
-        return {
-            content: `${caption}\n[Image exceeds the ${formatSize(MAX_IMAGE_BYTES)} attachment limit; not attached.]`,
-            details,
-        };
+    if (buf.length > MAX_IMAGE_FILE_BYTES) {
+        return { content: `${caption}\n[Image file is too large to attach.]`, details };
     }
+    const fit = await fitImage(buf, mimeType, options.imageOptions?.(ctx) ?? {}, abs);
+    if (!fit.ok)
+        return { content: `${caption}\n[${fit.note}]`, details };
+    const note = fit.resized !== undefined && fit.size !== undefined
+        ? `\n[Resized to ${fit.size.width}x${fit.size.height} to fit the attachment limit.]`
+        : "";
     const blocks = [
-        { type: "text", text: caption },
-        { type: "image", data: buf.toString("base64"), mimeType },
+        { type: "text", text: caption + note },
+        { type: "image", data: fit.buf.toString("base64"), mimeType: fit.mimeType },
     ];
     return { content: blocks, details };
 }

package/dist/tools/registry.d.ts

@@ -6,6 +6,8 @@
  * - `disable(name)` 后不再出现在 `list()` / `active()`，也不能被 `setActive` 选中；未注册的名字也
  *   记下（宿主可能先 disable 再由内置注册，例如 `disable("task")`）；
  * - 活动集缺省 = 全部已注册且未禁用；`setActive(names)` 之后只用这些（未知名 → tool_not_found）；
+ * - （W5-C0）伴随工具 `TOOL_COMPANIONS`：`task_ctl` 与 `task` 同进退——`disable("task")` 一并禁用，
+ *   `setActive` 选了 `task` 时一并选上（预设里的配对在 presets.ts）；
  * - `builtinTools()` 给出全部内置工具；Skill 正文由模型用 read 读取（设计 §5.6 删除了 skill 工具），
  *   `/skill:` 命令展开在 skills/expand.ts。
  */
@@ -13,6 +15,10 @@ import type { ToolDefinition, ToolExecutionMode, ToolRegistryApi, ToolSource } f
 import { type ReadToolOptions } from "./read.js";
 import { type BashToolOptions } from "./bash.js";
 import { type TaskToolOptions } from "./task.js";
+/** [W5-C0] 主工具 → 随它出现 / 消失的伴随工具。 */
+export declare const TOOL_COMPANIONS: Readonly<Record<string, readonly string[]>>;
+/** 按 `TOOL_COMPANIONS` 配对：有主工具就带上（已注册的）伴随工具，没有就去掉。 */
+export declare function pairCompanions(names: Iterable<string>, available: (name: string) => boolean): string[];
 export declare const TOOL_NAME_RE: RegExp;
 /** 未声明时：read → parallel；write / execute → sequential。 */
 export declare function executionModeOf(tool: Pick<ToolDefinition, "permission" | "executionMode">): ToolExecutionMode;
@@ -35,7 +41,7 @@ export interface BuiltinToolOptions {
     bash?: BashToolOptions;
     task?: TaskToolOptions;
 }
-/** 全部内置工具（read / write / edit / bash / grep / glob / ls / todo / task）。 */
+/** 全部内置工具（read / write / edit / bash / grep / glob / ls / todo / task / task_ctl）。 */
 export declare function builtinTools(options?: BuiltinToolOptions): ToolDefinition[];
 /** 新建注册表并登记全部内置工具；`disabled` 来自 config.tools.disabled。 */
 export declare function createToolRegistry(options?: BuiltinToolOptions & {

package/dist/tools/registry.js

@@ -6,6 +6,8 @@
  * - `disable(name)` 后不再出现在 `list()` / `active()`，也不能被 `setActive` 选中；未注册的名字也
  *   记下（宿主可能先 disable 再由内置注册，例如 `disable("task")`）；
  * - 活动集缺省 = 全部已注册且未禁用；`setActive(names)` 之后只用这些（未知名 → tool_not_found）；
+ * - （W5-C0）伴随工具 `TOOL_COMPANIONS`：`task_ctl` 与 `task` 同进退——`disable("task")` 一并禁用，
+ *   `setActive` 选了 `task` 时一并选上（预设里的配对在 presets.ts）；
  * - `builtinTools()` 给出全部内置工具；Skill 正文由模型用 read 读取（设计 §5.6 删除了 skill 工具），
  *   `/skill:` 命令展开在 skills/expand.ts。
  */
@@ -20,6 +22,24 @@ import { createGlobTool } from "./glob.js";
 import { createLsTool } from "./ls.js";
 import { createTodoTool } from "./todo.js";
 import { createTaskTool } from "./task.js";
+import { TASK_CTL_TOOL, createTaskCtlTool } from "./task-ctl.js";
+/** [W5-C0] 主工具 → 随它出现 / 消失的伴随工具。 */
+export const TOOL_COMPANIONS = Object.freeze({
+    task: [TASK_CTL_TOOL],
+});
+/** 按 `TOOL_COMPANIONS` 配对：有主工具就带上（已注册的）伴随工具，没有就去掉。 */
+export function pairCompanions(names, available) {
+    const set = new Set(names);
+    for (const [main, companions] of Object.entries(TOOL_COMPANIONS)) {
+        for (const companion of companions) {
+            if (set.has(main) && available(companion))
+                set.add(companion);
+            else
+                set.delete(companion);
+        }
+    }
+    return [...set];
+}
 export const TOOL_NAME_RE = /^[a-z][a-z0-9_]{1,63}$/;
 /** 未声明时：read → parallel；write / execute → sequential。 */
 export function executionModeOf(tool) {
@@ -52,8 +72,10 @@ export class ToolRegistry {
         this.entries.set(tool.name, { tool, source });
     }
     disable(name) {
-        this.disabled.add(name);
-        this.activeNames?.delete(name);
+        for (const target of [name, ...(TOOL_COMPANIONS[name] ?? [])]) {
+            this.disabled.add(target);
+            this.activeNames?.delete(target);
+        }
     }
     isDisabled(name) {
         return this.disabled.has(name);
@@ -77,10 +99,10 @@ export class ToolRegistry {
                 throw new AmaError("tool_not_found", `Unknown or disabled tool "${name}"`);
             }
         }
-        this.activeNames = new Set(names);
+        this.activeNames = new Set(pairCompanions(names, (n) => this.entries.has(n) && !this.disabled.has(n)));
     }
 }
-/** 全部内置工具（read / write / edit / bash / grep / glob / ls / todo / task）。 */
+/** 全部内置工具（read / write / edit / bash / grep / glob / ls / todo / task / task_ctl）。 */
 export function builtinTools(options = {}) {
     const tools = [
         createReadTool(options.read),
@@ -92,6 +114,7 @@ export function builtinTools(options = {}) {
         createLsTool(),
         createTodoTool(),
         createTaskTool(options.task),
+        createTaskCtlTool(),
     ];
     return tools;
 }

package/dist/tools/task-ctl.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `task_ctl` 工具：查看 / 等待 / 停止后台子 Agent 任务，读输出，向任务追加消息
+ * （docs/wave5-plan.md §7.3，D13）。[W5-C0 桩 → W5-G]
+ *
+ * - 与 `task` 同进退（预设、`--tools`、`disable("task")`，见 registry.ts 的 `TOOL_COMPANIONS`）；
+ * - 控制面按会话 id 取（agents/task-control.ts，注册表登记）；子会话里（depth ≥ 1）不可用——工具表
+ *   与父一致，运行时拒绝；
+ * - `wait` / `output` 是轮询类调用（`annotations.pollable`，重复调用检测豁免）；
+ * - `send` = 续聊放后台：等价于 `task{taskId, prompt, background:true}`，完成后同样收到通知。
+ */
+import type { ToolDefinition } from "./types.js";
+export declare const TASK_CTL_TOOL = "task_ctl";
+export declare const DEFAULT_WAIT_MS = 30000;
+export declare const MAX_WAIT_MS = 600000;
+export interface TaskCtlInput {
+    action: "list" | "wait" | "stop" | "output" | "send";
+    taskId?: string;
+    timeoutMs?: number;
+    /** send：追加给任务的消息。 */
+    prompt?: string;
+}
+export declare function createTaskCtlTool(): ToolDefinition<TaskCtlInput>;

package/dist/tools/task-ctl.js

@@ -0,0 +1,116 @@
+/**
+ * `task_ctl` 工具：查看 / 等待 / 停止后台子 Agent 任务，读输出，向任务追加消息
+ * （docs/wave5-plan.md §7.3，D13）。[W5-C0 桩 → W5-G]
+ *
+ * - 与 `task` 同进退（预设、`--tools`、`disable("task")`，见 registry.ts 的 `TOOL_COMPANIONS`）；
+ * - 控制面按会话 id 取（agents/task-control.ts，注册表登记）；子会话里（depth ≥ 1）不可用——工具表
+ *   与父一致，运行时拒绝；
+ * - `wait` / `output` 是轮询类调用（`annotations.pollable`，重复调用检测豁免）；
+ * - `send` = 续聊放后台：等价于 `task{taskId, prompt, background:true}`，完成后同样收到通知。
+ */
+import { capTaskText, formatTokens } from "../agents/result.js";
+import { taskControl } from "../agents/task-control.js";
+export const TASK_CTL_TOOL = "task_ctl";
+export const DEFAULT_WAIT_MS = 30_000;
+export const MAX_WAIT_MS = 600_000;
+function fail(message) {
+    return { content: message, isError: true };
+}
+function line(task, now) {
+    const parts = [task.taskId, task.agent, task.status];
+    if (task.turns !== undefined)
+        parts.push(`${task.turns} turns`);
+    if (task.usage !== undefined)
+        parts.push(`${formatTokens(task.usage.totalTokens)} tokens`);
+    parts.push(`${Math.round(((task.endedAt ?? now) - task.startedAt) / 1000)}s`);
+    if (task.background)
+        parts.push("background");
+    const text = parts.join(" · ");
+    return task.description === "" ? text : `${text} — ${task.description}`;
+}
+async function send(input, ctx) {
+    if (input.prompt === undefined || input.prompt.trim() === "")
+        return fail("send needs a non-empty prompt");
+    if (ctx.spawnSubagent === undefined)
+        return fail("Sub-agents are not available here.");
+    const result = await ctx.spawnSubagent({
+        prompt: input.prompt,
+        taskId: input.taskId,
+        background: true,
+        parentToolCallId: ctx.toolCallId,
+        signal: ctx.signal,
+    });
+    return { content: result.text, isError: result.isError };
+}
+export function createTaskCtlTool() {
+    return {
+        name: TASK_CTL_TOOL,
+        label: "TaskCtl",
+        description: "Manage sub-agent tasks started by task: list them, wait for one, stop it, read its " +
+            "output, or send it a follow-up message (runs in background).",
+        parameters: {
+            type: "object",
+            properties: {
+                action: { type: "string", enum: ["list", "wait", "stop", "output", "send"] },
+                taskId: { type: "string", description: "Required except for list" },
+                timeoutMs: { type: "number", description: `wait only (default ${DEFAULT_WAIT_MS})` },
+                prompt: { type: "string", description: "send only" },
+            },
+            required: ["action"],
+            additionalProperties: false,
+        },
+        permission: "read",
+        executionMode: "parallel",
+        annotations: { pollable: true },
+        async execute(input, ctx) {
+            if (ctx.depth >= 1)
+                return fail("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() ?? [];
+                if (tasks.length === 0)
+                    return { content: "No sub-agent tasks." };
+                const now = Date.now();
+                return { content: tasks.map((task) => line(task, now)).join("\n") };
+            }
+            const taskId = input.taskId;
+            if (taskId === undefined || taskId === "")
+                return fail(`${input.action} needs taskId`);
+            const info = control?.get(taskId);
+            if (control === undefined || info === undefined)
+                return fail(`Unknown task ${taskId}.`);
+            switch (input.action) {
+                case "send":
+                    return send(input, ctx);
+                case "output": {
+                    const text = control.output(taskId) ?? "";
+                    const head = info.status === "running" ? `Task ${taskId} is running; output so far:` : "";
+                    const body = capTaskText(text, info.outputFile).text || "(no output yet)";
+                    return { content: head === "" ? body : `${head}\n${body}` };
+                }
+                case "stop": {
+                    const result = await control.stop(taskId);
+                    return {
+                        content: `Task ${taskId} ${result?.status ?? control.get(taskId)?.status ?? "stopped"}.`,
+                    };
+                }
+                case "wait": {
+                    const timeout = Math.min(Math.max(input.timeoutMs ?? DEFAULT_WAIT_MS, 0), MAX_WAIT_MS);
+                    const result = await control.wait(taskId, timeout);
+                    if (result === undefined) {
+                        const turns = control.get(taskId)?.turns ?? 0;
+                        return {
+                            content: `Task ${taskId} is still running (${turns} turns so far). Wait again or stop it.`,
+                        };
+                    }
+                    return {
+                        content: `[task ${taskId} ${result.status ?? "completed"}]\n${result.text}`,
+                        isError: result.isError,
+                    };
+                }
+                default:
+                    return fail(`unknown action ${String(input.action)}`);
+            }
+        },
+    };
+}

package/dist/tools/task.d.ts

@@ -1,29 +1,41 @@
 /**
- * `task` 工具：同进程子 Agent（设计 §5.2、D14）。[B3]
+ * `task` 工具：子 Agent 的统一入口（设计 §5.2、D14；第五波 docs/wave5-plan.md §7.3，D13、D23）。
+ * [B3 → W5-G]
  *
- * 子会话由 `ctx.spawnSubagent`（B2 的 AgentSession 提供）创建：独立 JSONL、继承权限模式与 broker、
- * 审批串到父。本工具负责：
- * - 深度 ≤ 1：`ctx.depth ≥ 1` 或无 `spawnSubagent` → 错误（子 Agent 里没有 task）；
- * - 并发 ≤ 4：由会话的 `SubagentPool`（agent/session-subagent.ts，`subagents.maxConcurrent`）排队，
- *   本工具不再自带一层信号量；排队中父 abort → 子会话抛 aborted，这里返回 aborted；
- * - 工具子集：`tools` 里去掉 `task`（缺省交给 spawnSubagent = 父活动集去掉 task）；
- * - 父 abort 级联：把 `ctx.signal` 传给子；
- * - 结果 = 子的最后助手文本 + `details{ sessionFile, usage, stopReason }`。
+ * - `agent`：子 Agent 类型（内置 general / explore / plan、`.ama/agents/*.md`）或外部 Agent；缺省
+ *   general。描述里列出可用类型（catalog 由 compose-agents.ts 经 `bindTaskAgents` 绑定；没绑定时
+ *   只列内置类型）。
+ * - `background`：立即返回 taskId，完成后父会话收到 `<task-notification>`；`taskId`：向已有子会话
+ *   追加消息（续聊，忽略 agent / tools / model）；`isolation: "worktree"`：在独立 git worktree 里跑。
+ * - **parallel**：同一回复里的多个 task 真并行（会话注册表的池限流，缺省 4）；与 sequential 工具
+ *   （edit 等）同批时仍按 tool-runner 的规则整批串行。
+ * - 深度 ≤ 1：子会话的工具表里保留 task（与父字节一致，缓存前缀可复用），运行时在这里拒绝。
+ * - 结果 = 子 Agent 的最终报告（> 50 KB 截头尾、全文落 outputs/，见 agents/result.ts）+ details。
  */
 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;
 export declare const DEFAULT_TASK_MAX_TURNS = 30;
 export interface TaskInput {
     prompt: string;
+    agent?: string;
     description?: string;
+    background?: boolean;
+    taskId?: string;
+    isolation?: "none" | "worktree";
+    budgetUsd?: number;
     tools?: string[];
     model?: string;
     thinkingLevel?: ModelThinkingLevel;
     maxTurns?: number;
 }
-/** 预留（并发上限在会话的 SubagentPool，见文件头）。 */
+/** 预留（并发上限在会话的任务注册表，见 agent/subagent-registry.ts）。 */
 export interface TaskToolOptions {
 }
+/** 描述里类型清单的标题（清单本身另有 400 token 预算，见 agents/catalog.ts）。 */
+export declare const TASK_AGENTS_HEADING = "\nAgents:\n";
+/** 组装根把会话的类型目录绑到 task 工具上（描述里的类型清单）。 */
+export declare function bindTaskAgents(tool: ToolDefinition | undefined, catalog: AgentCatalog): void;
 export declare function buildSubagentRequest(input: TaskInput, ctx: ToolContext): SubagentRequest | string;
 export declare function createTaskTool(_options?: TaskToolOptions): ToolDefinition<TaskInput>;