@armadra/agent 0.4.0 → 0.5.1

package/dist/modes/interactive/subagent-view.js

@@ -0,0 +1,154 @@
+/**
+ * 消息区的子 Agent 折叠视图（docs/wave5-plan.md §7.5）。[W5-U]
+ *
+ * 消费 `subagent_start / update / end`，按 taskId 记下类型、状态、轮数、最近 3 个工具与用量；task 工具行
+ * （tool-view.ts）据 `parentToolCallId` 取来显示一行：
+ *
+ * ```
+ * ⏺ task 检查 src/tui 的测试覆盖缺口
+ *   ⎿ ⠋ explore · 运行中 1m05s · 3 轮 · read grep bash · ↑12k ↓3.4k
+ * ```
+ *
+ * 后台任务的工具调用立即返回，工具行下面多一行跟随状态（`↳ t2 explore · 完成 · 7 轮 …`，运行中每秒刷新）；
+ * 完成后父会话收到的 `<task-notification>` 只显示一行（`notificationSummary`），失败 / 停止另有一行提示。
+ * 外部 runner（claude / codex）同一组事件，用量可能缺。
+ */
+import { formatElapsed } from "../../tui.js";
+import { formatTokenCount } from "../session-report.js";
+import { taskStatusText } from "./tasks-report.js";
+export const RECENT_TOOLS = 3;
+export class SubagentTracker {
+    now;
+    tasks = new Map();
+    byCall = new Map();
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    /** 子 Agent 事件：更新状态并返回它；其它事件返回 undefined。 */
+    onEvent(event) {
+        switch (event.type) {
+            case "subagent_start": {
+                const previous = this.tasks.get(event.taskId);
+                const state = {
+                    taskId: event.taskId,
+                    parentToolCallId: event.parentToolCallId,
+                    agent: event.agent,
+                    runner: event.runner,
+                    background: event.background,
+                    status: "running",
+                    // 续聊（同一 taskId 再次 start）沿用轮数与工具
+                    turns: previous?.turns ?? 0,
+                    tools: previous?.tools ?? [],
+                    startedAt: this.now(),
+                };
+                this.tasks.set(event.taskId, state);
+                this.byCall.set(event.parentToolCallId, event.taskId);
+                return state;
+            }
+            case "subagent_update": {
+                const state = this.tasks.get(event.taskId);
+                if (state === undefined)
+                    return undefined;
+                if (event.turn > state.turns)
+                    state.turns = event.turn;
+                if (event.usage !== undefined)
+                    state.usage = event.usage;
+                if (event.kind === "tool" && event.toolName !== undefined) {
+                    state.tools.push(event.toolName);
+                    if (state.tools.length > RECENT_TOOLS)
+                        state.tools.splice(0, state.tools.length - RECENT_TOOLS);
+                }
+                return state;
+            }
+            case "subagent_end": {
+                const state = this.tasks.get(event.taskId);
+                if (state === undefined)
+                    return undefined;
+                state.status = event.status;
+                state.endedAt = this.now();
+                if (event.usage !== undefined)
+                    state.usage = event.usage;
+                return state;
+            }
+            default:
+                return undefined;
+        }
+    }
+    /** 运行中的任务。 */
+    running() {
+        return [...this.tasks.values()].filter((state) => state.status === "running");
+    }
+    get(taskId) {
+        return this.tasks.get(taskId);
+    }
+    /** task 工具调用对应的子 Agent（续聊时是同一 taskId）。 */
+    forToolCall(toolCallId) {
+        const taskId = this.byCall.get(toolCallId);
+        return taskId === undefined ? undefined : this.tasks.get(taskId);
+    }
+    clear() {
+        this.tasks.clear();
+        this.byCall.clear();
+    }
+}
+/** `explore · 运行中 1m05s · 3 轮 · read grep bash · ↑12k ↓3.4k`（已着色：类型 tool 色，其余 muted）。 */
+export function subagentLine(state, theme, now) {
+    const g = theme.glyphs;
+    const end = state.endedAt ?? now;
+    const elapsed = formatElapsed(end - state.startedAt);
+    const status = state.status === "running" ? `运行中 ${elapsed}` : `${taskStatusText(state.status)} ${elapsed}`;
+    const facts = [status];
+    if (state.turns > 0)
+        facts.push(`${state.turns} 轮`);
+    if (state.tools.length > 0)
+        facts.push(state.tools.join(" "));
+    const usage = state.usage;
+    if (usage !== undefined && usage.input + usage.output + usage.cacheRead > 0) {
+        const input = usage.input + usage.cacheRead + usage.cacheWrite;
+        facts.push(`${g.arrowUp}${formatTokenCount(input)} ${g.arrowDown}${formatTokenCount(usage.output)}`);
+    }
+    const color = state.status === "running" || state.status === "completed"
+        ? "muted"
+        : state.status === "failed"
+            ? "error"
+            : "warning";
+    const agent = state.runner !== "ama" && state.runner !== state.agent
+        ? `${state.agent}（${state.runner}）`
+        : state.agent;
+    return theme.fg("tool", agent) + theme.fg("dim", " · ") + theme.fg(color, facts.join(" · "));
+}
+/** 后台任务结束的一行提示。 */
+export function backgroundEndText(state) {
+    const turns = state.turns > 0 ? ` · ${state.turns} 轮` : "";
+    return `后台任务 ${state.taskId}（${state.agent}）${taskStatusText(state.status)}${turns} · /tasks 查看输出`;
+}
+/**
+ * 父会话收到的 `<task-notification …>`（origin `task` 的用户消息）在消息区只显示一行：
+ * `t1 explore 完成 · 7 轮 · /tasks 查看输出`；不是通知格式返回 undefined。
+ */
+export function notificationSummary(text) {
+    const head = /^<task-notification\s+([^>]*)>/.exec(text.trimStart());
+    if (head === null)
+        return undefined;
+    const attrs = new Map();
+    for (const m of (head[1] ?? "").matchAll(/(\w+)="([^"]*)"/g))
+        attrs.set(m[1], m[2]);
+    const taskId = attrs.get("taskId") ?? "?";
+    const status = attrs.get("status");
+    const parts = [
+        `${taskId} ${attrs.get("agent") ?? ""}`.trim() +
+            ` ${status !== undefined && status in STATUS_KEYS ? taskStatusText(status) : (status ?? "")}`,
+    ];
+    const turns = attrs.get("turns");
+    if (turns !== undefined)
+        parts.push(`${turns} 轮`);
+    parts.push("/tasks 查看输出");
+    return parts.join(" · ");
+}
+const STATUS_KEYS = {
+    completed: true,
+    failed: true,
+    aborted: true,
+    max_turns: true,
+    interrupted: true,
+};

