@armadra/agent 0.3.0 → 0.5.0

package/dist/tools/presets.js

@@ -5,34 +5,74 @@
  * | ------------- | ----------------------------------------- |
  * | `default`     | read、edit、write、bash、grep、glob       |
  * | `minimal`     | read、edit、write、bash                   |
- * | `codemode`    | 只有 codemode（其余工具在脚本里调用）     |
+ * | `codemode-only` | 只有 codemode（其余工具在脚本里调用）   |
  * | `coordinator` | read + 宿主注册的工具                     |
  *
  * - 预设只管**内置**工具；宿主 / SDK 注册的工具（`canvas_*` 等）总在活动集里，除非用户
  *   `--tools a,b,c` 整组替换（之后只用列出的名字）。
  * - `tools.default`：`+name` / `-name` 在预设上增减；不带前缀的名字整组替换预设的内置工具，
  *   之后再应用带前缀的项。未注册的名字记 warning 并忽略。
- * - codemode 开关跟随预设：`codemode` 预设 → `only`，其余 → `off`；`codemode.mode` 显式配置覆盖。
- * - codemode 工具由 B10 经组装根的 `toolFactories` 注册（`codemode.mode` 为 off 时不注册）；不可用
- *   （例如 `codemode.requireStrict` 而运行时 Node 不隔离网络）时 codemode 预设**回退到 default 并
- *   warning**（不报错：零配置用户不应因此起不来），`on` 同样忽略。
+ * - （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`。
+ *   `codemode.mode` 显式配置覆盖（缺省配置不写这个键，以后调整映射能惠及老用户）。
+ * - `coordinator` 预设即使显式 `on`，脚本里能调用的工具也只限活动集（read + 宿主工具），见
+ *   `codemodeCallableFilter`：协调者「不写文件、不跑 bash」的约定不能经 codemode 绕过。
+ * - codemode 工具由 B10 经组装根的 `toolFactories` 注册（生效模式为 off 时不注册）；不可用
+ *   （例如 `codemode.requireStrict` 而运行时 Node 不隔离网络）时 codemode-only 预设**回退到 default 并
+ *   warning**（不报错：零配置用户不应因此起不来），显式 `on` 同样忽略；跟随预设得到的 `on` 静默回退。
  * - `only` 模式活动集独占：宿主 / SDK 工具也不直接暴露，只能在脚本里调用（`exclusive`）。
  */
-import { ToolRegistry } from "./registry.js";
+import { sandboxCapabilityFor } from "../codemode/capability.js";
+import { canonicalPreset, } from "../config/types.js";
+import { ToolRegistry, pairCompanions } from "./registry.js";
 export const CODEMODE_TOOL = "codemode";
-/** 各预设下模型直接看到的内置工具（codemode 预设见 `resolvePreset`）。 */
+/** 各预设下模型直接看到的内置工具（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: [CODEMODE_TOOL],
+    "codemode-only": [CODEMODE_TOOL],
     coordinator: ["read"],
 });
-/** 生效的 codemode 模式：显式配置优先，否则跟随预设。 */
-export function effectiveCodemodeMode(config) {
+/**
+ * 预设对应的 codemode 模式（没有显式 `codemode.mode` 时）。`default` 只在沙箱 strict（Node ≥ 25，
+ * 权限模型同时隔离网络）时开 `on`：Node 22 / 24 下 codemode 属 execute 类，每次都要审批，`-p` 下
+ * 直接被拒，所以缺省关闭（启动时提示一次，见 cli/codemode-notice.ts）。
+ */
+export function presetCodemodeMode(preset, strict) {
+    switch (preset) {
+        case "codemode-only":
+            return "only";
+        case "default":
+            return strict ? "on" : "off";
+        default:
+            return "off";
+    }
+}
+/** 生效的 codemode 模式及其来源；`strict` 缺省按运行时探测（测试与组装根可注入）。 */
+export function resolveCodemodeMode(config, strict = sandboxCapabilityFor(config).strict) {
+    const preset = canonicalPreset(config.tools?.preset) ?? "default";
     const explicit = config.codemode?.mode;
     if (explicit !== undefined)
-        return explicit;
-    return config.tools?.preset === "codemode" ? "only" : "off";
+        return { mode: explicit, source: "config", preset, strict };
+    return { mode: presetCodemodeMode(preset, strict), source: "preset", preset, strict };
+}
+/** 生效的 codemode 模式：显式配置优先，否则跟随预设。 */
+export function effectiveCodemodeMode(config, strict) {
+    return resolveCodemodeMode(config, strict).mode;
+}
+/**
+ * codemode 脚本里可调用工具的范围：`coordinator` 预设只能调活动集里的工具（`"active"`），其它预设
+ * 不限（`undefined`；`on` 模式下脚本还能调没直接暴露的 ls / task / todo 等）。
+ */
+export function codemodeCallableFilter(config) {
+    return canonicalPreset(config.tools?.preset) === "coordinator" ? "active" : undefined;
 }
 /**
  * `tools.default` 微调：不带前缀的名字整组替换 `base`，再依次应用 `+name` / `-name`。
@@ -55,13 +95,18 @@ export function applyToolAdjustments(base, adjustments) {
 }
 export function resolvePreset(input) {
     const warnings = [];
-    let preset = input.config.tools?.preset ?? "default";
-    let codemode = effectiveCodemodeMode(input.config);
+    const resolved = resolveCodemodeMode(input.config, input.strict);
+    let preset = resolved.preset;
+    let codemode = resolved.mode;
+    // 跟随预设得到的 on（default 预设）在 codemode 不可用时静默回退：零配置不该因此出 warning。
+    if (codemode === "on" && resolved.source === "preset" && !input.available(CODEMODE_TOOL)) {
+        codemode = "off";
+    }
     if (codemode !== "off" && !input.available(CODEMODE_TOOL)) {
-        warnings.push(preset === "codemode"
-            ? "工具预设 codemode 需要 codemode 工具（不可用），已回退到 default"
+        warnings.push(preset === "codemode-only"
+            ? "工具预设 codemode-only 需要 codemode 工具（不可用），已回退到 default"
             : `codemode.mode ${codemode} 需要 codemode 工具（不可用），已忽略`);
-        if (preset === "codemode")
+        if (preset === "codemode-only")
             preset = "default";
         codemode = "off";
     }
@@ -69,12 +114,13 @@ export function resolvePreset(input) {
     if (codemode === "only")
         base = [CODEMODE_TOOL];
     else {
-        base = [...PRESET_TOOLS[preset === "codemode" ? "default" : preset]];
+        base = [...PRESET_TOOLS[preset === "codemode-only" ? "default" : preset]];
         if (codemode === "on")
             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>;