@tencent-ai/agent-harness 0.2.0-beta.7 → 0.2.0-beta.8

package/cli/dist-server/types/node/agent-task/agent-task.d.ts

@@ -0,0 +1,405 @@
+import { AgentManager, Session, SessionManager, SessionRunStateMachine } from '../../vendor/cbc-core/node/index.js';
+import { ProductManager } from '../../workspace/product/lib/common/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { Subscription } from 'rxjs';
+import { CustomCommandRenderer } from '../command';
+import { ConsoleManager } from '../console';
+import { ScopedHookRegistry } from '../hooks/hook-protocol';
+import { AgentScopedMcpManager } from '../mcp/mcp-protocol';
+import { SettingsManager } from '../settings';
+import { AgentTask, AgentTaskExecutionConfig, AgentTaskExecutionResult, type AgentTaskInvocationIdentity, AgentTaskOutputFileManager, ToolCallRecord } from './agent-task-protocol';
+export declare function restoreResumedSubAgentMeta(session: Session, options: {
+    mainSession: Session;
+    taskId: string;
+    taskName: string;
+    agentName?: string;
+    teamContext?: AgentTaskExecutionConfig['teamContext'];
+}): void;
+export declare function bindSubagentInvocationIdentity(session: Session, mainSession: Session, identity?: AgentTaskInvocationIdentity): AgentTaskInvocationIdentity;
+/**
+ * AgentTask class - unified agent task execution engine
+ * Encapsulates all agent task execution logic (both sync and async)
+ * Implements AgentTask interface for lifecycle management
+ */
+export declare class AgentTaskImpl implements AgentTask {
+    /**
+     * How long to wait for an interceptor-announced retry run to actually start
+     * before giving up and delivering the output we already have (#85908).
+     *
+     * This bounds STARTUP only — once the run is observed, we wait for it without
+     * any time limit, so long-running sub-agent turns are never cut short. The
+     * window exists purely so that an announced-but-never-started retry degrades
+     * to the pre-fix behaviour instead of hanging the parent's Agent tool.
+     */
+    private static readonly RETRY_START_GRACE_MS;
+    readonly id: string;
+    readonly startTime: number;
+    endTime?: number;
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | 'killed';
+    abortController: AbortController;
+    title: string;
+    description?: string;
+    prompt?: string;
+    agentType?: string;
+    agentIsolation?: 'worktree';
+    memberName?: string;
+    isTeamMember?: boolean;
+    isBackground?: boolean;
+    isWorkflowTask?: boolean;
+    retainInAgentTree?: boolean;
+    teamContext?: {
+        teamName: string;
+        memberName: string;
+        teamMembers: string[];
+        color?: string;
+    };
+    response?: string;
+    result?: string;
+    error?: string;
+    sessionResultSubscription?: Subscription;
+    toolCallHistory: ToolCallRecord[];
+    tokenUsage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        lastContextWindow?: number;
+    };
+    sessionId?: string;
+    mainSessionId?: string;
+    kill(): Promise<void>;
+    cancel(): Promise<void>;
+    private config;
+    private mainSession;
+    private subAgentSession;
+    private agent;
+    /** setupPhase 解析出的 run 名（含 fork 语义）；setupSubAgentSession 复用，避免二次解析漂移。 */
+    private resolvedRunAgentName?;
+    private executionResult?;
+    private invocationIdentity?;
+    private subagentStatusPublication?;
+    private subagentStartPublication?;
+    private subagentStartedPublished;
+    private pendingSubagentTerminalStatus?;
+    private subagentInvocationAfterId?;
+    private isDetached;
+    private subagentStopHookFired;
+    private cleanupFinished;
+    private executionPromise?;
+    private subAgentSessionReleaseRequested;
+    private subAgentRuntimeReleased;
+    private executionSlot?;
+    protected readonly productManager: ProductManager;
+    protected readonly consoleManager: ConsoleManager;
+    protected readonly taskOutputManager?: AgentTaskOutputFileManager;
+    protected readonly logger: Logger;
+    protected readonly settingsManager: SettingsManager;
+    protected readonly scopedHookRegistry: ScopedHookRegistry;
+    protected readonly agentScopedMcpManager: AgentScopedMcpManager;
+    protected readonly customCommandRenderer: CustomCommandRenderer;
+    protected readonly stateMachine: SessionRunStateMachine;
+    private subscriptions;
+    private mainAbortListener?;
+    private mainAbortSignal?;
+    private agentEndListener?;
+    private hasFixedPermissionMode;
+    private eventEmitter;
+    constructor();
+    /**
+     * Initialize agent task with configuration
+     */
+    init(config: AgentTaskExecutionConfig): void;
+    reserveExecutionSlot(): void;
+    getExecutionConfig(): AgentTaskExecutionConfig | undefined;
+    releaseExecutionSlot(): void;
+    /**
+     * Main execute method - unified agent task execution flow with network retry support
+     */
+    execute(): Promise<AgentTaskExecutionResult>;
+    whenSettled(): Promise<void>;
+    private executeTask;
+    /**
+     * Fork child composition: session mainKey → settings default → product default.
+     * Does not follow `session.agentName` / `@agent` telemetry, so a temporary
+     * mention switch cannot leak into the child's standing tools.
+     * 也不吃 lastUsed：空白父会话未盖章时 fork 必须跟父身份 / 设为默认，不能变成 chip 记忆。
+     */
+    private resolveForkParentAgent;
+    /**
+     * Phase 1: One-time setup - session, subscriptions, etc.
+     * This only runs once, not repeated during retries
+     */
+    private setupPhase;
+    /**
+     * 应用 agent 级 reasoning 覆盖：
+     *   - `thinkingEnabled: false` → 该 sub agent 运行时强制关闭 thinking（对齐 Claude thinkingEnabled）；
+     *   - `effort: <level>`        → 该 sub agent 使用指定 reasoning 强度（对齐 Claude subagent effort）。
+     *
+     * 复用 `SessionManager.setOverrideThinking`（session 级、内存、不持久化），
+     * 由 `ModelConfigAgentRunInterceptor` 在真实请求时消费，优先级最高。
+     * 不改 interceptor / model-provider，不影响主 agent。
+     *
+     * 作用域：
+     *   - `effort`：对所有 sub agent（含 custom / plugin）生效，对齐 Claude subagent effort；
+     *   - `thinkingEnabled: false`：仅对内置 sub agent 生效——custom / plugin agent（带
+     *     CUSTOM_AGENT_TAG）被排除，避免外部来源绕过模型 `onlyReasoning` 的产品语义
+     *     （与 admin-trusted 判定同思路）。
+     *
+     * 关闭与 effort 互斥，关闭优先。非法 effort 值静默忽略（继承默认，不报错）。
+     */
+    private applyAgentReasoningOverride;
+    /**
+     * 将 agent frontmatter `skills:` 列出的 skill 完整内容作为 isMeta user message
+     * 预加载到 subAgentSession.history，让 subagent 启动前模型就能看到这些 skill 的内容。
+     *
+     * 对齐 Claude Code `runAgent.ts:577-646` 的 initialMessages preload 语义。
+     * 和 tool description 里"给模型看的 skill 列表过滤"是两个独立维度——preload 提供内容，
+     * 过滤列表只影响模型能感知到哪些 skill 可用，二者共存。
+     *
+     * Name 解析策略（三档 fallback，对齐 CC resolveSkillName）：
+     *   1. exact match on skill.name
+     *   2. 如果 agent 来自插件且 frontmatter 写裸名，尝试 `${pluginName}:${name}`
+     *   3. 后缀匹配 skill.name.endsWith(`:${name}`)（多个命中取第一个并 warn）
+     *
+     * 失败处理：warn + skip。非 prompt-based skill 也 skip（当前 cbc 所有 skill 都是
+     * prompt-based，这里留预留判断与 CC 对齐）。
+     */
+    private preloadFrontmatterSkills;
+    /**
+     * Build an isMeta + skipRun user-message history item for preloaded
+     * subagent context. isMeta hides it from SDK resume replay / user view;
+     * skipRun keeps it as pass-through context that never triggers a model
+     * run. See preloadFrontmatterSkills for the 内存 == jsonl invariant that
+     * requires these to be written via sessionManager.addHistory.
+     */
+    private buildPreloadItem;
+    /**
+     * Build the failure reminder item (model needs to see that a *requested*
+     * skill is NOT in its context — otherwise the "agent has skills
+     * configured but doesn't know them" phantom bug).
+     */
+    private buildPreloadFailureItem;
+    /**
+     * 3 档 fallback 解析 skill 名称（对齐 CC runAgent.ts:resolveSkillName）。
+     * 返回命中的 Skill 实例，未命中返回 undefined。
+     */
+    private resolveSkillNameForPreload;
+    /**
+     * Phase 2: Execution phase with network retry logic
+     * This can be retried multiple times on network errors
+     */
+    private executePhaseWithRetry;
+    /**
+     * Shared completion finalization: scan the report for instruction-shaped
+     * patterns, persist it, build the execution result and mark the task
+     * completed. Used by both the normal path and the maxTurns partial-output
+     * path (Claude Code parity — reaching maxTurns is a normal stop).
+     */
+    private finalizeCompletedResult;
+    /**
+     * Agent ID trailer appended to every subagent report. The `[Agent ID: <id>]`
+     * token is emitted for ALL agent types — including the one-shot Explore / Plan
+     * built-ins — so downstream consumers that parse it (audit / linking) keep
+     * working. This matches the pre-parity output and is honest, since resume
+     * actually succeeds for these sessions too; the earlier Explore/Plan omission
+     * silently broke `[Agent ID: ...]` extraction for those two types.
+     */
+    private agentIdTrailer;
+    /** Last assistant text the subagent produced (partial output for the maxTurns path). */
+    private extractLastAssistantText;
+    /**
+     * Get the execution result
+     */
+    getResult(): AgentTaskExecutionResult | undefined;
+    getMainSession(): Session;
+    getSubAgentSession(): Session | undefined;
+    private rebindIdleQueueDrain;
+    releaseSubAgentSession(): void;
+    private releaseSubAgentRuntime;
+    getInvocationIdentity(): AgentTaskInvocationIdentity;
+    private getSubagentId;
+    private buildSubagentDescriptor;
+    private buildSubagentSnapshot;
+    private emitSubagentStatus;
+    private queueSubagentStatusPublication;
+    private publishSubagentStatus;
+    /**
+     * Setup sub-agent session
+     */
+    private setupSubAgentSession;
+    /**
+     * Inherit the main session's context-window override into a sub-agent session (#133811).
+     *
+     * Copies only the explicit parent override, if any — letting the child fall
+     * back to its own model's default when the parent has none. We deliberately do
+     * NOT copy the parent's *computed* effective budget: that value may have been
+     * clamped to the parent's model, and blindly reusing it would misrepresent the
+     * user's actual intent when the subagent runs a different model.
+     * `resolveSessionContextBudget` (cbc-core) re-validates whatever we set here
+     * against the child model's `supportedLengths` and fails closed if incompatible,
+     * so an inherited value that doesn't fit the child model is harmless.
+     *
+     * Passing `null` when the parent has no override also clears any stale value
+     * left over on a reused/resumed child session id. Nested subagents inherit
+     * transitively because each level re-reads its own immediate parent's override.
+     *
+     * Both sessionManager calls are guarded with a `typeof` check: some sub-agent
+     * / test-double SessionManager stands-ins only implement the members they
+     * personally exercise (see agent-task-resume-model.spec.ts), and this
+     * inheritance step must stay a no-op rather than throw when either method
+     * is absent — mirroring the same defensive pattern `resolveSessionContextBudget`
+     * (context-protocol.ts) already uses for `getOverrideContextWindow`.
+     */
+    private inheritParentContextWindow;
+    /**
+     * Build the sub-agent session's `options` / `requestOptions`.
+     *
+     * Shared by the fresh-create and the resume paths so a resumed sub-agent
+     * runs on exactly the same model as its first turn (issue #95409).
+     * `options` / `requestOptions` are runtime-only — `SessionFactory` rebuilds
+     * them as `{}` for any session deserialized from disk — so the resume path
+     * MUST recompute them instead of trusting whatever came back from the store.
+     */
+    private buildSubAgentSessionOptions;
+    /**
+     * Resolve agent model
+     * 支持三种输入：
+     * 1. "default" / "inherit" - 继承父模型，返回 undefined
+     * 2. 场景类型（如 "lite", "reasoning"），根据主模型动态解析
+     * 3. 模型 ID（如 "gpt-5.1-codex"），直接查找
+     *
+     * 优先级: 环境变量 CODEBUDDY_CODE_SUBAGENT_MODEL > 参数指定的模型
+     */
+    private resolveAgentModel;
+    private isInheritedModel;
+    private resolveConfiguredSubagentModel;
+    /**
+     * Configure permission mode
+     */
+    private configurePermissionMode;
+    /**
+     * Stamp `subAgentPlanModeLocked` on the sub-session meta when the
+     * sub-agent is being EXPLICITLY locked into plan mode (Priority 1 / 2 in
+     * configurePermissionMode). The agent-manager visibility gate reads this
+     * marker to decide whether `ExitPlanMode` should be advertised to the
+     * LLM — sub-agents that merely INHERIT plan mode from the main session
+     * (Priority 4) must not own a plan, otherwise their ExitPlanMode call
+     * surfaces an approval popup whose semantics belong to the parent.
+     *
+     * No-op when the resolved mode is anything other than Plan.
+     */
+    private markPlanModeLockedIfPlan;
+    /**
+     * Setup session subscriptions - forward data to main session
+     * In detached mode, skip forwarding intermediate messages and state updates
+     */
+    private setupSessionSubscriptions;
+    /**
+     * Execute agent with optional custom prompt
+     * @param prompt Optional custom prompt, defaults to this.config.prompt
+     */
+    private executeAgent;
+    private executeSubagentStopHookOnce;
+    /**
+     * Wait for agent completion and get result
+     */
+    private waitForAgentCompletion;
+    /**
+     * Decide whether a finalOutput may be delivered to the parent, or whether a
+     * retry started by a ModelResponseInterceptor owns this sub-session (#85908).
+     *
+     * @returns `true` to deliver (settle), `false` to defer to the retry.
+     */
+    private shouldDeliverDespiteRetry;
+    /**
+     * Bounded wait for the announced retry run to leave `idle`.
+     *
+     * Resolves `true` as soon as the sub-session becomes busy, `false` if nothing
+     * started within {@link AgentTaskImpl.RETRY_START_GRACE_MS}. Returns early on
+     * abort so a cancel is never delayed by the grace window.
+     */
+    private waitForRetryRunToStart;
+    /**
+     * Capture tool call for output
+     */
+    private captureToolCall;
+    /**
+     * Capture final output to file
+     */
+    private captureFinalOutput;
+    /**
+     * Update task status and emit status change event
+     */
+    private updateStatus;
+    /**
+     * Issue 5 · record a sanitized failure summary on the TeamMemberRegistry
+     * entry for this teammate, so the team-lead's next system prompt can
+     * include `<teammate-failures>` and the Desktop UI can show the reason
+     * in a tooltip. No-op for non-teammates (sync sub-agents, background
+     * tasks, auto-team implicit members).
+     *
+     * Registry lookups / mutations are best-effort: any throw is swallowed
+     * and logged at warn level so a failing registry can never prevent the
+     * underlying task from propagating its error upstream.
+     */
+    private recordTeammateFailure;
+    /**
+     * Subscribe to status change events
+     */
+    onStatusChange(listener: (event: {
+        task: AgentTask;
+        oldStatus: string;
+        newStatus: string;
+    }) => void): void;
+    /**
+     * Unsubscribe from status change events
+     */
+    offStatusChange(listener: (event: {
+        task: AgentTask;
+        oldStatus: string;
+        newStatus: string;
+    }) => void): void;
+    /**
+     * Subscribe to progress events (fired once per captured tool_use).
+     * Used by the Agent-tool → backgroundTaskSubject bridge to emit stream-json
+     * `task_progress` events with cumulative usage for background sub-agents.
+     */
+    onProgress(listener: (event: {
+        task: AgentTask;
+    }) => void): void;
+    /**
+     * Unsubscribe from progress events.
+     */
+    offProgress(listener: (event: {
+        task: AgentTask;
+    }) => void): void;
+    /**
+     * Register frontmatter hooks declared on the subagent definition and/or
+     * task config. Scope-scoped to the subagent session; auto-cleaned in
+     * cleanup().
+     *
+     * Two sources (both optional, each gated independently; surviving
+     * configs are registered under the same scope):
+     * 1. agent.hooks — from `.codebuddy/agents/*.md` frontmatter. Trust
+     *    evaluated here via `isAgentAdminTrusted(agentConfig)`.
+     * 2. config.additionalHooks — passed in by caller (e.g. skill-tool fork
+     *    path carries SKILL.md frontmatter hooks here). Trust is declared by
+     *    the caller via `config.additionalHooksAdminTrusted`; we cannot
+     *    infer it from `subagent_type` since skill forks often reuse a
+     *    trusted built-in agent like `general-purpose`.
+     *
+     * Admin-trusted gate: source survives if either the source itself is
+     * admin-trusted, OR `settings.allowUntrustedFrontmatterHooks=true`.
+     * Aligns with CC `runAgent.ts:566` `isSourceAdminTrusted` semantics.
+     */
+    private registerFrontmatterHooks;
+    /**
+     * Cleanup resources
+     */
+    private cleanup;
+    /**
+     * Parse permission mode string to enum
+     */
+    private parsePermissionMode;
+    get agentManager(): AgentManager;
+    get sessionManager(): SessionManager;
+}