package/dist/modes/interactive/tasks-report.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `/tasks`、`/agents` 的数据与文本（line 模式与交互模式共用）。[W5-U]
+ *
+ * - 任务：`taskRegistryView(sessionId).list()`（子 Agent 注册表，W5-G）；全文 `registryOf(sessionId).output()`；
+ *   停止 `registryOf(sessionId).stop()`。
+ * - 类型：`cachedAgentInfos(sessionId) ?? sessionAgents(sessionId)`（外部 Agent 带安装状态与版本，W5-EG）。
+ */
+import type { AgentInfo } from "../../agents/types.js";
+import type { SubagentStatus, TaskInfo } from "../../tools/types.js";
+export declare function taskStatusText(status: SubagentStatus | "running"): string;
+export declare function listTasks(sessionId: string): readonly TaskInfo[];
+export declare function listAgents(sessionId: string): AgentInfo[];
+/** 运行中是已有输出，结束后是最终文本。 */
+export declare function taskOutput(sessionId: string, taskId: string): string | undefined;
+export declare function stopTask(sessionId: string, taskId: string): Promise<void>;
+/** 任务一行的各字段（状态、耗时、轮数、用量、费用）。 */
+export declare function taskFacts(task: TaskInfo, now: number): string[];
+/** `t1  explore · 运行中 · 1m05s · 7 轮 · 描述` */
+export declare function taskLine(task: TaskInfo, now: number): string;
+/** `/tasks` 的纯文本（line 模式）。 */
+export declare function describeTasks(sessionId: string, now: number): string;
+/** 一个任务的输出全文（line 模式 `/tasks <id>`）。 */
+export declare function describeTaskOutput(sessionId: string, taskId: string, now: number): string;
+/** 类型一行的状态：外部 Agent 写安装与版本。 */
+export declare function agentFacts(agent: AgentInfo): string[];
+/** `/agents` 的纯文本（line 模式）。 */
+export declare function describeAgents(sessionId: string): string;

