@armadra/agent 0.4.0 → 0.5.1

package/dist/tools/task.js

@@ -1,15 +1,19 @@
 /**
- * `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 { AgentCatalog } from "../agents/catalog.js";
+import { TASK_NOTIFICATION_RULE } from "../agents/result.js";
 export const MAX_TASK_DEPTH = 1;
 export const DEFAULT_TASK_MAX_TURNS = 30;
 const THINKING = [
@@ -20,6 +24,17 @@ const THINKING = [
     "high",
     "xhigh",
 ];
+const BASE_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.";
+/** 描述里类型清单的标题（清单本身另有 400 token 预算，见 agents/catalog.ts）。 */
+export const TASK_AGENTS_HEADING = "\nAgents:\n";
+const catalogs = new WeakMap();
+/** 组装根把会话的类型目录绑到 task 工具上（描述里的类型清单）。 */
+export function bindTaskAgents(tool, catalog) {
+    if (tool !== undefined)
+        catalogs.set(tool, catalog);
+}
 function fail(message) {
     return { content: message, isError: true };
 }
@@ -27,21 +42,37 @@ export function buildSubagentRequest(input, ctx) {
     if (typeof input.prompt !== "string" || input.prompt.trim() === "") {
         return "prompt must be a non-empty string";
     }
-    const maxTurns = input.maxTurns ?? DEFAULT_TASK_MAX_TURNS;
-    if (!Number.isInteger(maxTurns) || maxTurns < 1)
+    if (input.maxTurns !== undefined && (!Number.isInteger(input.maxTurns) || input.maxTurns < 1))
         return "maxTurns must be an integer ≥ 1";
     if (input.thinkingLevel !== undefined && !THINKING.includes(input.thinkingLevel)) {
         return `thinkingLevel must be one of ${THINKING.join(", ")}`;
     }
+    if (input.isolation !== undefined && input.isolation !== "none" && input.isolation !== "worktree")
+        return 'isolation must be "none" or "worktree"';
+    if (input.budgetUsd !== undefined && !(input.budgetUsd > 0))
+        return "budgetUsd must be > 0";
     const request = {
         prompt: input.prompt,
-        maxTurns,
         parentToolCallId: ctx.toolCallId,
         signal: ctx.signal,
         onUpdate: (partial) => ctx.onUpdate(partial),
     };
+    if (input.maxTurns !== undefined)
+        request.maxTurns = input.maxTurns;
     if (input.description !== undefined)
         request.description = input.description;
+    if (input.background !== undefined)
+        request.background = input.background;
+    if (input.taskId !== undefined) {
+        request.taskId = input.taskId;
+        return request;
+    }
+    if (input.agent !== undefined)
+        request.agent = input.agent;
+    if (input.isolation !== undefined)
+        request.isolation = input.isolation;
+    if (input.budgetUsd !== undefined)
+        request.budgetUsd = input.budgetUsd;
     if (input.tools !== undefined)
         request.tools = input.tools.filter((t) => t !== "task");
     if (input.model !== undefined)
@@ -51,31 +82,35 @@ export function buildSubagentRequest(input, ctx) {
     return request;
 }
 export function createTaskTool(_options = {}) {
-    return {
+    const tool = {
         name: "task",
         label: "Task",
-        description: "Delegate to a fresh sub-agent. It cannot see this chat: give full instructions. " +
-            "Returns its final answer.",
+        get description() {
+            const catalog = catalogs.get(tool) ?? new AgentCatalog();
+            return `${BASE_DESCRIPTION}${TASK_AGENTS_HEADING}${catalog.describe()}`;
+        },
         parameters: {
             type: "object",
             properties: {
                 prompt: { type: "string" },
-                description: { type: "string", description: "Label" },
-                tools: {
-                    type: "array",
-                    items: { type: "string" },
-                    description: "Default: all but task",
-                },
-                model: { type: "string", description: "provider/model" },
+                agent: { type: "string", description: "Default general" },
+                description: { type: "string" },
+                background: { type: "boolean" },
+                taskId: { type: "string" },
+                isolation: { type: "string", enum: ["none", "worktree"] },
+                budgetUsd: { type: "number" },
+                tools: { type: "array", items: { type: "string" } },
+                model: { type: "string" },
                 thinkingLevel: { type: "string", enum: [...THINKING] },
-                maxTurns: { type: "integer", description: `Default ${DEFAULT_TASK_MAX_TURNS}` },
+                maxTurns: { type: "integer" },
             },
             required: ["prompt"],
             additionalProperties: false,
         },
         permission: "execute",
-        executionMode: "sequential",
+        executionMode: "parallel",
         promptSnippet: "task: run a sub-agent",
+        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).");
@@ -88,14 +123,18 @@ export function createTaskTool(_options = {}) {
             try {
                 const result = await ctx.spawnSubagent(request);
                 const details = {
+                    ...(result.taskId !== undefined ? { taskId: result.taskId } : {}),
+                    ...(result.status !== undefined ? { status: result.status } : {}),
                     ...(result.sessionFile !== undefined ? { sessionFile: result.sessionFile } : {}),
+                    ...(result.outputFile !== undefined ? { outputFile: result.outputFile } : {}),
                     usage: result.usage,
                     stopReason: result.stopReason,
                 };
-                if (ctx.signal.aborted)
+                if (ctx.signal.aborted && result.status !== "running")
                     return { content: "aborted by user", isError: true, details };
                 const text = result.text.trim() === "" ? "(the sub-agent returned no text)" : result.text;
-                return { content: text, isError: result.isError, details };
+                const head = result.taskId !== undefined ? `[task ${result.taskId}] ` : "";
+                return { content: `${head}${text}`, isError: result.isError, details };
             }
             catch (err) {
                 if (ctx.signal.aborted)
@@ -104,4 +143,5 @@ export function createTaskTool(_options = {}) {
             }
         },
     };
+    return tool;
 }

package/dist/tools/todo.d.ts

@@ -4,6 +4,9 @@
  * 会话内任务清单：`set` 整表替换并写 `custom{customType:"ama.todo"}` 条目（不进上下文），`get`
  * 读活动分支上最近一条。`renderTodoList()` 给 TUI / 结果文本共用。待定项「todo 是否进系统提示」：
  * 第一期不进（只有 promptSnippet 一行说明工具存在）。
+ * [W5-F] `update` 按 id 局部更新（`items: {id, status?, text?}[]`，省得整表重发）；条目可带 `planStep`
+ * 指回计划步骤（批准计划时由 plan 扩展生成清单）。plan 模式下 `set / update` 由权限管线拒绝。
+ * 「连续多回合未更新」的提醒走 W5-H2 的提醒通道（`ama.reminder`，config `todo.reminder`）。
  */
 import type { ToolContext, ToolDefinition, ToolResult } from "./types.js";
 export declare const TODO_CUSTOM_TYPE = "ama.todo";
@@ -12,17 +15,34 @@ export interface TodoItem {
     id: string;
     text: string;
     status: TodoStatus;
+    /** [W5-F] 来自计划的步骤 id（`S1`…）。 */
+    planStep?: string;
+}
+/** [W5-F] `update` 的一条补丁：按 id 改状态或文字。 */
+export interface TodoPatch {
+    id: string;
+    status?: TodoStatus;
+    text?: string;
 }
 export interface TodoState {
     items: TodoItem[];
 }
 export interface TodoInput {
-    action: "set" | "get";
-    items?: TodoItem[];
+    action: "set" | "get" | "update";
+    /** set：整表；update：补丁（`{id, status?, text?}`）。 */
+    items?: TodoItem[] | TodoPatch[];
 }
 export declare function validateTodoItems(items: unknown): string | undefined;
+/** `ama.todo` 条目的 data → 清单；形状不对返回空表。 */
+export declare function parseTodoState(data: unknown): TodoState;
 /** 读当前清单；无记录或形状不对返回空表。 */
 export declare function readTodoState(ctx: Pick<ToolContext, "session">): TodoState;
+/** [W5-F] 按 id 应用补丁；返回新清单或错误说明。 */
+export declare function applyTodoPatches(items: readonly TodoItem[], updates: unknown): {
+    items: TodoItem[];
+} | {
+    error: string;
+};
 export declare function renderTodoList(items: readonly TodoItem[]): string[];
 export declare function executeTodo(input: TodoInput, ctx: ToolContext): Promise<ToolResult>;
 export declare function createTodoTool(): ToolDefinition<TodoInput>;

package/dist/tools/todo.js

@@ -4,6 +4,9 @@
  * 会话内任务清单：`set` 整表替换并写 `custom{customType:"ama.todo"}` 条目（不进上下文），`get`
  * 读活动分支上最近一条。`renderTodoList()` 给 TUI / 结果文本共用。待定项「todo 是否进系统提示」：
  * 第一期不进（只有 promptSnippet 一行说明工具存在）。
+ * [W5-F] `update` 按 id 局部更新（`items: {id, status?, text?}[]`，省得整表重发）；条目可带 `planStep`
+ * 指回计划步骤（批准计划时由 plan 扩展生成清单）。plan 模式下 `set / update` 由权限管线拒绝。
+ * 「连续多回合未更新」的提醒走 W5-H2 的提醒通道（`ama.reminder`，config `todo.reminder`）。
  */
 export const TODO_CUSTOM_TYPE = "ama.todo";
 const STATUSES = ["pending", "in_progress", "done"];
@@ -15,7 +18,7 @@ export function validateTodoItems(items) {
     for (const [i, item] of items.entries()) {
         if (typeof item !== "object" || item === null)
             return `items[${i}] must be an object`;
-        const { id, text, status } = item;
+        const { id, text, status, planStep } = item;
         if (typeof id !== "string" || id === "")
             return `items[${i}].id must be a non-empty string`;
         if (typeof text !== "string" || text === "")
@@ -23,15 +26,16 @@ export function validateTodoItems(items) {
         if (!STATUSES.includes(status)) {
             return `items[${i}].status must be one of ${STATUSES.join(", ")}`;
         }
+        if (planStep !== undefined && typeof planStep !== "string")
+            return `items[${i}].planStep must be a string`;
         if (ids.has(id))
             return `duplicate id "${id}"`;
         ids.add(id);
     }
     return undefined;
 }
-/** 读当前清单；无记录或形状不对返回空表。 */
-export function readTodoState(ctx) {
-    const data = ctx.session.lastCustom(TODO_CUSTOM_TYPE);
+/** `ama.todo` 条目的 data → 清单；形状不对返回空表。 */
+export function parseTodoState(data) {
     if (typeof data === "object" && data !== null && Array.isArray(data.items)) {
         const items = data.items;
         if (validateTodoItems(items) === undefined)
@@ -39,6 +43,36 @@ export function readTodoState(ctx) {
     }
     return { items: [] };
 }
+/** 读当前清单；无记录或形状不对返回空表。 */
+export function readTodoState(ctx) {
+    return parseTodoState(ctx.session.lastCustom(TODO_CUSTOM_TYPE));
+}
+/** [W5-F] 按 id 应用补丁；返回新清单或错误说明。 */
+export function applyTodoPatches(items, updates) {
+    if (!Array.isArray(updates) || updates.length === 0)
+        return { error: "items must be a non-empty array of {id, status?, text?}" };
+    const next = items.map((it) => ({ ...it }));
+    for (const [i, patch] of updates.entries()) {
+        if (typeof patch !== "object" || patch === null)
+            return { error: `items[${i}] must be an object` };
+        const { id, status, text } = patch;
+        const item = next.find((it) => it.id === id);
+        if (item === undefined)
+            return { error: `items[${i}]: no task with id "${String(id)}"` };
+        if (status !== undefined) {
+            if (!STATUSES.includes(status)) {
+                return { error: `items[${i}].status must be one of ${STATUSES.join(", ")}` };
+            }
+            item.status = status;
+        }
+        if (text !== undefined) {
+            if (typeof text !== "string" || text === "")
+                return { error: `items[${i}].text must be a non-empty string` };
+            item.text = text;
+        }
+    }
+    return { items: next };
+}
 export function renderTodoList(items) {
     if (items.length === 0)
         return ["(no tasks)"];
@@ -56,12 +90,22 @@ export async function executeTodo(input, ctx) {
             details: state,
         };
     }
-    if (input.action !== "set")
-        return { content: 'action must be "set" or "get"', isError: true };
-    const problem = validateTodoItems(input.items ?? []);
-    if (problem !== undefined)
-        return { content: problem, isError: true };
-    const state = { items: (input.items ?? []).map((it) => ({ ...it })) };
+    let state;
+    if (input.action === "update") {
+        const patched = applyTodoPatches(readTodoState(ctx).items, input.items);
+        if ("error" in patched)
+            return { content: patched.error, isError: true };
+        state = patched;
+    }
+    else if (input.action === "set") {
+        const problem = validateTodoItems(input.items ?? []);
+        if (problem !== undefined)
+            return { content: problem, isError: true };
+        state = { items: (input.items ?? []).map((it) => ({ ...it })) };
+    }
+    else {
+        return { content: 'action must be "set", "update" or "get"', isError: true };
+    }
     ctx.session.appendCustom(TODO_CUSTOM_TYPE, state);
     return {
         content: [`Updated tasks (${summary(state.items)}):`, ...renderTodoList(state.items)].join("\n"),
@@ -72,22 +116,22 @@ export function createTodoTool() {
     return {
         name: "todo",
         label: "Todo",
-        description: "Session task list for multi-step work: `set` replaces the whole list, `get` returns it.",
+        description: "Session task list: `set` replaces all items, `update` changes items by id (only given fields), `get` reads.",
         parameters: {
             type: "object",
             properties: {
-                action: { type: "string", enum: ["set", "get"] },
+                action: { type: "string", enum: ["set", "update", "get"] },
                 items: {
                     type: "array",
-                    description: "Full list (set)",
                     items: {
                         type: "object",
                         properties: {
                             id: { type: "string" },
                             text: { type: "string" },
                             status: { type: "string", enum: ["pending", "in_progress", "done"] },
+                            planStep: { type: "string" },
                         },
-                        required: ["id", "text", "status"],
+                        required: ["id"],
                         additionalProperties: false,
                     },
                 },

package/dist/tools/truncate.d.ts

@@ -2,6 +2,8 @@
  * 头 / 尾截断（行数 + 字节双阈值，先到者为准）与全文落盘（设计 §5.2、§4.4）。[B3]
  *
  * - read / grep 用**头截断**（保留开头，提示 offset 续读）；bash 用**尾截断**（保留结尾）。
+ * - [W5-H2] 会话层通用截断（`maxToolResultChars`）用**头 + 尾**（`truncateMiddle`）：保留前 70% 与
+ *   后 30%，中间换成省略说明（错误信息常在尾部）。
  * - 字节按 UTF-8 计；不切断多字节字符；单行超过字节上限时按字符边界截该行。
  */
 export declare const DEFAULT_MAX_LINES = 2000;
@@ -33,6 +35,19 @@ export declare function sliceTailBytes(text: string, maxBytes: number): string;
 export declare function truncateHead(text: string, options?: TruncateOptions): TruncateResult;
 /** 保留结尾。 */
 export declare function truncateTail(text: string, options?: TruncateOptions): TruncateResult;
+/** 头 + 尾截断时开头所占的比例（§8.3 H5）。 */
+export declare const HEAD_TAIL_RATIO = 0.7;
+export interface MiddleTruncation {
+    /** 截断后的文本（未超限时原样）。 */
+    content: string;
+    /** 省略的字符数（UTF-16 单元）；未截断为 0。 */
+    omitted: number;
+}
+/**
+ * 头 + 尾截断（[W5-H2] §8.3 H5）：超过 `maxChars` 时保留前 70% 与后 30%，中间换成
+ * `marker(省略字符数)` 的文本（缺省 `[… N 字符已省略]`）。
+ */
+export declare function truncateMiddle(text: string, maxChars: number, marker?: (omitted: number) => string): MiddleTruncation;
 /** 单行按字符截断，附省略提示。 */
 export declare function truncateLine(line: string, maxChars?: number): string;
 export declare function formatSize(bytes: number): string;

package/dist/tools/truncate.js

@@ -2,6 +2,8 @@
  * 头 / 尾截断（行数 + 字节双阈值，先到者为准）与全文落盘（设计 §5.2、§4.4）。[B3]
  *
  * - read / grep 用**头截断**（保留开头，提示 offset 续读）；bash 用**尾截断**（保留结尾）。
+ * - [W5-H2] 会话层通用截断（`maxToolResultChars`）用**头 + 尾**（`truncateMiddle`）：保留前 70% 与
+ *   后 30%，中间换成省略说明（错误信息常在尾部）。
  * - 字节按 UTF-8 计；不切断多字节字符；单行超过字节上限时按字符边界截该行。
  */
 import { mkdirSync, writeFileSync } from "node:fs";
@@ -142,6 +144,29 @@ export function truncateTail(text, options = {}) {
         outputBytes: byteLength(content),
     };
 }
+/** 头 + 尾截断时开头所占的比例（§8.3 H5）。 */
+export const HEAD_TAIL_RATIO = 0.7;
+/** 下标落在代理对中间时往前挪一位，不切断字符。 */
+function charBoundary(text, index) {
+    if (index <= 0 || index >= text.length)
+        return index;
+    const code = text.charCodeAt(index);
+    return code >= 0xdc00 && code <= 0xdfff ? index - 1 : index;
+}
+/**
+ * 头 + 尾截断（[W5-H2] §8.3 H5）：超过 `maxChars` 时保留前 70% 与后 30%，中间换成
+ * `marker(省略字符数)` 的文本（缺省 `[… N 字符已省略]`）。
+ */
+export function truncateMiddle(text, maxChars, marker = (omitted) => `[… ${omitted} 字符已省略]`) {
+    if (text.length <= maxChars)
+        return { content: text, omitted: 0 };
+    const limit = Math.max(0, Math.floor(maxChars));
+    const headEnd = charBoundary(text, Math.floor(limit * HEAD_TAIL_RATIO));
+    const tailStart = charBoundary(text, text.length - (limit - headEnd));
+    const omitted = tailStart - headEnd;
+    const content = `${text.slice(0, headEnd)}\n\n${marker(omitted)}\n\n${text.slice(tailStart)}`;
+    return { content, omitted };
+}
 /** 单行按字符截断，附省略提示。 */
 export function truncateLine(line, maxChars = GREP_MAX_LINE_CHARS) {
     const chars = Array.from(line);

package/dist/tools/types.d.ts

@@ -12,8 +12,15 @@
  * - `defineTool()` 是恒等函数，只为推断 `I`；放在契约文件里供 SDK 再导出。
  * - `ToolRegistryApi` 是 Runtime 需要的最小接口，B3 的 `ToolRegistry` 实现它。
  * - （W3-C0）`SubagentResult.cache` 可选：子会话的命中率与重计费 token。
+ * - （W5-C0）第五波（docs/wave5-plan.md §7.3–§7.6、§8.2 C4、§8.3 H1）：`annotations.pollable /
+ *   keepInContext`；`SubagentRequest` 加 `agent / background / taskId / isolation / budgetUsd`；
+ *   `SubagentResult` 加 `taskId / status / outputFile / sessionRef`（契约要求向后兼容，全部可选）；
+ *   统一入口 `SubagentRunner / RunnerHandle / SubagentEvent`（ama 子会话、外部 CLI、宿主 runner）；
+ *   `ToolContext.tasks` 为任务注册表的只读视图（W5-G 提供）。
  */
 import type { ContentBlock, JsonSchema, ModelRef, ModelThinkingLevel, Usage } from "../ai/types.js";
+import type { CheckpointHooks } from "../checkpoints/types.js";
+import type { PermissionMode } from "../permissions/types.js";
 export type { JsonSchema } from "../ai/types.js";
 /** 权限管线的粗分类（§7）。 */
 export type ToolPermission = "read" | "write" | "execute";
@@ -22,6 +29,10 @@ export interface ToolAnnotations {
     readOnly?: boolean;
     destructive?: boolean;
     openWorld?: boolean;
+    /** [W5-C0] 轮询类调用（`task_ctl wait`、后台 bash 查询）：重复调用检测豁免（§8.3 H1）。 */
+    pollable?: boolean;
+    /** [W5-C0] 结果不被档一裁剪（压缩保护集，§8.2 C4）。 */
+    keepInContext?: boolean;
 }
 export interface ToolDefinition<I = unknown> {
     /** `^[a-z][a-z0-9_]{1,63}$`；宿主工具建议前缀（canvas_*）。 */
@@ -66,6 +77,24 @@ export interface SubagentRequest {
     parentToolCallId: string;
     signal: AbortSignal;
     onUpdate?(partial: string): void;
+    /** [W5-C0] 子 Agent 类型或外部 Agent id；缺省 `general`。 */
+    agent?: string;
+    /** [W5-C0] 后台运行：立即返回 taskId，完成后以 `<task-notification>` 通知。 */
+    background?: boolean;
+    /** [W5-C0] 续聊：向已有子会话追加消息（忽略 agent / tools / model）。 */
+    taskId?: string;
+    /** [W5-C0] `worktree`：在 `<repo>/.ama/worktrees/<taskId>` 里运行；缺省 `none`。 */
+    isolation?: "none" | "worktree";
+    /** [W5-C0] 外部 Agent 的美元预算。 */
+    budgetUsd?: number;
+}
+/** [W5-C0] 子 Agent 任务的终态（`subagent_end.status`）。 */
+export type SubagentStatus = "completed" | "failed" | "aborted" | "max_turns" | "interrupted";
+/** [W5-C0] 会话引用：ama 子会话文件，或外部 CLI 自己的会话 id（`custom{ama.agent-session}`）。 */
+export interface SubagentSessionRef {
+    runner: string;
+    sessionId: string;
+    sessionFile?: string;
 }
 export interface SubagentResult {
     /** 子会话最后一条助手文本。 */
@@ -82,6 +111,86 @@ export interface SubagentResult {
         hitRate?: number;
         reBilledTokens: number;
     };
+    /** [W5-C0] 注册表里的任务 id（W5-G 起总有）。 */
+    taskId?: string;
+    /** [W5-C0] 终态；后台启动时为 `running`。 */
+    status?: SubagentStatus | "running";
+    /** [W5-C0] 结果全文（> 50 KB 截断时、后台任务的输出文件）。 */
+    outputFile?: string;
+    sessionRef?: SubagentSessionRef;
+}
+/** runner 上报的进度（由注册表转成 `subagent_update` 事件）。 */
+export type SubagentEvent = {
+    type: "text";
+    delta: string;
+} | {
+    type: "thought";
+    delta: string;
+} | {
+    type: "tool";
+    toolName: string;
+    status: "started" | "completed" | "failed";
+} | {
+    type: "turn";
+    turn: number;
+} | {
+    type: "usage";
+    usage?: Usage;
+    /** 无美元单位的外部 Agent 按各自单位记（不换算）。 */
+    unit?: "usd" | "tokens" | "requests";
+    amount?: number;
+} | {
+    type: "notice";
+    level: "info" | "warn";
+    text: string;
+};
+export interface SubagentRunRequest {
+    prompt: string;
+    cwd: string;
+    /** 不得比父会话当前模式宽（`isAtLeastAsStrict`）。 */
+    mode: PermissionMode;
+    model?: string;
+    /** 续聊的会话 id（runner 自己的）。 */
+    resume?: string;
+    budgetUsd?: number;
+    /** [W5-EG] 发起的任务 id（审批标注 `context.taskId`、外部会话引用记账用）；可选。 */
+    taskId?: string;
+    signal: AbortSignal;
+    onEvent(event: SubagentEvent): void;
+}
+export interface RunnerHandle {
+    /** 子会话 / 外部会话 id。 */
+    readonly id: string;
+    /** 续聊。 */
+    send(text: string): Promise<void>;
+    wait(): Promise<SubagentResult>;
+    stop(): Promise<void>;
+}
+/** `ama`（AmaRunner）| `claude` | `codex` | `acp:<program>`（ProcessRunner，W5-E）| 宿主 id。 */
+export interface SubagentRunner {
+    readonly id: string;
+    start(request: SubagentRunRequest): Promise<RunnerHandle>;
+}
+/** [W5-C0] 任务注册表里一条任务的快照（`task_ctl list`、RPC `get_tasks`、`/tasks`）。 */
+export interface TaskInfo {
+    taskId: string;
+    agent: string;
+    runner: string;
+    description: string;
+    background: boolean;
+    status: SubagentStatus | "running";
+    startedAt: number;
+    endedAt?: number;
+    turns?: number;
+    usage?: Usage;
+    costUsd?: number;
+    outputFile?: string;
+    sessionRef?: SubagentSessionRef;
+}
+/** [W5-C0] 任务注册表的只读视图（W5-G 的 `SubagentRegistry` 提供）。 */
+export interface TaskRegistryView {
+    list(): readonly TaskInfo[];
+    get(taskId: string): TaskInfo | undefined;
 }
 export interface ToolContext {
     readonly toolCallId: string;
@@ -115,8 +224,12 @@ export interface ToolContext {
         /** 活动分支上最近一条该类型 custom 条目的 data。 */
         lastCustom(customType: string): unknown;
     };
+    /** 检查点（docs/rewind-plan.md §2）：edit / write 写文件前后调用；未启用时为 undefined。 */
+    readonly checkpoint?: CheckpointHooks;
     /** 仅 depth 0 且 task 可用时存在。 */
     readonly spawnSubagent?: (request: SubagentRequest) => Promise<SubagentResult>;
+    /** [W5-C0] 任务注册表只读视图（`task_ctl`）；注册表未装配时 undefined。 */
+    readonly tasks?: TaskRegistryView;
     log(level: "debug" | "info" | "warn", message: string): void;
 }
 export type ToolSource = "builtin" | "host" | "sdk";

package/dist/tools/types.js

@@ -12,6 +12,11 @@
  * - `defineTool()` 是恒等函数，只为推断 `I`；放在契约文件里供 SDK 再导出。
  * - `ToolRegistryApi` 是 Runtime 需要的最小接口，B3 的 `ToolRegistry` 实现它。
  * - （W3-C0）`SubagentResult.cache` 可选：子会话的命中率与重计费 token。
+ * - （W5-C0）第五波（docs/wave5-plan.md §7.3–§7.6、§8.2 C4、§8.3 H1）：`annotations.pollable /
+ *   keepInContext`；`SubagentRequest` 加 `agent / background / taskId / isolation / budgetUsd`；
+ *   `SubagentResult` 加 `taskId / status / outputFile / sessionRef`（契约要求向后兼容，全部可选）；
+ *   统一入口 `SubagentRunner / RunnerHandle / SubagentEvent`（ama 子会话、外部 CLI、宿主 runner）；
+ *   `ToolContext.tasks` 为任务注册表的只读视图（W5-G 提供）。
  */
 /** 恒等函数，帮助推断输入类型。 */
 export function defineTool(tool) {

package/dist/tools/write.js

@@ -8,6 +8,7 @@ import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import { displayPath, resolvePath } from "./paths.js";
 import { withFileMutex } from "./file-mutex.js";
+import { beforeWrite } from "./edit.js";
 import { BOM, detectLineEnding, normalizeToLF, restoreLineEndings, splitBom, } from "./edit-fuzzy.js";
 async function exists(path) {
     try {
@@ -48,8 +49,10 @@ export async function executeWrite(input, ctx) {
             }
             output = conformToOriginal(await readFile(abs, "utf8"), input.content);
         }
+        await beforeWrite(ctx, abs);
         await mkdir(dirname(abs), { recursive: true });
         await writeFile(abs, output, "utf8");
+        ctx.checkpoint?.afterWrite(abs, output);
         ctx.markRead(abs);
         const details = {
             path: abs,

package/dist/tui/glyphs.d.ts

@@ -58,6 +58,10 @@ export interface Glyphs {
     readonly ellipsis: string;
     readonly arrowUp: string;
     readonly arrowDown: string;
+    /** [W5-A] 状态栏 git 分支标记。 */
+    readonly branch: string;
+    /** [W5-A] 速率行分隔点。 */
+    readonly dot: string;
 }
 export declare const UNICODE_GLYPHS: Glyphs;
 export declare const ASCII_GLYPHS: Glyphs;

package/dist/tui/glyphs.js

@@ -42,6 +42,8 @@ export const UNICODE_GLYPHS = {
     ellipsis: "…",
     arrowUp: "↑",
     arrowDown: "↓",
+    branch: "⎇",
+    dot: "•",
 };
 export const ASCII_GLYPHS = {
     ascii: true,
@@ -77,6 +79,8 @@ export const ASCII_GLYPHS = {
     ellipsis: "...",
     arrowUp: "^",
     arrowDown: "v",
+    branch: "git",
+    dot: "*",
 };
 function truthy(value) {
     if (value === undefined || value === "")

package/dist/tui/keybindings.d.ts

@@ -31,14 +31,19 @@ export declare const DEFAULT_KEYBINDINGS: {
     readonly "tui.select.confirm": readonly ["enter", "tab"];
     readonly "tui.select.cancel": readonly ["escape", "ctrl+c"];
     readonly "app.interrupt": readonly ["escape"];
+    readonly "app.rewind": readonly ["escape"];
     readonly "app.clear": readonly ["ctrl+c"];
     readonly "app.exit": readonly ["ctrl+d"];
     readonly "app.message.followUp": readonly ["alt+enter"];
     readonly "app.message.dequeue": readonly ["alt+up"];
-    readonly "app.permission.cycle": readonly ["shift+tab"];
+    readonly "app.permission.cycle": readonly ["shift+tab", "tab"];
     readonly "app.tools.expand": readonly ["ctrl+o"];
     readonly "app.model.select": readonly ["ctrl+l"];
     readonly "app.thinking.select": readonly ["ctrl+t"];
+    /** [W5-A] 底部信息行 full ↔ compact（只影响本会话）。 */
+    readonly "app.statusLine.toggle": readonly ["ctrl+g"];
+    /** [W5-U] 粘贴剪贴板图片（写进数据目录，输入框插入 `@路径`）。 */
+    readonly "app.paste.image": readonly ["ctrl+v"];
 };
 export type ActionId = keyof typeof DEFAULT_KEYBINDINGS;
 export type KeybindingOverrides = Partial<Record<ActionId, readonly string[]>>;