package/cli/dist-server/types/node/agent-task/background-task-notifier.d.ts

@@ -0,0 +1,212 @@
+import { AgentService, type BackgroundTask, MessageQueueManager, type NotificationInjectionBuffer as INotificationInjectionBuffer, Session, SessionManager, SessionRunStateMachine } from '../../vendor/cbc-core/node/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { SettingsManager } from '../settings';
+import { AcpDrainTrigger, BackgroundTaskNotifier, StreamJsonDrainTrigger } from './agent-task-protocol';
+/**
+ * 把后台 bash/powershell 任务的完成事件，主动推送给主 agent。
+ *
+ * 设计与 `CronSchedulerServiceImpl` 对齐：
+ * 1. 复用 `MessageQueueManager.enqueueMessage` —— 这是 codebuddy 唯一一条
+ *    "外部事件 → 主 agent"的消息通道。
+ * 2. `isMeta=true` —— 跳过 SystemReminder 注入，对齐 cron 通知样式。
+ * 3. idle 时 `queueMicrotask` 触发一次 drain（ACP / stream-json / 空数组 runDefault）。
+ *    多个 task 在同一 tick 完成时由 `drainPending` 合并成一次 run。
+ * 4. Mode A 的 busy 情形交给 interceptor / `IdleQueueDrainService` 在下一轮合并；Mode B
+ *    下这些兜底全被短路，必须自己挂常驻 RunState 订阅反复补投（详见 `ensureIdleRetry`）。
+ *
+ * 与 Claude Code 的差异（已记录在 commit message）：
+ * - 不做 "N background commands completed" 折叠（CC 是 UI 层折叠，不影响模型上下文，
+ *   未来如果出现刷屏问题再加）
+ * - 不做 stall watchdog（独立 feature，后续 PR）
+ * - 不通过 SDK system event 通道（codebuddy print 模式直接拒绝 run_in_background）
+ *
+ * ACP 模式支持：
+ * - ACP 模式下 `triggerEmptyRun` 绕过了 AcpView 的 `for await` 循环，
+ *   没有 `createEventForwardingPromise` 覆盖，模型响应事件不会被转发给客户端。
+ * - 解决方案：注入 `AcpDrainTrigger`（由 AcpView 实现），ACP 模式下通过
+ *   prompt 迭代器推入内部 drain item，复用 `drainQueuedMessages` 的事件转发链路。
+ */
+export declare class BackgroundTaskNotifierImpl implements BackgroundTaskNotifier {
+    protected readonly messageQueueManager: MessageQueueManager;
+    protected readonly stateMachine: SessionRunStateMachine;
+    protected readonly logger: Logger;
+    protected readonly acpDrainTrigger?: AcpDrainTrigger;
+    protected readonly streamJsonDrainTrigger?: StreamJsonDrainTrigger;
+    /**
+     * 后台通知注入缓冲（#89130）。Mode B 下通知进这里而非 session.queue：busy 期由正在跑的
+     * 真实轮 mid-turn 注入（runner-factory 来源三），idle 期作为非空 input 起轮
+     * （ACP drainBackgroundTaskNotifications 从缓冲取）。用 @Optional() 容错精简变体。
+     */
+    protected readonly notificationBuffer?: INotificationInjectionBuffer;
+    /**
+     * 仅用于写「后台任务完成耗时行」（见 {@link appendCompletionMetrics}）。
+     *
+     * 用 `@Autowired` 而非懒解析是有意的：这确实闭合了一个环
+     * （SessionManager → ToolManager → Tool[] → BashTool → 本类 → SessionManager），
+     * 但 CellJS 把 `@Component` 的 Symbol 绑成 `toDynamicValue`，inversify 的解析计划
+     * 遇到这类绑定就停止下探，环进不了静态循环检测。同形态的更短的环
+     * （SessionManagerImpl ⇄ ToolManagerImpl）已在生产运行。
+     *
+     * **约束：只能在方法体里用**——再入解析时拿到的是同一个对象，但那一刻它自己的
+     * 属性注入未必跑完，构造函数 / 字段初始化器里用会读到空引用。
+     */
+    protected readonly sessionManager?: SessionManager;
+    protected readonly settingsManager?: SettingsManager;
+    /**
+     * 同 tick 内多个 task 完成时合并 drain，避免触发多次空数组 run。
+     * 以 sessionId 为粒度——不同 session 的 drain 必须独立。
+     */
+    private drainPending;
+    /**
+     * 常驻的 idle 重投订阅，每个 Session 最多一条。见 `ensureIdleRetry`。
+     */
+    private readonly pendingIdleRetry;
+    notifyCompletion(task: BackgroundTask, session: Session, options?: {
+        deferDrain?: boolean;
+    }): void;
+    /**
+     * 往对话流写一条「后台任务完成耗时」，渲染为 `✔ Worked for 2m 20s`。
+     *
+     * 为什么需要：后台任务完成此前在对话流里**完全不可见**——通知是 `isMeta` 消息
+     * 界面不渲染，而 `<task-notification>` XML 里也没有时长字段，模型自己同样不知道
+     * 任务跑了多久。这个数字原本只能按 ↓ 进任务面板才看得到。
+     *
+     * 复用 `turn-metrics` 项而不是新增类型：展示形态与回合耗时行本来就要求一致，
+     * 复用后渲染组件、时长格式化与 `showTurnDuration` 开关全部共享，对 stream-json /
+     * ACP / SDK 消费方的数据形状零影响。两者靠 `source` 字段区分——它同时决定了
+     * 这一行不带 `· N shells still running` 后缀。
+     *
+     * 失败安全：整段自吞异常。写历史失败**绝不能**影响通知投递，否则会退化成
+     * issue #83856 那类「后台任务跑完了主 agent 不知道」的静默故障。
+     */
+    private appendCompletionMetrics;
+    notifyEvent(session: Session, xml: string): void;
+    /**
+     * `notifyCompletion` / `notifyEvent` 共用的入队 + drain 调度逻辑。
+     *
+     * @param deferDrain 只入队不调度。**注意这不是"稍后一定会投"的承诺**——它连
+     *   `ensureIdleRetry` 都不挂，所以这条通知会一直等到下一次有人真正起轮（用户输入、
+     *   别的后台任务完成、Mode A 的 interceptor 兜底）才被 drain 走。这正是"用户点删除
+     *   不该自己烧一轮对话"想要的语义。
+     */
+    private enqueueAndScheduleDrain;
+    /**
+     * 拼装 `<task-notification>` XML。字段顺序对齐 Claude Code（task-id / status /
+     * summary / output-file），方便未来共享解析逻辑。
+     *
+     * Summary 文案区分 toolName，让模型一眼看出是 Bash/PowerShell；status=killed 时
+     * 标注"was stopped"，以便模型知道这是显式 kill 不是 process crash。
+     */
+    private buildNotificationXml;
+    /**
+     * 尾部的"行动指引"。这段是整条通知里唯一直接指挥模型下一步的内容，也是最容易
+     * 出错的地方——LLM 对末尾几行的注意力最高。
+     *
+     * 按结束原因分支，而不是所有终态共用一套话术：`killed` 同时覆盖「用户取消」
+     * 「输出超限被强杀」「会话中断」，它们要求的下一步截然相反。
+     *
+     * 只说"输出去哪取"和"这条通知是什么"，不替模型判断下一步该做什么——要求模型
+     * 回看原始请求、"原始指令优先"的话术已删除（#133018），它会让模型自行加戏。
+     */
+    private buildGuidanceLines;
+    /**
+     * 这个任务的退出码是否不可信——即 `completed` 这个状态是猜出来的，不是收到退出码
+     * 算出来的。
+     *
+     * 额外要求 `status === 'completed'` 是一道防御：`kill` 之后终止事件丢失、由句柄
+     * 兜底收口，是这条路径最常见的形态，于是 `exitStatusUnknown` 会和 `killed` 大量
+     * 共存。而对一个用户主动停掉的任务说"退出码没采集到，请看输出判断成功与否"是误导——
+     * 他知道是自己停的。置位口径见 {@link BackgroundTask.exitStatusUnknown}，这里再拦一层。
+     */
+    private isExitStatusUnknown;
+    private buildSummary;
+    requestIdleRetry(session: Session): void;
+    /**
+     * 本通道拥有、还等着投递的排队项数量，用于常驻 idle 重投判定「还有没有要发的」。
+     *
+     * Mode B（#89130）：通知在 NotificationInjectionBuffer，读它。**不能**读
+     * `session.queue`——Mode B 下通知已不进 session.queue，而 session.queue 里可能有
+     * rich queue 的展示镜像（用户输入），读它会误判成「还有通知」，把用户排队消息提前投给模型。
+     * Mode A：通知仍在 session.queue，读 `QueueDispatchUtils.ownedQueueItems`。
+     */
+    private pendingNotificationCount;
+    /**
+     * idle 时主动触发一次 drain；busy 时挂上常驻 idle 重投（`ensureIdleRetry`）。
+     *
+     * 为什么用 queueMicrotask 而不是同步调用：
+     * - notifyCompletion 是从 bash-tool 的 .then/.catch/.finally 链路调进来的，
+     *   此时 ToolCall 可能还在结算中，state machine 状态未必已经回 IDLE。延后到
+     *   微任务能让当前 reactive chain 收尾。
+     * - 同时多个 task 完成时通过 drainPending 合并，避免重复 run。
+     *
+     * busy 检查刻意排在 drainPending 之前：已排了微任务但在它执行前会话又变 busy 时，
+     * 这个顺序保证后到的通知走 ensureIdleRetry 分支而不是被 drainPending 静默吃掉。
+     *
+     * 无论走哪条分支都会 `ensureIdleRetry`：投递本身可能静默失败（ACP 的 triggerDrain 有
+     * 多条 warn-and-return 分支、stream-json 可能没有 parked waiter、drain 轮次也可能被
+     * 打断），常驻订阅是这些失败的统一兜底。
+     */
+    private scheduleDrain;
+    /**
+     * TUI 先开、Web 后挂上时 `options.acp` 往往仍是 false，但 `meta.acpConnectionId`
+     * 已经写好。只看 options 会把唤醒投进 TUI 空 run / Mode B 死缓冲，Web 永远看不到
+     * `<task-notification>`。
+     */
+    private isAcpAttachedSession;
+    /** 按宿主形态把 drain 请求投出去。调用方已确认 session 活着、idle、未 abort。 */
+    private dispatchDrain;
+    /**
+     * Mode B 无 ACP 通道、或 ACP triggerDrain 未注入时：从缓冲取出通知当非空 input 起轮。
+     * 投递失败必须 push 回去，否则 pendingNotificationCount 变 0，idle 重投再也补不了。
+     */
+    private deliverBufferedNotificationRun;
+    private triggerNotificationRun;
+    /**
+     * fall-through 轮（triggerEmptyRun / triggerNotificationRun）成功送达后的 ACP 收尾。
+     *
+     * 这轮不经过 AcpView 的 drain 链路，没有 session_end 收尾帧，Web UI 输入框可能
+     * 一直停在 running。委托给 AcpDrainTrigger（AcpView）：能解析到绑定本会话的
+     * AcpAgent 就补发与正常 drain 轮相同的 session_end，解析不到（纯 TUI）时 no-op。
+     * 只在投递成功后调用——失败路径已回灌，收尾帧会误导客户端以为这轮结束了。
+     */
+    private notifyAcpFallThroughCompleted;
+    /**
+     * 挂一条**常驻**的 idle 重投订阅：每次合格 idle 都重新尝试投递，直到本通道的待投项
+     * 被消费干净；session 释放时 `runStateSubject.complete()` 自动收尾。
+     *
+     * 为什么需要（#89130 后）：Mode B 下 busy 期完成的后台任务通知进
+     * `NotificationInjectionBuffer`，主要由正在跑的真实轮 mid-turn 注入（runner-factory
+     * 来源三）。但存在一个边界——busy 期完成通知、且其所在轮就是最后一轮（之后再无用户
+     * 输入 / 后台任务）时，没有新的 model step 来 drain 它。常驻订阅补上这个洞：轮结束
+     * 落到合格 idle 时，`pendingNotificationCount` 读 buffer 发现还有通知，触发 dispatchDrain
+     * 起一次真实轮把它送达。这也覆盖投递静默失败（ACP `triggerDrain` 的 warn-and-return
+     * 分支、stream-json 无 parked waiter、drain 轮次被打断）的重试。
+     *
+     * 为什么常驻而不是一次性：投递可以静默失败，一次性语义会把唯一的重试烧掉。形态对齐
+     * 同仓 `IdleQueueDrainService`。
+     *
+     * 为什么只在 Mode B 挂：Mode A 通知走 session.queue，`IdleQueueDrainService` /
+     * interceptor 兜底已在。再挂一个 drainer 会在同一次 transition 上并发触发多余的空
+     * drain run。Mode B 的 TUI / ACP-miss 路径由 `deliverBufferedNotificationRun` 投递。
+     */
+    private ensureIdleRetry;
+    /**
+     * 常驻订阅的每次判定。任何一项 guard 不过就静默跳过，**不拆订阅**——下一次合格
+     * transition 还要再试。只有会话换代才拆（那条订阅已经属于上一代）。
+     */
+    private tryIdleRetry;
+    /**
+     * 会话卸载/换代：拆掉本代的 idle-retry 订阅。abort **不**触发本方法
+     * （#83856：abort 保订阅等 resume）。单进程单主会话世界里 WeakMap 键
+     * 天然随对象回收兜底，这里提供显式拆点供释放路径与测试使用。
+     */
+    evictSession(session: Session): void;
+    private teardownIdleRetry;
+    private triggerEmptyRun;
+    /**
+     * 解析 AgentService。提取出来便于测试覆盖（避免触碰 ContainerUtil）。
+     * 不通过 `@Autowired` 是为了和 `AgentService → BackgroundTaskNotifier` 之间
+     * 可能形成的循环依赖解耦——延迟到使用时再解析。
+     */
+    protected resolveAgentService(): AgentService;
+}