package/dist/modes/interactive/tasks-report.js

@@ -0,0 +1,114 @@
+/**
+ * `/tasks`、`/agents` 的数据与文本（line 模式与交互模式共用）。[W5-U]
+ *
+ * - 任务：`taskRegistryView(sessionId).list()`（子 Agent 注册表，W5-G）；全文 `registryOf(sessionId).output()`；
+ *   停止 `registryOf(sessionId).stop()`。
+ * - 类型：`cachedAgentInfos(sessionId) ?? sessionAgents(sessionId)`（外部 Agent 带安装状态与版本，W5-EG）。
+ */
+import { cachedAgentInfos } from "../../agents/external.js";
+import { registryOf, sessionAgents, taskRegistryView } from "../../agent/subagent-registry.js";
+import { formatTokenCount, formatUsd } from "../session-report.js";
+import { formatDuration } from "./tool-summary.js";
+const STATUS = {
+    running: "运行中",
+    completed: "完成",
+    failed: "失败",
+    aborted: "已停止",
+    max_turns: "轮数耗尽",
+    interrupted: "已中断",
+};
+export function taskStatusText(status) {
+    return STATUS[status];
+}
+export function listTasks(sessionId) {
+    return taskRegistryView(sessionId)?.list() ?? [];
+}
+export function listAgents(sessionId) {
+    return cachedAgentInfos(sessionId) ?? sessionAgents(sessionId);
+}
+/** 运行中是已有输出，结束后是最终文本。 */
+export function taskOutput(sessionId, taskId) {
+    return registryOf(sessionId)?.output(taskId);
+}
+export async function stopTask(sessionId, taskId) {
+    const registry = registryOf(sessionId);
+    if (registry === undefined)
+        return;
+    await registry.stop(taskId);
+}
+/** 任务一行的各字段（状态、耗时、轮数、用量、费用）。 */
+export function taskFacts(task, now) {
+    const end = task.endedAt ?? now;
+    const facts = [taskStatusText(task.status), formatDuration(end - task.startedAt)];
+    if (task.turns !== undefined && task.turns > 0)
+        facts.push(`${task.turns} 轮`);
+    const usage = task.usage;
+    if (usage !== undefined && usage.input + usage.output + usage.cacheRead > 0)
+        facts.push(`↑${formatTokenCount(usage.input + usage.cacheRead + usage.cacheWrite)} ↓${formatTokenCount(usage.output)}`);
+    if (task.costUsd !== undefined && task.costUsd > 0)
+        facts.push(formatUsd(task.costUsd));
+    return facts;
+}
+function oneLine(text, max = 60) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+/** `t1  explore · 运行中 · 1m05s · 7 轮 · 描述` */
+export function taskLine(task, now) {
+    const agent = task.runner !== "ama" && task.runner !== task.agent
+        ? `${task.agent}（${task.runner}）`
+        : task.agent;
+    const parts = [agent, ...taskFacts(task, now)];
+    if (task.background)
+        parts.push("后台");
+    const description = oneLine(task.description);
+    return `${task.taskId}  ${parts.join(" · ")}${description !== "" ? `  ${description}` : ""}`;
+}
+/** `/tasks` 的纯文本（line 模式）。 */
+export function describeTasks(sessionId, now) {
+    const tasks = listTasks(sessionId);
+    if (tasks.length === 0)
+        return "还没有子 Agent 任务";
+    return [
+        `子 Agent 任务（${tasks.length}）：`,
+        ...tasks.map((task) => `  ${taskLine(task, now)}`),
+        "/tasks <id> 查看输出 · /tasks stop <id> 停止",
+    ].join("\n");
+}
+/** 一个任务的输出全文（line 模式 `/tasks <id>`）。 */
+export function describeTaskOutput(sessionId, taskId, now) {
+    const task = taskRegistryView(sessionId)?.get(taskId);
+    if (task === undefined)
+        return `没有任务 ${taskId}`;
+    const output = taskOutput(sessionId, taskId) ?? "";
+    const file = task.outputFile !== undefined ? `\n全文：${task.outputFile}` : "";
+    return `${taskLine(task, now)}${file}\n${output.trim() === "" ? "（还没有输出）" : output.trimEnd()}`;
+}
+const SOURCE = {
+    builtin: "内置",
+    cli: "命令行",
+    profile: "profile",
+    user: "用户",
+    project: "项目",
+    host: "宿主",
+};
+/** 类型一行的状态：外部 Agent 写安装与版本。 */
+export function agentFacts(agent) {
+    const facts = [agent.runner, SOURCE[agent.source] ?? agent.source];
+    if (agent.installed === false)
+        facts.push("未安装");
+    else if (agent.installed === true)
+        facts.push(agent.version !== undefined ? `已安装 ${agent.version}` : "已安装");
+    return facts;
+}
+/** `/agents` 的纯文本（line 模式）。 */
+export function describeAgents(sessionId) {
+    const agents = listAgents(sessionId);
+    if (agents.length === 0)
+        return "当前会话没有子 Agent（task 工具未启用）";
+    const width = Math.max(...agents.map((a) => a.name.length));
+    return [
+        `子 Agent 类型（${agents.length}）：`,
+        ...agents.map((a) => `  ${a.name.padEnd(width)}  ${agentFacts(a).join(" · ")}  ${oneLine(a.description)}`),
+    ].join("\n");
+}

