@armadra/agent 0.6.1 → 0.6.3

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

@@ -21,6 +21,10 @@
  * - [W5-H2] plan 模式产出计划、`plan.unattended: stop`（缺省）没人审批：stderr 一行（计划文件与审批办法）、
  *   json 带 `planPending{planId, version, filePath}`、退出码 9。
  * - [W5-H2] `--image` / `@图片` 超限时按 config `images.resize` 缩放（缺省 auto）。
+ * - [W7-B2] 后台子 Agent（显式 `background:true` 或 `subagents.background: always`）：主回合结束后若还有任务
+ *   在跑或通知待投递，stderr 一行提示并等它们结束、跑完通知回合再输出（最终文本 = 最后一条助手回复）；
+ *   受 `--max-turns` / `--max-cost` / `limits.*` 约束（到限即停止等待，退出码 8），SIGINT / SIGTERM 照常中止
+ *   （未结束的任务随会话关闭被停止）；json 结果带 `tasks`（同 `getStats().tasks`）。
  * - 退出码：最终助手消息 `error / aborted` 或提示被拒 → 1；有工具调用被拒 → 7；到达预算 → 8；
  *   计划待审批 → 9；SIGINT 130、SIGTERM 143（先 abort）。
  */
@@ -29,6 +33,7 @@ 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 { registryOf } from "../../agent/subagent-registry.js";
 import { promptImages, sessionModel } from "../image-input.js";
 import { msg } from "../../i18n/index.js";
 export function joinPrompt(argument, piped) {
@@ -118,9 +123,15 @@ export async function runPrintMode(runtime, context) {
     const denied = [];
     let limit;
     let plan;
+    let stopWaiting = () => undefined;
+    const stopped = new Promise((resolve) => {
+        stopWaiting = resolve;
+    });
     const unsubscribe = session.subscribe((event) => {
-        if (event.type === "limit_reached")
+        if (event.type === "limit_reached") {
             limit ??= event;
+            stopWaiting();
+        }
         else if (event.type === "plan_proposed")
             plan = event;
         else if (event.type === "plan_resolved" && event.planId === plan?.planId)
@@ -139,16 +150,25 @@ export async function runPrintMode(runtime, context) {
     let signalled;
     const offSignals = onTerminationSignals((code) => {
         signalled ??= code;
+        stopWaiting();
         void session.abort();
     });
     let stdoutClosed = false;
     const offEpipe = onStdoutClosed(() => {
         stdoutClosed = true;
+        stopWaiting();
         void session.abort();
     });
     let failure;
     try {
         await session.prompt(prompt, images.length > 0 ? { images } : {});
+        const ended = lastAssistant(session)?.stopReason;
+        if (signalled === undefined &&
+            !stdoutClosed &&
+            limit === undefined &&
+            ended !== "error" &&
+            ended !== "aborted")
+            await waitBackgroundTasks(session, stopped, io);
     }
     catch (error) {
         failure = errorText(error);
@@ -183,6 +203,7 @@ export async function runPrintMode(runtime, context) {
             cost: stats.cost,
             cacheHitRate: stats.cacheHitRate,
             ...(stats.cache !== undefined ? { cache: stats.cache } : {}),
+            ...(stats.tasks !== undefined ? { tasks: stats.tasks } : {}),
             ...(denied.length > 0 ? { deniedTools: denied } : {}),
             ...(plan !== undefined
                 ? {
@@ -230,6 +251,20 @@ export async function runPrintMode(runtime, context) {
         return ExitCode.ToolDenied;
     return ExitCode.Ok;
 }
+/**
+ * [W7-B2] 主回合结束后等后台任务与它们的通知回合（docs/agents-concurrency-plan.md §2.6、§6 Q5）。
+ * `settled()`（subagent-background.ts）等到没有运行中任务且通知投递链（含通知回合）结束；`stopped`：SIGINT /
+ * SIGTERM、stdout 关闭或预算到限时 resolve，立即停止等待。没有子 Agent 注册表时直接返回。
+ */
+export async function waitBackgroundTasks(session, stopped, io) {
+    const registry = registryOf(session.state.sessionId);
+    if (registry === undefined)
+        return;
+    const running = registry.list().filter((task) => task.status === "running").length;
+    if (running > 0)
+        io.stderr(msg().print.print.waitingTasks(running));
+    await Promise.race([registry.settled(), stopped]);
+}
 /** stderr 一行：计划已落盘待审批（-p 不替人批准）。 */
 export function describePlanPending(plan) {
     const where = plan.filePath ?? plan.planId;

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

@@ -1,5 +1,5 @@
 /**
- * RPC 命令分派表（设计 §13.2、src/rpc.ts 的 33 条命令）。[B6]
+ * RPC 命令分派表（设计 §13.2、src/rpc.ts 的命令表，现 44 条）。[B6]
  *
  * - 提示类（prompt / steer / follow_up）不等运行结束：会话开始运行（`before_agent_start` /
  *   `agent_start`）、入队或被处理后立刻应答 `{ disposition }`；运行中的进展走事件。
@@ -11,6 +11,7 @@
  * - [W5-F] 计划：声明 `plans` 能力后计划审批交客户端（`plan_proposed` → `plan_response`），未声明按
  *   `plan.unattended`；`approve_fresh` 在这里新建会话并以计划全文开新回合。`get_tasks / get_agents`
  *   读 `RpcContext.tasks / agents`（W5-G 的注册表与发现结果；未装配时回空表）。
+ * - [W7-B2] `background_task { taskId? }` → `{ backgrounded }`（`session.backgroundTask`，B1）。
  */
 import type { AgentInfo } from "../../agents/types.js";
 import type { TaskRegistryView } from "../../tools/types.js";

package/dist/modes/rpc/commands.js

@@ -1,5 +1,5 @@
 /**
- * RPC 命令分派表（设计 §13.2、src/rpc.ts 的 33 条命令）。[B6]
+ * RPC 命令分派表（设计 §13.2、src/rpc.ts 的命令表，现 44 条）。[B6]
  *
  * - 提示类（prompt / steer / follow_up）不等运行结束：会话开始运行（`before_agent_start` /
  *   `agent_start`）、入队或被处理后立刻应答 `{ disposition }`；运行中的进展走事件。
@@ -11,6 +11,7 @@
  * - [W5-F] 计划：声明 `plans` 能力后计划审批交客户端（`plan_proposed` → `plan_response`），未声明按
  *   `plan.unattended`；`approve_fresh` 在这里新建会话并以计划全文开新回合。`get_tasks / get_agents`
  *   读 `RpcContext.tasks / agents`（W5-G 的注册表与发现结果；未装配时回空表）。
+ * - [W7-B2] `background_task { taskId? }` → `{ backgrounded }`（`session.backgroundTask`，B1）。
  */
 import { formatModelRef } from "../../ai/providers/channels.js";
 import { AgentSessionImpl } from "../../agent/session.js";
@@ -312,5 +313,12 @@ export const handlers = {
     get_agents: async (_p, ctx) => ({ agents: [...(ctx.agents?.() ?? [])] }),
     // [W6-T2] 轨迹（docs/wave6-plan.md §2.6；分页 / 增量 / 脱敏见 trace/query.ts）
     get_trace: async (p, ctx) => sessionTrace(ctx.session(), p ?? {}),
+    // [W7-B2] 前台任务转后台：工具调用立即返回、任务继续，完成后照常通知
+    background_task: async (p, ctx) => {
+        const taskId = p?.taskId;
+        if (taskId !== undefined && typeof taskId !== "string")
+            throw new AmaError("invalid_arguments", msg().print.rpc.badTaskId);
+        return { backgrounded: ctx.session().backgroundTask(taskId) };
+    },
 };
 export const RPC_COMMAND_TYPES = Object.keys(handlers);

package/dist/rpc.d.ts

@@ -19,6 +19,9 @@
  * - [W6-C0] 第六波（docs/wave6-plan.md §2.6、§4.4）：命令 `get_trace`（参数 `RpcGetTraceParams`、返回
  *   `RpcW6Results`，W6-T2 实现，之前回 `not_implemented`）；事件 `quota_update`；`permission_request.context`
  *   可带 `toolCallId`；`keySource` 可为 `oauth`。`RPC_PROTOCOL_VERSION` 不变。
+ * - [W7-B2] 后台子 Agent（docs/agents-concurrency-plan.md §2.5）：命令 `background_task { taskId? }` →
+ *   `RpcW7Results`（无 taskId = 全部前台运行中任务；对已结束 / 已在后台的任务回空表）；事件
+ *   `subagent_background` 由 `SessionEvent` 派生。`RPC_PROTOCOL_VERSION` 不变。
  */
 import type { AssistantEvent, ImageBlock, ModelThinkingLevel, Usage } from "./ai/types.js";
 import type { PlanData, PlanDecisionKind, QueueMode, SessionEvent, TodoItemView } from "./agent/types.js";
@@ -139,6 +142,16 @@ export interface RpcCommandMap {
     get_tasks: NoParams;
     get_agents: NoParams;
     get_trace: RpcGetTraceParams;
+    background_task: {
+        taskId?: string;
+    };
+}
+/** [W7-B2] 第七波命令成功时的 `data` 形状。 */
+export interface RpcW7Results {
+    /** 实际转了后台的 taskId（含被打断的 `task_ctl wait`）；没有可转的为空表。 */
+    background_task: {
+        backgrounded: string[];
+    };
 }
 /** [W6-C0] `get_trace` 的参数。 */
 export interface RpcGetTraceParams {

package/dist/rpc.js

@@ -19,5 +19,8 @@
  * - [W6-C0] 第六波（docs/wave6-plan.md §2.6、§4.4）：命令 `get_trace`（参数 `RpcGetTraceParams`、返回
  *   `RpcW6Results`，W6-T2 实现，之前回 `not_implemented`）；事件 `quota_update`；`permission_request.context`
  *   可带 `toolCallId`；`keySource` 可为 `oauth`。`RPC_PROTOCOL_VERSION` 不变。
+ * - [W7-B2] 后台子 Agent（docs/agents-concurrency-plan.md §2.5）：命令 `background_task { taskId? }` →
+ *   `RpcW7Results`（无 taskId = 全部前台运行中任务；对已结束 / 已在后台的任务回空表）；事件
+ *   `subagent_background` 由 `SessionEvent` 派生。`RPC_PROTOCOL_VERSION` 不变。
  */
 export const RPC_PROTOCOL_VERSION = 1;

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

@@ -7,6 +7,8 @@
  *   与父一致，运行时拒绝；
  * - `wait` / `output` 是轮询类调用（`annotations.pollable`，重复调用检测豁免）；
  * - `send` = 续聊放后台：等价于 `task{taskId, prompt, background:true}`，完成后同样收到通知。
+ * - [W7-B1] `wait` 被转后台（`background()`，TUI `Ctrl+B` / RPC `background_task`）打断时立即返回固定
+ *   文案，要求模型不要再等。
  */
 import type { ToolDefinition } from "./types.js";
 export declare const TASK_CTL_TOOL = "task_ctl";

package/dist/tools/task-ctl.js

@@ -7,8 +7,10 @@
  *   与父一致，运行时拒绝；
  * - `wait` / `output` 是轮询类调用（`annotations.pollable`，重复调用检测豁免）；
  * - `send` = 续聊放后台：等价于 `task{taskId, prompt, background:true}`，完成后同样收到通知。
+ * - [W7-B1] `wait` 被转后台（`background()`，TUI `Ctrl+B` / RPC `background_task`）打断时立即返回固定
+ *   文案，要求模型不要再等。
  */
-import { capTaskText, formatTokens } from "../agents/result.js";
+import { capTaskText, formatTokens, waitDetachedText } 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;
@@ -96,7 +98,10 @@ export function createTaskCtlTool() {
                 }
                 case "wait": {
                     const timeout = Math.min(Math.max(input.timeoutMs ?? DEFAULT_WAIT_MS, 0), MAX_WAIT_MS);
-                    const result = await control.wait(taskId, timeout);
+                    const signal = control.detachSignal(taskId);
+                    const result = await control.wait(taskId, timeout, { signal });
+                    if (result === undefined && signal.aborted)
+                        return { content: waitDetachedText(taskId) };
                     if (result === undefined) {
                         const turns = control.get(taskId)?.turns ?? 0;
                         return {

package/dist/tools/task.d.ts

@@ -5,6 +5,8 @@
  * - `agent`：子 Agent 类型（内置 general / explore / plan、`.ama/agents/*.md`）或外部 Agent；缺省
  *   general。描述里列出可用类型（catalog 由 compose-agents.ts 经 `bindTaskAgents` 绑定；没绑定时
  *   只列内置类型）。
+ * - [W7-B1] 缺省前台 / 后台由 `subagents.background` 决定（交互 / RPC / ACP 后台，`-p` 前台），描述随之
+ *   二选一（`bindTaskBackground`）；前台任务可被 `background()` 转后台，工具立即以固定文案返回。
  * - `background`：立即返回 taskId，完成后父会话收到 `<task-notification>`；`taskId`：向已有子会话
  *   追加消息（续聊，忽略 agent / tools / model）；`isolation: "worktree"`：在独立 git worktree 里跑。
  * - **parallel**：同一回复里的多个 task 真并行（会话注册表的池限流，缺省 4）；与 sequential 工具
@@ -33,9 +35,18 @@ export interface TaskInput {
 /** 预留（并发上限在会话的任务注册表，见 agent/subagent-registry.ts）。 */
 export interface TaskToolOptions {
 }
+/** 缺省前台（`-p`、`subagents.background: never`）时的描述。 */
+export declare const FOREGROUND_DESCRIPTION: string;
+/** [W7-B1] 缺省后台（交互 / RPC / ACP，docs/agents-concurrency-plan.md §2.6）时的描述。 */
+export declare const BACKGROUND_DESCRIPTION: string;
 /** 描述里类型清单的标题（清单本身另有 400 token 预算，见 agents/catalog.ts）。 */
 export declare const TASK_AGENTS_HEADING = "\nAgents:\n";
 /** 组装根把会话的类型目录绑到 task 工具上（描述里的类型清单）。 */
 export declare function bindTaskAgents(tool: ToolDefinition | undefined, catalog: AgentCatalog): void;
+/**
+ * [W7-B1] 组装根把本进程的缺省前台 / 后台（`subagents.background` 按运行模式解析后）绑到 task 工具：
+ * 决定描述用哪一版。会话内不变（缓存前缀稳定）；没绑定按缺省前台。
+ */
+export declare function bindTaskBackground(tool: ToolDefinition | undefined, background: boolean): void;
 export declare function buildSubagentRequest(input: TaskInput, ctx: ToolContext): SubagentRequest | string;
 export declare function createTaskTool(_options?: TaskToolOptions): ToolDefinition<TaskInput>;

package/dist/tools/task.js

@@ -5,6 +5,8 @@
  * - `agent`：子 Agent 类型（内置 general / explore / plan、`.ama/agents/*.md`）或外部 Agent；缺省
  *   general。描述里列出可用类型（catalog 由 compose-agents.ts 经 `bindTaskAgents` 绑定；没绑定时
  *   只列内置类型）。
+ * - [W7-B1] 缺省前台 / 后台由 `subagents.background` 决定（交互 / RPC / ACP 后台，`-p` 前台），描述随之
+ *   二选一（`bindTaskBackground`）；前台任务可被 `background()` 转后台，工具立即以固定文案返回。
  * - `background`：立即返回 taskId，完成后父会话收到 `<task-notification>`；`taskId`：向已有子会话
  *   追加消息（续聊，忽略 agent / tools / model）；`isolation: "worktree"`：在独立 git worktree 里跑。
  * - **parallel**：同一回复里的多个 task 真并行（会话注册表的池限流，缺省 4）；与 sequential 工具
@@ -24,17 +26,32 @@ const THINKING = [
     "high",
     "xhigh",
 ];
-const BASE_DESCRIPTION = "Delegate to a sub-agent (fresh context; give full instructions). Returns its final report. " +
+/** 缺省前台（`-p`、`subagents.background: never`）时的描述。 */
+export const FOREGROUND_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.";
+/** [W7-B1] 缺省后台（交互 / RPC / ACP，docs/agents-concurrency-plan.md §2.6）时的描述。 */
+export const BACKGROUND_DESCRIPTION = "Delegate to a sub-agent (fresh context; give full instructions). Runs in the background by " +
+    "default: returns a taskId; a <task-notification> follows when done, so keep working. " +
+    "background:false if your next step needs the result. taskId: continue a task. Tasks in one " +
+    "reply run in parallel; writers use isolation worktree.";
 /** 描述里类型清单的标题（清单本身另有 400 token 预算，见 agents/catalog.ts）。 */
 export const TASK_AGENTS_HEADING = "\nAgents:\n";
 const catalogs = new WeakMap();
+const backgrounds = new WeakMap();
 /** 组装根把会话的类型目录绑到 task 工具上（描述里的类型清单）。 */
 export function bindTaskAgents(tool, catalog) {
     if (tool !== undefined)
         catalogs.set(tool, catalog);
 }
+/**
+ * [W7-B1] 组装根把本进程的缺省前台 / 后台（`subagents.background` 按运行模式解析后）绑到 task 工具：
+ * 决定描述用哪一版。会话内不变（缓存前缀稳定）；没绑定按缺省前台。
+ */
+export function bindTaskBackground(tool, background) {
+    if (tool !== undefined)
+        backgrounds.set(tool, background);
+}
 function fail(message) {
     return { content: message, isError: true };
 }
@@ -87,7 +104,8 @@ export function createTaskTool(_options = {}) {
         label: "Task",
         get description() {
             const catalog = catalogs.get(tool) ?? new AgentCatalog();
-            return `${BASE_DESCRIPTION}${TASK_AGENTS_HEADING}${catalog.describe()}`;
+            const base = backgrounds.get(tool) === true ? BACKGROUND_DESCRIPTION : FOREGROUND_DESCRIPTION;
+            return `${base}${TASK_AGENTS_HEADING}${catalog.describe()}`;
         },
         parameters: {
             type: "object",

package/dist/tui/components/editor.d.ts

@@ -88,6 +88,8 @@ export declare class Editor implements Component, Focusable {
         col: number;
     };
     get isCompletionOpen(): boolean;
+    /** 正在用 ↑↓ 浏览输入历史（编辑后即退出）。 */
+    get isBrowsingHistory(): boolean;
     getHistory(): readonly string[];
     setHistory(entries: readonly string[]): void;
     addToHistory(text: string): void;

package/dist/tui/components/editor.js

@@ -88,6 +88,10 @@ export class Editor {
     get isCompletionOpen() {
         return this.completion !== null;
     }
+    /** 正在用 ↑↓ 浏览输入历史（编辑后即退出）。 */
+    get isBrowsingHistory() {
+        return this.historyIndex !== -1;
+    }
     getHistory() {
         return this.history;
     }

package/dist/tui/components/loader.d.ts

@@ -2,7 +2,8 @@
  * 运行指示（设计 §12.1、§12.6；终端界面视觉设计 v1 §3.7）。[B4]
  *
  * 一行 `⠋ 动词 · 已用时 · 附加项…`：spinner `accent`、动词正文色、其余 `dim`，以 ` · ` 连接。
- * - `setVerb(verb, extras, { elapsed })` 换动词（思考中 / 回复中 / 运行 bash / 等待确认……）；
+ * - `setVerb(verb, extras, { elapsed, optional })` 换动词（思考中 / 回复中 / 运行 bash / 等待确认……）；
+ *   `optional` 是排在附加项之后的可丢弃项（按键提示），整行放不下时从后往前丢，而不是被截断；
  *   `setMessage(text)` 是只换动词的旧接口。
  * - 帧取 `theme.glyphs.spinner`（Unicode 10 帧 80 ms、ASCII 4 帧 250 ms）；`frame` 暴露当前帧字形，
  *   `onFrame` 让别的组件（运行中的工具摘要行）与 Loader 同帧换字，保证一帧只多改一行。
@@ -27,6 +28,8 @@ export interface LoaderOptions {
 export interface LoaderVerbOptions {
     /** 本动词是否显示已用时（缺省跟随 `showElapsed`）。 */
     elapsed?: boolean;
+    /** 可丢弃的附加项：宽度不够时从后往前整项丢掉（缺省没有）。 */
+    optional?: readonly string[];
 }
 export declare function formatElapsed(ms: number): string;
 export declare class Loader implements Component {
@@ -37,6 +40,7 @@ export declare class Loader implements Component {
     private startedAt;
     private verb;
     private extras;
+    private optional;
     private verbElapsed;
     private lastElapsed;
     private readonly listeners;

package/dist/tui/components/loader.js

@@ -2,17 +2,21 @@
  * 运行指示（设计 §12.1、§12.6；终端界面视觉设计 v1 §3.7）。[B4]
  *
  * 一行 `⠋ 动词 · 已用时 · 附加项…`：spinner `accent`、动词正文色、其余 `dim`，以 ` · ` 连接。
- * - `setVerb(verb, extras, { elapsed })` 换动词（思考中 / 回复中 / 运行 bash / 等待确认……）；
+ * - `setVerb(verb, extras, { elapsed, optional })` 换动词（思考中 / 回复中 / 运行 bash / 等待确认……）；
+ *   `optional` 是排在附加项之后的可丢弃项（按键提示），整行放不下时从后往前丢，而不是被截断；
  *   `setMessage(text)` 是只换动词的旧接口。
  * - 帧取 `theme.glyphs.spinner`（Unicode 10 帧 80 ms、ASCII 4 帧 250 ms）；`frame` 暴露当前帧字形，
  *   `onFrame` 让别的组件（运行中的工具摘要行）与 Loader 同帧换字，保证一帧只多改一行。
  * - `animation: false`：spinner 固定为 `glyphs.spinnerStatic`，定时器每秒一次，已用时变了才请求重绘。
  * - `stop()` 后不再触发渲染。时钟可注入便于测试。
  */
-import { truncateToWidth } from "../ansi.js";
+import { truncateToWidth, visibleWidth } from "../ansi.js";
 import { UNICODE_GLYPHS } from "../glyphs.js";
 /** Unicode 帧表（兼容旧导出；实际帧取 `theme.glyphs.spinner`）。 */
 export const LOADER_FRAMES = UNICODE_GLYPHS.spinner;
+function sameList(a, b) {
+    return a.length === b.length && a.every((e, i) => e === b[i]);
+}
 export function formatElapsed(ms) {
     const total = Math.max(0, Math.floor(ms / 1000));
     if (total < 60)
@@ -29,6 +33,7 @@ export class Loader {
     startedAt;
     verb;
     extras = [];
+    optional = [];
     verbElapsed;
     lastElapsed = "";
     listeners = new Set();
@@ -65,12 +70,13 @@ export class Loader {
     setVerb(verb, extras = [], options = {}) {
         const same = verb === this.verb &&
             options.elapsed === this.verbElapsed &&
-            extras.length === this.extras.length &&
-            extras.every((e, i) => e === this.extras[i]);
+            sameList(extras, this.extras) &&
+            sameList(options.optional ?? [], this.optional);
         if (same)
             return;
         this.verb = verb;
         this.extras = [...extras];
+        this.optional = [...(options.optional ?? [])];
         this.verbElapsed = options.elapsed;
         this.requestRender();
     }
@@ -142,7 +148,14 @@ export class Loader {
         for (const extra of this.extras)
             parts.push(dim(extra));
         const spinner = theme ? theme.fg("accent", this.frame) : this.frame;
-        return [truncateToWidth(`${spinner} ${parts.join(dim(" · "))}`, width)];
+        const line = (items) => `${spinner} ${items.join(dim(" · "))}`;
+        for (const extra of this.optional) {
+            const next = [...parts, dim(extra)];
+            if (visibleWidth(line(next)) > width)
+                break;
+            parts.push(dim(extra));
+        }
+        return [truncateToWidth(line(parts), width)];
     }
     invalidate() { }
 }

package/dist/tui/keybindings.d.ts

@@ -45,10 +45,15 @@ export declare const DEFAULT_KEYBINDINGS: {
     /** [W5-U] 粘贴剪贴板图片（写进数据目录，输入框插入 `@路径`）。 */
     readonly "app.paste.image": readonly ["ctrl+v"];
     /**
-     * [W6-A] 进入 Agent 栏：只在输入为空时生效（有字时 `Ctrl+B` 仍是光标左移、`↓` 仍是下移 / 历史）；
-     * `↓` 另要求栏可见。tmux 缺省前缀吃掉 `Ctrl+B` 时用 `↓`。
+     * [W6-A / W7-A] 进入 Agent 栏：输入为空、补全未开、有子 Agent 任务即可（不要求栏可见）；有字时 `↓` 仍是
+     * 下移 / 历史，并给一次提示。`Ctrl+B` 不再进栏（tmux 缺省前缀会吃掉它），留给 `app.tasks.background`。
      */
-    readonly "app.agents.focus": readonly ["ctrl+b", "down"];
+    readonly "app.agents.focus": readonly ["down"];
+    /**
+     * [W7-C] 有阻塞中的前台子 Agent 任务（或 `task_ctl wait`）时全部转后台，不看输入框；没有时落回编辑器
+     * （`tui.editor.cursorLeft` 的 `ctrl+b`）。tmux 里按 `C-b C-b` 透传。
+     */
+    readonly "app.tasks.background": readonly ["ctrl+b"];
 };
 export type ActionId = keyof typeof DEFAULT_KEYBINDINGS;
 export type KeybindingOverrides = Partial<Record<ActionId, readonly string[]>>;

package/dist/tui/keybindings.js

@@ -48,10 +48,15 @@ export const DEFAULT_KEYBINDINGS = {
     /** [W5-U] 粘贴剪贴板图片（写进数据目录，输入框插入 `@路径`）。 */
     "app.paste.image": ["ctrl+v"],
     /**
-     * [W6-A] 进入 Agent 栏：只在输入为空时生效（有字时 `Ctrl+B` 仍是光标左移、`↓` 仍是下移 / 历史）；
-     * `↓` 另要求栏可见。tmux 缺省前缀吃掉 `Ctrl+B` 时用 `↓`。
+     * [W6-A / W7-A] 进入 Agent 栏：输入为空、补全未开、有子 Agent 任务即可（不要求栏可见）；有字时 `↓` 仍是
+     * 下移 / 历史，并给一次提示。`Ctrl+B` 不再进栏（tmux 缺省前缀会吃掉它），留给 `app.tasks.background`。
      */
-    "app.agents.focus": ["ctrl+b", "down"],
+    "app.agents.focus": ["down"],
+    /**
+     * [W7-C] 有阻塞中的前台子 Agent 任务（或 `task_ctl wait`）时全部转后台，不看输入框；没有时落回编辑器
+     * （`tui.editor.cursorLeft` 的 `ctrl+b`）。tmux 里按 `C-b C-b` 透传。
+     */
+    "app.tasks.background": ["ctrl+b"],
 };
 export function isActionId(id) {
     return Object.prototype.hasOwnProperty.call(DEFAULT_KEYBINDINGS, id);

package/docs/agents.md

@@ -38,7 +38,7 @@ model: fast # inherit（缺省）| fast | strong（models.aliases）| provider/m
 thinking: low
 max-turns: 20 # 缺省 30
 isolation: none # none（缺省）| worktree
-background: false
+background: false # 不写 = 按 config subagents.background
 runner: ama # ama（缺省）| claude | codex | acp:<程序>
 ---
 
@@ -60,16 +60,16 @@ runner: ama # ama（缺省）| claude | codex | acp:<程序>
 
 ### `task` 参数
 
-| 参数                                             | 说明                                                                       |
-| ------------------------------------------------ | -------------------------------------------------------------------------- |
-| `prompt`                                         | 必填，完整的任务说明                                                       |
-| `agent`                                          | 类型名，缺省 `general`；也可以是外部 Agent（见「外部 Agent」节）           |
-| `description`                                    | 显示用的短标签                                                             |
-| `background`                                     | `true`：立即返回 `taskId`，完成后父会话收到通知；缺省取类型的 `background` |
-| `taskId`                                         | 续聊：向已有任务的子会话追加一条消息（忽略 `agent` / `tools` / `model`）   |
-| `isolation`                                      | `worktree`：在独立 git worktree 里运行                                     |
-| `budgetUsd`                                      | 外部 Agent 的美元预算                                                      |
-| `tools` / `model` / `thinkingLevel` / `maxTurns` | 保留的高级参数（描述里不展开）                                             |
+| 参数                                             | 说明                                                                                                                                                     |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `prompt`                                         | 必填，完整的任务说明                                                                                                                                     |
+| `agent`                                          | 类型名，缺省 `general`；也可以是外部 Agent（见「外部 Agent」节）                                                                                         |
+| `description`                                    | 显示用的短标签                                                                                                                                           |
+| `background`                                     | `true`：立即返回 `taskId`，完成后父会话收到通知；`false`：等结果。缺省取类型的 `background`，类型没写时按 `subagents.background`（见下文「前台与后台」） |
+| `taskId`                                         | 续聊：向已有任务的子会话追加一条消息（忽略 `agent` / `tools` / `model`）                                                                                 |
+| `isolation`                                      | `worktree`：在独立 git worktree 里运行                                                                                                                   |
+| `budgetUsd`                                      | 外部 Agent 的美元预算                                                                                                                                    |
+| `tools` / `model` / `thinkingLevel` / `maxTurns` | 保留的高级参数（描述里不展开）                                                                                                                           |
 
 同一条回复里的多个 `task` **并行**执行，由会话的任务池限流（`subagents.maxConcurrent`，缺省 4）；排队超过
 `subagents.maxPending`（缺省 16）直接报错，提示模型不要重试。并行且会写文件的任务请用 `isolation: "worktree"`。
@@ -79,9 +79,31 @@ runner: ama # ama（缺省）| claude | codex | acp:<程序>
 全文写到会话目录的 `outputs/<会话 id>-<taskId>.md`（内存会话写到系统临时目录）。轮数用尽且最后一步停在工具结果上时，
 ama 以「不允许调用工具」再跑一轮要最终报告，结果前加 `[Turn limit reached; …]`，状态 `max_turns`。
 
+### 前台与后台
+
+是否后台的优先级：调用参数 `background` > 类型定义的 `background:` > config `subagents.background`。
+`subagents.background` 缺省 `auto`：交互界面、RPC、ACP 下后台（模型需要结果才写 `background: false`），`-p` 下前台；
+`always` / `never` 固定。两种缺省对应两版 `task` 工具描述，会话内不变，不影响缓存前缀稳定。
+
+前台任务运行中可以转后台，任务不中断，`task` 工具调用立即返回一段固定英文结果（含 `taskId` 与输出文件），完成后照常发
+`<task-notification>`：
+
+- 交互界面：`Ctrl+B` / `/tasks bg [id]` / Agent 栏里按 `b`（见 [tui.md](tui.md)「子 Agent」）；
+- RPC：`background_task { taskId? }`（[rpc.md](rpc.md)），SDK：`session.backgroundTask(taskId?)`，返回实际转了的 `taskId`；
+  不给 `taskId` 时转全部前台运行中任务，正在 `task_ctl wait` 的等待也一并打断；
+- 自动：`subagents.autoBackgroundAfterMs` 大于 0 时，前台任务运行超过该毫秒数自动转后台（缺省 0 关闭）。
+
+转后台发 `subagent_background { taskId, parentToolCallId, reason }` 事件（`user` / `timeout` / `host`）。
+父会话 `Esc` 中断只连带中止仍在前台的任务，后台任务不受影响；停止后台任务用 `task_ctl stop` 或 `/tasks stop`。
+
+`-p` 下（缺省前台）显式 `background: true` 仍生效：主回合结束后若还有任务在跑或通知待投递，stderr 一行提示，等它们结束、
+跑完通知回合再输出，输出的文本是最后一条助手回复；等待受 `--max-turns` / `--max-cost` / `limits.*` 约束（到限停止等待、
+退出码 8），`Ctrl+C` / SIGTERM 照常中止（未结束的任务随会话关闭被停止，退出码 130 / 143）。`--output-format json` 的结果带
+`tasks`（同 `getStats().tasks`）。
+
 ### 后台任务与 `task_ctl`
 
-`background: true` 立即返回 `taskId` 与输出文件路径。任务完成后，ama 在父会话空闲时投递一条 user 消息（`origin: "task"`）
+后台任务立即返回 `taskId` 与输出文件路径。任务完成后，ama 在父会话空闲时投递一条 user 消息（`origin: "task"`）
 并开始新回合；父正忙则等这一轮结束再投递，不打断。多条通知按完成顺序到达：
 
 ```text
@@ -95,13 +117,13 @@ ama 以「不允许调用工具」再跑一轮要最终报告，结果前加 `[T
 
 `task_ctl` 的动作：
 
-| `action` | 说明                                                                               |
-| -------- | ---------------------------------------------------------------------------------- |
-| `list`   | 列出本会话的任务：编号、类型、状态、轮数、token、耗时、是否后台、描述              |
-| `wait`   | 等任务结束（`timeoutMs` 缺省 30 000，最多 600 000）；超时说明仍在运行              |
-| `stop`   | 停止任务，返回终态                                                                 |
-| `output` | 运行中返回已有输出，结束后返回最终文本（同样有 50 KB 上限）                        |
-| `send`   | 向任务追加一条消息并放到后台运行（等价于 `task{taskId, prompt, background:true}`） |
+| `action` | 说明                                                                                                    |
+| -------- | ------------------------------------------------------------------------------------------------------- |
+| `list`   | 列出本会话的任务：编号、类型、状态、轮数、token、耗时、是否后台、描述                                   |
+| `wait`   | 等任务结束（`timeoutMs` 缺省 30 000，最多 600 000）；超时说明仍在运行；被转后台时立即返回并说明不必再等 |
+| `stop`   | 停止任务，返回终态                                                                                      |
+| `output` | 运行中返回已有输出，结束后返回最终文本（同样有 50 KB 上限）                                             |
+| `send`   | 向任务追加一条消息并放到后台运行（等价于 `task{taskId, prompt, background:true}`）                      |
 
 ### 续聊、保留与 resume
 
@@ -122,20 +144,22 @@ worktree 里的编辑不记进父会话的检查点。注意：worktree 不共
 
 ### 事件与统计
 
-RPC / SDK 事件 `subagent_start` / `subagent_update` / `subagent_end` 见 [rpc.md](rpc.md)「子 Agent 事件」。
+RPC / SDK 事件 `subagent_start` / `subagent_update` / `subagent_background` / `subagent_end` 见 [rpc.md](rpc.md)「子 Agent 事件」。
 `getStats().tasks` 给出任务总数、运行中数量与按状态的计数；子会话的缓存命中与重计费仍汇总在 `cache.subagents`。
 RPC `get_tasks` / `get_agents` 返回任务快照与可用类型（来源、定义文件路径）。交互界面的 `/tasks`、`/agents` 与 task 工具行的折叠显示见 [tui.md](tui.md)「子 Agent」。
 
 ### 配置
 
-| 键                                | 说明                                        |
-| --------------------------------- | ------------------------------------------- |
-| `subagents.maxConcurrent`         | 同时运行的子 Agent，缺省 4                  |
-| `subagents.maxPending`            | 排队上限，缺省 16                           |
-| `subagents.defaultModel`          | 子 Agent 缺省模型，不设继承父会话           |
-| `agents.dirs`                     | 追加的定义目录                              |
-| `agents.<类型>.model`             | 某个类型的模型（如让 `explore` 用便宜模型） |
-| `models.aliases.fast` / `.strong` | 定义文件里 `model: fast / strong` 的映射    |
+| 键                                | 说明                                                                             |
+| --------------------------------- | -------------------------------------------------------------------------------- |
+| `subagents.maxConcurrent`         | 同时运行的子 Agent，缺省 4                                                       |
+| `subagents.maxPending`            | 排队上限，缺省 16                                                                |
+| `subagents.defaultModel`          | 子 Agent 缺省模型，不设继承父会话                                                |
+| `subagents.background`            | `auto`（缺省）\| `always` \| `never`，见「前台与后台」；用户 / 项目 / 宿主级都认 |
+| `subagents.autoBackgroundAfterMs` | 前台任务运行超过该毫秒数自动转后台，缺省 0（关闭）；用户 / 项目级都认            |
+| `agents.dirs`                     | 追加的定义目录                                                                   |
+| `agents.<类型>.model`             | 某个类型的模型（如让 `explore` 用便宜模型）                                      |
+| `models.aliases.fast` / `.strong` | 定义文件里 `model: fast / strong` 的映射                                         |
 
 ### 限制
 

package/docs/en/host-api.md

@@ -164,4 +164,8 @@ Return `"warm"` / `"stop"` (a Promise is fine). `"stop"` skips the request and s
 
 ## Embedding in Armadra
 
-Armadra starts ama with a profile: `ama --profile <path>`. The profile's `host` points to its adapter (`ama-armadra.cjs`) and also carries instructions, skillDirs, hooksFile, authFile, sessionDir and `trustProject`. The adapter returns `undefined` when `ARMADRA_NODE_ID` is missing, so the same profile behaves as plain ama outside the canvas. Contract details are in [docs/design/coordinator-agent.md](https://github.com/yovinchen/Armadra/blob/main/docs/design/coordinator-agent.md) in the Armadra repository.
+Armadra starts ama with a profile: `ama --profile <path>`. The profile's `host` points to its adapter (`ama-armadra.cjs`) and also carries instructions, skillDirs, hooksFile, authFile, sessionDir and `trustProject`. The adapter returns `undefined` when `ARMADRA_NODE_ID` is missing, so the same profile behaves as plain ama outside the canvas.
+
+Interface defaults with a profile: `ui.quietStartup: "header"` and `ui.statusLine: "compact"` (the last line is the status bar, which the host parses by `·`). The agent bar (`ui.agentBar`) is no longer off by default; it is `auto` as in a standalone terminal. A host that shows sub-tasks itself and does not want the bar writes `{ "ui": { "agentBar": "off" } }` into the config file its profile's `config` points to.
+
+Contract details are in [docs/design/coordinator-agent.md](https://github.com/yovinchen/Armadra/blob/main/docs/design/coordinator-agent.md) in the Armadra repository.