package/cli/dist-server/types/node/agent-task/background-task-tool-approval-service.d.ts

@@ -0,0 +1,36 @@
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { AgentInputItem, RunToolApprovalItem } from '../../vendor/cbc-shared/node/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { ToolManager } from '../tools';
+import { BackgroundTaskToolApprovalService } from './agent-task-protocol';
+/**
+ * BackgroundTaskToolApprovalServiceImpl
+ * 后台任务工具授权服务实现
+ *
+ * 负责在后台任务 session 中处理工具调用权限。
+ * 所有工具调用自动批准，无需用户交互。
+ */
+export declare class BackgroundTaskToolApprovalServiceImpl implements BackgroundTaskToolApprovalService {
+    protected readonly logger: Logger;
+    protected readonly toolManager: ToolManager;
+    /**
+     * 检查 session 是否为后台任务会话
+     * 通过检查 session.meta.isBackgroundTaskSession 标记
+     */
+    isBackgroundTaskSession(session: Session): boolean;
+    /**
+     * 自动批准后台任务中的工具调用
+     * SDK 批准由 core 对准确的来源 RunState 写入；这里只记录策略决定
+     */
+    approve(item: RunToolApprovalItem, session: Session): void;
+    /**
+     * 处理后台任务中被拒绝的工具调用
+     * 生成工具执行失败结果并返回给 Agent
+     */
+    handleRejection(item: RunToolApprovalItem, session: Session, reason: string): Promise<AgentInputItem[]>;
+    /**
+     * 记录权限决策
+     * 用于审计和日志追踪
+     */
+    logApprovalDecision(item: RunToolApprovalItem, session: Session, decision: 'approved' | 'rejected'): void;
+}