package/dist/modes/interactive/tool-view.d.ts

@@ -9,7 +9,9 @@
  *     … 另 117 行（Ctrl+O 展开）
  * ```
  * - 运行中摘要行 `⎿ ⠋ 运行中 · 4s`：spinner 与底部 Loader 同帧（ToolTracker.tick 由 Loader.onFrame 驱动），
- *   标题行不变；bash 流式显示尾部 8 行（muted）。task 显示 `子 Agent · 运行中 1m05s`。
+ *   标题行不变；bash 流式显示尾部 8 行（muted）。task 显示 `子 Agent · 运行中 1m05s`；有 `subagent_*`
+ *   事件时（W5-U，subagent-view.ts）改为 `explore · 运行中 1m05s · 3 轮 · 最近 3 个工具 · ↑↓`，后台任务
+ *   在结果摘要下多一行跟随状态。
  * - 折叠（缺省）：结果前 3 行；edit 显示 `details.diff`（`@@` dim、`+` success、`-` error、上下文 muted，
  *   宽 ≥ 60 时带行号列），前 12 行；`Ctrl+O` 展开全部（上限 400 行，长行折行）。
  * - 嵌套：带 `parentToolCallId` 的调用（codemode 脚本里的 `tools.*`）挂在外层调用下、右移 4 列；折叠时只列
@@ -20,6 +22,7 @@
  */
 import type { ToolDefinition, ToolResult } from "../../tools/types.js";
 import { type Component, type Theme } from "../../tui.js";
+import { type SubagentState } from "./subagent-view.js";
 export { cleanLines, toolSummary } from "./tool-summary.js";
 export declare const COLLAPSED_RESULT_LINES = 3;
 export declare const COLLAPSED_DIFF_LINES = 12;
@@ -36,6 +39,8 @@ export interface ToolViewOptions {
     now?(): number;
     /** 运行中摘要行的 spinner 帧（与 Loader 同帧）；缺省静态字形。 */
     spinner?(): string;
+    /** [W5-U] task 调用对应的子 Agent 状态（折叠视图）；缺省不显示。 */
+    subagent?(toolCallId: string): SubagentState | undefined;
 }
 export declare class ToolView implements Component {
     readonly toolCallId: string;
@@ -69,14 +74,19 @@ export declare class ToolView implements Component {
     addNested(child: ToolView): void;
     /** 审批打开 / 关闭：还没有输出的运行中调用显示「等待确认」，关闭后从此刻重新计时。 */
     setAwaiting(awaiting: boolean): void;
-    /** spinner 换帧 / 秒数变化：运行中的视图重画摘要行。 */
+    /** spinner 换帧 / 秒数变化：运行中的视图重画摘要行（后台子 Agent 运行中也算）。 */
     tick(): void;
+    /** 外部状态变了（子 Agent 事件）：重画。 */
+    refresh(): void;
+    private subagentState;
     private touch;
     invalidate(): void;
     render(width: number): string[];
     header(width: number): string;
     /** `  ⎿ 摘要`：运行中带 spinner 与秒数，完成后是结果摘要。 */
     summaryLine(width: number): string | undefined;
+    /** 后台子 Agent：结果摘要下一行跟随状态 `    ↳ t2 explore · 完成 2m · 7 轮 …`。 */
+    private followLine;
     private custom;
     /** `renderCall` 的第一行（去控制字符、折叠空白）；没有或为空时 undefined。 */
     private customCall;

package/dist/modes/interactive/tool-view.js

@@ -9,7 +9,9 @@
  *     … 另 117 行（Ctrl+O 展开）
  * ```
  * - 运行中摘要行 `⎿ ⠋ 运行中 · 4s`：spinner 与底部 Loader 同帧（ToolTracker.tick 由 Loader.onFrame 驱动），
- *   标题行不变；bash 流式显示尾部 8 行（muted）。task 显示 `子 Agent · 运行中 1m05s`。
+ *   标题行不变；bash 流式显示尾部 8 行（muted）。task 显示 `子 Agent · 运行中 1m05s`；有 `subagent_*`
+ *   事件时（W5-U，subagent-view.ts）改为 `explore · 运行中 1m05s · 3 轮 · 最近 3 个工具 · ↑↓`，后台任务
+ *   在结果摘要下多一行跟随状态。
  * - 折叠（缺省）：结果前 3 行；edit 显示 `details.diff`（`@@` dim、`+` success、`-` error、上下文 muted，
  *   宽 ≥ 60 时带行号列），前 12 行；`Ctrl+O` 展开全部（上限 400 行，长行折行）。
  * - 嵌套：带 `parentToolCallId` 的调用（codemode 脚本里的 `tools.*`）挂在外层调用下、右移 4 列；折叠时只列
@@ -20,6 +22,7 @@
  */
 import { formatElapsed, truncateToWidth, wrapTextWithAnsi, } from "../../tui.js";
 import { contentText } from "./message-view.js";
+import { subagentLine } from "./subagent-view.js";
 import { bashOutput, cleanLines, diffOf, flat, parseDiff, resultSummary, toolSummary, } from "./tool-summary.js";
 export { cleanLines, toolSummary } from "./tool-summary.js";
 export const COLLAPSED_RESULT_LINES = 3;
@@ -108,11 +111,18 @@ export class ToolView {
         this.awaiting = awaiting;
         this.touch();
     }
-    /** spinner 换帧 / 秒数变化：运行中的视图重画摘要行。 */
+    /** spinner 换帧 / 秒数变化：运行中的视图重画摘要行（后台子 Agent 运行中也算）。 */
     tick() {
-        if (this.state === "running")
+        if (this.state === "running" || this.subagentState()?.status === "running")
             this.touch();
     }