package/cli/dist-server/types/node/agent-task/index.d.ts

@@ -0,0 +1,9 @@
+export * from './agent-task-manager';
+export * from './agent-task-protocol';
+export * from './subagent-output-scanner';
+export * from './agent-task';
+export * from './agent-task-output-manager';
+export * from './background-task-notifier';
+export * from './background-task-tool-approval-service';
+export * from './retained-agent-task';
+export * from './stream-json-drain-trigger';

package/cli/dist-server/types/node/agent-task/retained-agent-task.d.ts

@@ -0,0 +1,11 @@
+import { type Session } from '../../vendor/cbc-core/node/index.js';
+import { type AgentInputItem } from '../../vendor/cbc-shared/node/index.js';
+import { type AgentTask, type AgentTaskExecutionConfig } from './agent-task-protocol';
+export declare const AGENT_TREE_GRACE_MS = 30000;
+export declare function onRetainedAgentTasksChanged(listener: () => void): () => void;
+export declare function dismissRetainedAgentTask(taskId: string): void;
+export declare function startRetainedAgentTask(config: AgentTaskExecutionConfig): AgentTask;
+/** Observe TUI agent invocations without retaining them before the user opens Agent view. */
+export declare function trackInteractiveAgentTask(task: AgentTask, notify?: boolean): void;
+export declare function setRetainedAgentTaskFocused(taskId: string, focused: boolean): void;
+export declare function sendToRetainedAgentTask(taskId: string, message: string | AgentInputItem[], parentSession: Session): Promise<string>;