+    /** 外部状态变了（子 Agent 事件）：重画。 */
+    refresh() {
+        this.touch();
+    }
+    subagentState() {
+        return this.toolName === "task" ? this.options.subagent?.(this.toolCallId) : undefined;
+    }
     touch() {
         this.version++;
         this.parent?.touch();
@@ -126,7 +136,12 @@ export class ToolView {
         if (this.cache && this.cache.width === width && this.cache.version === this.version) {
             return this.cache.lines;
         }
-        const lines = [this.header(width), this.summaryLine(width), ...this.body(width)].filter((line) => line !== undefined);
+        const lines = [
+            this.header(width),
+            this.summaryLine(width),
+            this.followLine(width),
+            ...this.body(width),
+        ].filter((line) => line !== undefined);
         this.cache = { width, version: this.version, lines };
         return lines;
     }
@@ -146,6 +161,12 @@ export class ToolView {
         if (this.state === "running" && this.awaiting) {
             return truncateToWidth(lead + theme.fg("dim", `${g.spinnerStatic} 等待确认`), width);
         }
+        const sub = this.subagentState();
+        if (this.state === "running" && sub !== undefined) {
+            const frame = this.options.spinner?.() ?? g.spinnerStatic;
+            const line = subagentLine(sub, theme, this.now());
+            return truncateToWidth(lead + theme.fg("accent", frame) + " " + line, width);
+        }
         if (this.state === "running") {
             const frame = this.options.spinner?.() ?? g.spinnerStatic;
             const elapsed = formatElapsed(this.now() - this.startedAt);
@@ -164,6 +185,15 @@ export class ToolView {
         }, theme);
         return truncateToWidth(lead + text, width);
     }
+    /** 后台子 Agent：结果摘要下一行跟随状态 `    ↳ t2 explore · 完成 2m · 7 轮 …`。 */
+    followLine(width) {
+        const sub = this.subagentState();
+        if (this.state === "running" || sub === undefined || !sub.background)
+            return undefined;
+        const { theme } = this.options;
+        const head = theme.fg("dim", `${theme.glyphs.queued} ${sub.taskId} `);
+        return truncateToWidth(BODY + head + subagentLine(sub, theme, this.now()), width);
+    }
     custom(render) {
         const tool = this.options.getTool?.(this.toolName);
         if (tool === undefined)

package/dist/modes/print/print-mode.d.ts

@@ -15,13 +15,18 @@
  * - 重试：text / json 格式在 stderr 打一行 `↻ 重试 n/m`（stream-json 里本来就有事件），等待期间不再无声。
  * - 无人值守：ask → deny（bootstrap 已按 print 设 unattended）。被拒的调用（`tool_execution_end`
  *   带 `denied`）在 stderr 汇总一行（工具 ×次数、首个原因、放行办法），json 结果带 `deniedTools`。
- * - `--max-turns N`：到达上限时若最后一条助手消息停在 toolUse（还有活没做完）→ stderr 一行、
- *   json 带 `maxTurnsReached`、退出码 1。
- * - 退出码：最终助手消息 `error / aborted` 或提示被拒 → 1；有工具调用被拒 → 7；SIGINT 130、
- *   SIGTERM 143（先 abort）。
+ * - [W5-H2] 预算（`--max-turns N` / `--max-cost USD` / config `limits.*`，agent/limits.ts）：到限
+ *   （会话发 `limit_reached`）→ stderr 一行、json 带 `limitReached{kind, value, limit}`（回合到限另带
+ *   `maxTurnsReached: true`）、退出码 8。
+ * - [W5-H2] plan 模式产出计划、`plan.unattended: stop`（缺省）没人审批：stderr 一行（计划文件与审批办法）、
+ *   json 带 `planPending{planId, version, filePath}`、退出码 9。
+ * - [W5-H2] `--image` / `@图片` 超限时按 config `images.resize` 缩放（缺省 auto）。
+ * - 退出码：最终助手消息 `error / aborted` 或提示被拒 → 1；有工具调用被拒 → 7；到达预算 → 8；
+ *   计划待审批 → 9；SIGINT 130、SIGTERM 143（先 abort）。
  */
 import type { CliIo, ModeContext } from "../../cli/deps.js";
 import type { Runtime } from "../../cli/runtime.js";
+import type { LimitReachedEvent, PlanProposedEvent } from "../../agent/types.js";
 export declare function joinPrompt(argument: string | undefined, piped: string): string;
 /** 等 stdin 多久后提示一次「正在等待」。 */
 export declare const STDIN_WAIT_HINT_MS = 3000;
@@ -34,6 +39,10 @@ export declare function stdinWaitMs(env: Readonly<Record<string, string | undefi
  */
 export declare function readPromptStdin(io: CliIo, prompt: string | undefined, mode: "auto" | "explicit" | "off", hintMs?: number): Promise<string>;
 export declare function runPrintMode(runtime: Runtime, context: ModeContext): Promise<number>;
+/** stderr 一行：计划已落盘待审批（-p 不替人批准）。 */
+export declare function describePlanPending(plan: PlanProposedEvent): string;
+/** stderr 一行：哪个预算到限。 */
+export declare function describeLimit(event: LimitReachedEvent): string;
 /** 被拒的一次工具调用（json 结果的 `deniedTools` 元素）。 */
 export interface DeniedTool {
     toolCallId: string;

package/dist/modes/print/print-mode.js

@@ -15,15 +15,20 @@
  * - 重试：text / json 格式在 stderr 打一行 `↻ 重试 n/m`（stream-json 里本来就有事件），等待期间不再无声。
  * - 无人值守：ask → deny（bootstrap 已按 print 设 unattended）。被拒的调用（`tool_execution_end`
  *   带 `denied`）在 stderr 汇总一行（工具 ×次数、首个原因、放行办法），json 结果带 `deniedTools`。
- * - `--max-turns N`：到达上限时若最后一条助手消息停在 toolUse（还有活没做完）→ stderr 一行、
- *   json 带 `maxTurnsReached`、退出码 1。
- * - 退出码：最终助手消息 `error / aborted` 或提示被拒 → 1；有工具调用被拒 → 7；SIGINT 130、
- *   SIGTERM 143（先 abort）。
+ * - [W5-H2] 预算（`--max-turns N` / `--max-cost USD` / config `limits.*`，agent/limits.ts）：到限
+ *   （会话发 `limit_reached`）→ stderr 一行、json 带 `limitReached{kind, value, limit}`（回合到限另带
+ *   `maxTurnsReached: true`）、退出码 8。
+ * - [W5-H2] plan 模式产出计划、`plan.unattended: stop`（缺省）没人审批：stderr 一行（计划文件与审批办法）、
+ *   json 带 `planPending{planId, version, filePath}`、退出码 9。
+ * - [W5-H2] `--image` / `@图片` 超限时按 config `images.resize` 缩放（缺省 auto）。
+ * - 退出码：最终助手消息 `error / aborted` 或提示被拒 → 1；有工具调用被拒 → 7；到达预算 → 8；
+ *   计划待审批 → 9；SIGINT 130、SIGTERM 143（先 abort）。
  */
 import { currentSession } from "../../cli/compose-session.js";
 import { ExitCode } from "../../cli/exit-codes.js";
 import { errorText, lastAssistant, onStdoutClosed, onTerminationSignals } from "../shared.js";
 import { toJsonLine, toWireEvent } from "./json-event.js";
+import { formatUsd } from "../../agent/limits.js";
 import { promptImages, sessionModel } from "../image-input.js";
 export function joinPrompt(argument, piped) {
     const parts = [argument ?? "", piped.replace(/\s+$/, "")].filter((p) => p.trim() !== "");
@@ -100,15 +105,24 @@ export async function runPrintMode(runtime, context) {
     }
     const session = currentSession(runtime);
     let images;
+    const resize = runtime.config.images?.resize;
     try {
-        images = await promptImages(prompt, context.args.images, io.cwd, sessionModel(runtime.providers, session));
+        images = await promptImages(prompt, context.args.images, io.cwd, sessionModel(runtime.providers, session), resize === undefined ? {} : { resize });
     }
     catch (error) {
         io.stderr(`ama: ${errorText(error)}\n`);
         return ExitCode.Usage;
     }
     const denied = [];
+    let limit;
+    let plan;
     const unsubscribe = session.subscribe((event) => {
+        if (event.type === "limit_reached")
+            limit ??= event;
+        else if (event.type === "plan_proposed")
+            plan = event;
+        else if (event.type === "plan_resolved" && event.planId === plan?.planId)
+            plan = undefined;
         if (event.type === "tool_execution_end" && event.denied === true)
             denied.push({
                 toolCallId: event.toolCallId,
@@ -144,9 +158,6 @@ export async function runPrintMode(runtime, context) {
     }
     const last = lastAssistant(session);
     const text = session.getLastAssistantText() ?? "";
-    // 回合上限在工具执行之后结束运行：最后一条助手消息停在 toolUse 即「没做完」
-    const maxTurns = context.args.maxTurns;
-    const turnsExhausted = maxTurns !== undefined && failure === undefined && last?.stopReason === "toolUse";
     const stopReason = failure !== undefined ? "error" : (last?.stopReason ?? "stop");
     if (format === "text") {
         // 部分模型在正文前多发空行：只去前导空行，保留首行缩进；json / stream-json 原样。
@@ -171,7 +182,21 @@ export async function runPrintMode(runtime, context) {
             cacheHitRate: stats.cacheHitRate,
             ...(stats.cache !== undefined ? { cache: stats.cache } : {}),
             ...(denied.length > 0 ? { deniedTools: denied } : {}),
-            ...(turnsExhausted ? { maxTurnsReached: true } : {}),
+            ...(plan !== undefined
+                ? {
+                    planPending: {
+                        planId: plan.planId,
+                        version: plan.version,
+                        ...(plan.filePath === undefined ? {} : { filePath: plan.filePath }),
+                    },
+                }
+                : {}),
+            ...(limit !== undefined
+                ? {
+                    limitReached: { kind: limit.kind, value: limit.value, limit: limit.limit },
+                    ...(limit.kind === "turns" ? { maxTurnsReached: true } : {}),
+                }
+                : {}),
             entries: session.entries,
         })}\n`);
     }
@@ -183,20 +208,39 @@ export async function runPrintMode(runtime, context) {
         io.stderr(`ama: ${failure}\n`);
         return ExitCode.RuntimeError;
     }
+    if (limit !== undefined) {
+        if (denied.length > 0)
+            io.stderr(`${describeDenied(denied)}\n`);
+        io.stderr(`${describeLimit(limit)}\n`);
+        return ExitCode.LimitReached;
+    }
     if (last?.stopReason === "error" || last?.stopReason === "aborted") {
         io.stderr(`ama: ${last.errorMessage ?? "模型调用失败"}\n`);
         return ExitCode.RuntimeError;
     }
     if (denied.length > 0)
         io.stderr(`${describeDenied(denied)}\n`);
-    if (turnsExhausted) {
-        io.stderr(`ama: 已达到 --max-turns ${maxTurns}，运行在完成前结束\n`);
-        return ExitCode.RuntimeError;
+    if (plan !== undefined) {
+        io.stderr(`${describePlanPending(plan)}\n`);
+        return ExitCode.PlanPending;
     }
     if (denied.length > 0)
         return ExitCode.ToolDenied;
     return ExitCode.Ok;
 }
+/** stderr 一行：计划已落盘待审批（-p 不替人批准）。 */
+export function describePlanPending(plan) {
+    const where = plan.filePath ?? plan.planId;
+    return (`ama: 计划 v${plan.version} 已落盘、待审批（未执行）：${where}；-p 不替人批准——` +
+        "在交互界面或 RPC plan_response 里审批，或设 plan.unattended: approve 让 -p 批准后接着执行");
+}
+/** stderr 一行：哪个预算到限。 */
+export function describeLimit(event) {
+    return event.kind === "turns"
+        ? `ama: 已达到回合上限 ${event.limit}（--max-turns / limits.maxTurns），运行在完成前结束`
+        : `ama: 已达到费用上限 ${formatUsd(event.limit)}（累计 ${formatUsd(event.value)}；` +
+            "--max-cost / limits.maxCostUsd），运行在完成前结束";
+}
 function textOf(event) {
     const content = event.result.content;
     const text = typeof content === "string"

package/dist/modes/rpc/commands.d.ts

@@ -8,7 +8,12 @@
  * - 审批：`RpcApprovals` 是 UI broker（`set_client_capabilities` 声明 approvals 后挂上），
  *   `permission_response` 按 requestId 作答；先到的回答暂存，等 broker 被问到时取用。
  * - 密钥不离开进程：`get_available_models` 只回 `hasKey` 与 `keySource`。
+ * - [W5-F] 计划：声明 `plans` 能力后计划审批交客户端（`plan_proposed` → `plan_response`），未声明按
+ *   `plan.unattended`；`approve_fresh` 在这里新建会话并以计划全文开新回合。`get_tasks / get_agents`
+ *   读 `RpcContext.tasks / agents`（W5-G 的注册表与发现结果；未装配时回空表）。
  */
+import type { AgentInfo } from "../../agents/types.js";
+import type { TaskRegistryView } from "../../tools/types.js";
 import type { AgentSession } from "../../agent/types.js";
 import type { Runtime } from "../../cli/runtime.js";
 import type { ApprovalBroker, ApprovalDecision, ApprovalRequest } from "../../permissions/types.js";
@@ -32,6 +37,10 @@ export interface RpcContext {
     onSessionChanged(next: AgentSession): void;
     /** 运行开始后提示命令自身的失败（应答已发出）。 */
     onBackgroundError(error: unknown): void;
+    /** [W5-F] `get_tasks`：子 Agent 任务注册表的只读视图（W5-G 装配；缺省回空表）。 */
+    tasks?(): TaskRegistryView | undefined;
+    /** [W5-F] `get_agents`：可用的子 Agent 类型与外部 Agent（W5-G / W5-E 装配；缺省回空表）。 */
+    agents?(): readonly AgentInfo[];
 }
 export type RpcHandlers = {
     [K in RpcCommandType]: (params: RpcCommandMap[K], ctx: RpcContext) => Promise<unknown>;