@armadra/agent 0.4.0 → 0.5.1

package/dist/agent/session-run.js

@@ -10,12 +10,31 @@
  * - 将要停下时发 agent_before_settle 并跑 Stop（子 Agent 为 SubagentStop）Hook：block + reason →
  *   以 reason 作为新 user 消息再跑一轮（上限 3 次，stopHookActive 传给 Hook）。
  * - 最终失败后若 followUp 队列非空，照常投递。
+ * - [W5-H2] 模型回退：可重试错误在 overloaded 时、或重试用尽后，若配置了 `fallbackModel` 就切过去
+ *   重试一次本请求（`model_fallback` 事件），回退模型回复后切回主模型；每个周期最多一次。
+ * - [W5-H2] 扩展经 `noteSettleWarning` 登记的 warning（预算到限 `limit_reached`）写进本周期的 agent_settled；
+ *   `limit_reached:` 开头的错误回复（预算拦下请求）不重试。
+ * - [W5-H2] run 带 `warning`（重复调用检测 `repeated_tool_call`）：不跑 Stop Hook，agent_settled 带该 warning。
  */
 import { AmaError } from "../errors.js";
+import { formatModelRef, modelRefOf } from "../ai/providers/channels.js";
 import { classifyFailure, retryDelayMs, sleep } from "./retry.js";
 export const MAX_STOP_HOOK_CONTINUATIONS = 3;
 export const ABORTED_CUSTOM_TYPE = "ama.aborted";
-export function decideAfterRun(deps, outcome, retryAttempt, overflowRecovered) {
+/** [W5-H2] 预算拦下请求时错误回复的前缀（limits.ts）：判为最终失败，不重试、不回退。 */
+export const LIMIT_ERROR_PREFIX = "limit_reached:";
+/** [W5-H2] 扩展（limits）登记的 agent_settled warning：本周期收尾时取走。 */
+const settleWarnings = new WeakMap();
+export function noteSettleWarning(core, warning) {
+    if (!settleWarnings.has(core))
+        settleWarnings.set(core, warning);
+}
+function takeSettleWarning(core) {
+    const warning = settleWarnings.get(core);
+    settleWarnings.delete(core);
+    return warning;
+}
+export function decideAfterRun(deps, outcome, retryAttempt, overflowRecovered, fallbackUsed = false) {
     if (outcome.stopReason === "aborted")
         return { kind: "aborted" };
     const last = outcome.lastAssistant;
@@ -25,6 +44,8 @@ export function decideAfterRun(deps, outcome, retryAttempt, overflowRecovered) {
     if (!failedStop)
         return { kind: "done" };
     const errorMessage = last.errorMessage ?? (last.stopReason === "length" ? "output hit the token limit" : "error");
+    if (errorMessage.startsWith(LIMIT_ERROR_PREFIX))
+        return { kind: "failed", errorMessage };
     const classifyOptions = deps.core.options.isContextOverflow === undefined
         ? {}
         : { isContextOverflow: deps.core.options.isContextOverflow };
@@ -38,11 +59,75 @@ export function decideAfterRun(deps, outcome, retryAttempt, overflowRecovered) {
         return recoverable ? { kind: "overflow" } : { kind: "failed", errorMessage };
     }
     const settings = deps.retry();
+    const canFallback = kind === "retryable" && !fallbackUsed && fallbackTarget(deps.core) !== undefined;
+    if (canFallback && OVERLOADED.test(errorMessage))
+        return { kind: "fallback", errorMessage };
     if (kind === "retryable" && settings.enabled && retryAttempt < settings.maxRetries) {
         return { kind: "retry", errorMessage };
     }
+    if (canFallback)
+        return { kind: "fallback", errorMessage };
     return { kind: "failed", errorMessage };
 }
+const OVERLOADED = /overloaded/i;
+/** 配置了与当前模型不同、且能找到的回退模型时返回它的引用。 */
+function fallbackTarget(core) {
+    const target = core.options.fallbackModel?.trim();
+    if (target === undefined || target === "")
+        return undefined;
+    if (core.setModel === undefined)
+        return undefined;
+    const current = core.model();
+    const refs = [formatModelRef(current), `${current.provider}/${current.id}`];
+    if (refs.includes(target))
+        return undefined;
+    // 找不到的回退模型等于没配：照常重试（启动时不校验，避免目录未加载时误报）
+    return core.options.providers.findModel(target).ok ? target : undefined;
+}
+/**
+ * [W5-H2] 模型回退（§8.3 H7）：经 `setModel` 切到回退模型（落 model_change、发 model_changed——缓存
+ * 未命中归因 `model_changed`，思考块按跨模型规则降级），发 `model_fallback{from, to, reason}`；
+ * 回退模型的第一条回复落盘后切回主模型（下一次请求仍用主模型）。返回「切回」函数；切换失败返回
+ * undefined（按最终失败处理）。
+ */
+async function switchToFallback(core, reason) {
+    const target = fallbackTarget(core);
+    const switcher = core;
+    if (target === undefined || switcher.setModel === undefined)
+        return undefined;
+    const primary = core.model();
+    try {
+        await switcher.setModel(target);
+    }
+    catch (error) {
+        core.log("warn", `fallbackModel ${target} unavailable: ${String(error)}`);
+        return undefined;
+    }
+    core.emit({
+        type: "model_fallback",
+        from: modelRefOf(primary),
+        to: modelRefOf(core.model()),
+        reason,
+    });
+    let restored = false;
+    const restore = async () => {
+        if (restored)
+            return;
+        restored = true;
+        unsubscribe();
+        try {
+            await switcher.setModel?.(formatModelRef(primary));
+        }
+        catch (error) {
+            core.log("warn", `cannot switch back to ${formatModelRef(primary)}: ${String(error)}`);
+        }
+    };
+    const unsubscribe = core.agent.subscribe(async (event) => {
+        if (event.type === "message_end" && event.message.role === "assistant")
+            await restore();
+    });
+    return restore;
+}
 /** 用 context_edit 把失败尝试（助手消息与其后补的结果）从上下文剔除。 */
 export function excludeFailedAttempt(core, failed, reason) {
     if (failed === undefined)
@@ -72,7 +157,30 @@ export function recordAbort(core) {
     });
     core.reloadMessages();
 }
+/**
+ * 会话周期：跑完一轮（到 agent_settled 与 onAgentSettled）后，若期间（Stop Hook、agent_settled 监听器、
+ * onAgentSettled 扩展）又有 steer / followUp 入队——宿主 `sendUser`、子 Agent 后台通知等在周期收尾
+ * 阶段调用时会话仍算忙，只能入队——就在同一周期里再开一轮投递它们（[W5-H2]，W5-G 发现的竞态）。
+ * abort 或已请求停止（Hook continue:false、预算到限）时不续投，消息留在队列。
+ */
 export async function runCycle(deps, prompts, signal) {
+    let next = prompts;
+    for (;;) {
+        await runSettledCycle(deps, next, signal);
+        if (signal.aborted || deps.stopRequested())
+            return;
+        const queued = drainQueued(deps.core);
+        if (queued.length === 0)
+            return;
+        next = queued;
+    }
+}
+/** 先取 steer（按其投递模式），没有再取 followUp。 */
+function drainQueued(core) {
+    const steering = core.agent.steeringQueue.drain();
+    return steering.length > 0 ? steering : core.agent.followUpQueue.drain();
+}
+async function runSettledCycle(deps, prompts, signal) {
     const { core, compaction } = deps;
     let next = prompts;
     let retryAttempt = 0;
@@ -80,6 +188,8 @@ export async function runCycle(deps, prompts, signal) {
     let stopHooks = 0;
     let warning;
     let announced = false;
+    let fallbackUsed = false;
+    let restoreModel;
     const endRetry = (success, finalError) => {
         if (retryAttempt === 0)
             return;
@@ -100,8 +210,8 @@ export async function runCycle(deps, prompts, signal) {
         const outcome = await core.agent.run(next, {
             signal,
             onRunEnd: (result) => {
-                decision = decideAfterRun(deps, result, retryAttempt, overflowRecovered);
-                return decision.kind === "retry" || decision.kind === "overflow";
+                decision = decideAfterRun(deps, result, retryAttempt, overflowRecovered, fallbackUsed);
+                return (decision.kind === "retry" || decision.kind === "overflow" || decision.kind === "fallback");
             },
         });
         next = undefined;
@@ -141,7 +251,21 @@ export async function runCycle(deps, prompts, signal) {
             next = [];
             continue;
         }
+        if (current.kind === "fallback") {
+            fallbackUsed = true;
+            endRetry(false, current.errorMessage);
+            restoreModel = await switchToFallback(core, current.errorMessage);
+            if (restoreModel !== undefined) {
+                excludeFailedAttempt(core, outcome.lastAssistant, "retry");
+                next = [];
+                continue;
+            }
+        }
         endRetry(current.kind === "done", current.kind === "failed" ? current.errorMessage : undefined);
+        // [W5-H2] harness 提前结束（重复调用检测）：带 warning 停下，不跑 Stop Hook、不续投队列
+        const harnessStop = outcome.warning;
+        if (harnessStop !== undefined)
+            warning = harnessStop;
         if (current.kind === "overflow") {
             overflowRecovered = true;
             excludeFailedAttempt(core, outcome.lastAssistant, "overflow");
@@ -156,19 +280,30 @@ export async function runCycle(deps, prompts, signal) {
             }
             warning = recovery.warning;
         }
-        else if (current.kind === "failed") {
+        else if (current.kind === "failed" || current.kind === "fallback") {
             warning = current.errorMessage;
             void core.runHook("Notification", {
                 notification: { kind: "error", message: current.errorMessage },
             });
         }
-        if (current.kind === "failed" && core.agent.followUpQueue.hasItems()) {
+        if ((current.kind === "failed" || current.kind === "fallback") &&
+            core.agent.followUpQueue.hasItems()) {
             next = core.agent.followUpQueue.drain();
             continue;
         }
+        // [W5-H2] run 收尾时（循环已不再取队列）入队的 steer / followUp：本周期接着投递，不滞留到下次提示
+        const queuedNow = () => harnessStop === undefined && !deps.stopRequested() && !signal.aborted
+            ? drainQueued(core)
+            : [];
+        let queued = queuedNow();
+        if (queued.length > 0) {
+            next = queued;
+            continue;
+        }
         core.emit({ type: "agent_before_settle" });
         announced = true;
         if (current.kind === "done" &&
+            harnessStop === undefined &&
             !deps.stopRequested() &&
             stopHooks < MAX_STOP_HOOK_CONTINUATIONS) {
             const event = core.depth > 0 ? "SubagentStop" : "Stop";
@@ -183,16 +318,28 @@ export async function runCycle(deps, prompts, signal) {
                 continue;
             }
         }
+        queued = queuedNow(); // Stop Hook 期间入队的
+        if (queued.length > 0)
+            next = queued;
     }
+    await restoreModel?.();
     if (!announced)
         core.emit({ type: "agent_before_settle" });
     const settled = { type: "agent_settled" };
+    const noted = takeSettleWarning(core);
+    if (noted !== undefined && (warning === undefined || warning.startsWith(LIMIT_ERROR_PREFIX)))
+        warning = noted;
     if (warning !== undefined)
         settled.warning = warning;
     core.emit(settled);
     void core.runHook("Notification", {
         notification: { kind: "settled", message: warning ?? "run finished" },
     });
+    await deps.afterSettled?.();
+}
+/** `"user"` = 普通用户输入，不写 origin。 */
+export function normalizeOrigin(origin) {
+    return origin === undefined || origin === "user" ? undefined : origin;
 }
 export function makeUserMessage(text, images, origin) {
     const message = {
@@ -226,7 +373,8 @@ export async function runPrompt(deps, text, images, origin, signal) {
         if (hook.updatedPrompt !== undefined)
             prompt = hook.updatedPrompt;
     }
-    const prompts = [makeUserMessage(prompt, images, origin)];
+    const message = makeUserMessage(prompt, images, origin);
+    const prompts = [message];
     if (hook?.additionalContext !== undefined && hook.additionalContext !== "") {
         prompts.push({
             role: "custom",
@@ -240,6 +388,9 @@ export async function runPrompt(deps, text, images, origin, signal) {
     if (signal.aborted)
         return "handled";
     deps.syncSystem();
+    deps.beginTurn?.(message);
+    if (deps.beforePrompts !== undefined)
+        prompts.push(...(await deps.beforePrompts(prompts)));
     core.emit({ type: "before_agent_start", prompt });
     await runCycle(deps, prompts, signal);
     return "started";

package/dist/agent/session-settings.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 会话的可变设置：模型、思考级别、工具表与活动集、系统提示静态部分（从 session.ts 搬出，
+ * docs/wave5-plan.md §9「session.ts → session-settings.ts」）。[W5-C0]
+ *
+ * 纯搬迁：`setModel / setThinkingLevel / setPermissionMode / setActiveTools / addTool /
+ * updateSystem / announceStart / getTools` 的行为与事件顺序不变；`AgentSessionImpl` 以同名成员转发。
+ */
+import type { Model, ModelThinkingLevel, ProviderRegistryApi } from "../ai/types.js";
+import type { PermissionMode } from "../permissions/types.js";
+import type { ToolDefinition } from "../tools/types.js";
+import type { StreamFn } from "./loop.js";
+import type { AgentSessionOptions, SessionCore } from "./session-core.js";
+import type { SystemPromptInput } from "./system-prompt.js";
+/** 按模型的协议分派到已注册的实现（会话流的最内层）。 */
+export declare function providerStream(providers: ProviderRegistryApi): StreamFn;
+export type StaticSystemInput = Omit<SystemPromptInput, "tools" | "cwd">;
+export interface SessionSettingsDeps {
+    /** 会话本身（构造完成后才会被调用）。 */
+    core: SessionCore;
+    assertUsable(): void;
+    /** 换模型后刷新压缩阈值。 */
+    onModelChanged(): void;
+}
+export declare class SessionSettings {
+    private readonly options;
+    private readonly deps;
+    model: Model;
+    thinking: ModelThinkingLevel;
+    systemInput: StaticSystemInput;
+    private readonly allTools;
+    private activeNames;
+    constructor(options: AgentSessionOptions, deps: SessionSettingsDeps);
+    activeTool(name: string): ToolDefinition | undefined;
+    tool(name: string): ToolDefinition | undefined;
+    activeToolNames(): string[];
+    /** 子会话 / fork 继承的活动集（同一数组引用，与搬迁前一致）。 */
+    activeNamesRef(): string[];
+    setModel(ref: string): Promise<void>;
+    setThinkingLevel(level: ModelThinkingLevel): void;
+    setPermissionMode(mode: PermissionMode): void;
+    setActiveTools(names: string[]): void;
+    /** 宿主 / SDK 在会话创建后追加工具（下次请求前以 system 补丁声明）。 */
+    addTool(tool: ToolDefinition, active?: boolean): void;
+    /** 更新系统提示的静态部分（SessionStart Hook 的 hookContext、宿主 instructions 等）。 */
+    updateSystem(patch: Partial<StaticSystemInput>): void;
+    getTools(): readonly ToolDefinition[];
+    /** 发 session_start（bootstrap / SDK 在会话就绪后调用一次）。 */
+    announceStart(reason: "startup" | "resume" | "new" | "fork"): void;
+}

package/dist/agent/session-settings.js

@@ -0,0 +1,95 @@
+/**
+ * 会话的可变设置：模型、思考级别、工具表与活动集、系统提示静态部分（从 session.ts 搬出，
+ * docs/wave5-plan.md §9「session.ts → session-settings.ts」）。[W5-C0]
+ *
+ * 纯搬迁：`setModel / setThinkingLevel / setPermissionMode / setActiveTools / addTool /
+ * updateSystem / announceStart / getTools` 的行为与事件顺序不变；`AgentSessionImpl` 以同名成员转发。
+ */
+import { AmaError } from "../errors.js";
+import { appendModelChange, findModelOrThrow, sessionStartEvent } from "./session-sync.js";
+/** 按模型的协议分派到已注册的实现（会话流的最内层）。 */
+export function providerStream(providers) {
+    return (model, context, streamOptions) => {
+        const api = providers.getApi(model.api);
+        if (api === undefined) {
+            throw new AmaError("provider_not_found", `no implementation registered for api ${model.api}`);
+        }
+        return api.stream(model, context, streamOptions);
+    };
+}
+export class SessionSettings {
+    options;
+    deps;
+    model;
+    thinking;
+    systemInput;
+    allTools = new Map();
+    activeNames;
+    constructor(options, deps) {
+        this.options = options;
+        this.deps = deps;
+        this.model = options.model;
+        this.thinking = options.thinkingLevel ?? "off";
+        for (const tool of options.tools ?? [])
+            this.allTools.set(tool.name, tool);
+        this.activeNames = [...(options.activeTools ?? this.allTools.keys())].filter((name) => this.allTools.has(name));
+        this.systemInput = { ...(options.system ?? {}) };
+    }
+    activeTool(name) {
+        return this.activeNames.includes(name) ? this.allTools.get(name) : undefined;
+    }
+    tool(name) {
+        return this.allTools.get(name);
+    }
+    activeToolNames() {
+        return [...this.activeNames];
+    }
+    /** 子会话 / fork 继承的活动集（同一数组引用，与搬迁前一致）。 */
+    activeNamesRef() {
+        return this.activeNames;
+    }
+    async setModel(ref) {
+        this.deps.assertUsable();
+        this.model = findModelOrThrow(this.options.providers, ref);
+        this.deps.onModelChanged();
+        const core = this.deps.core;
+        core.emit({ type: "model_changed", model: appendModelChange(core, this.model) });
+    }
+    setThinkingLevel(level) {
+        this.thinking = level;
+        this.deps.core.appendEntry({ type: "thinking_level_change", thinkingLevel: level });
+        this.deps.core.emit({ type: "thinking_level_changed", level });
+    }
+    setPermissionMode(mode) {
+        this.options.permission?.setMode(mode);
+        this.deps.core.emit({ type: "permission_mode_changed", mode });
+    }
+    setActiveTools(names) {
+        const unknown = names.filter((name) => !this.allTools.has(name));
+        if (unknown.length > 0)
+            throw new AmaError("tool_not_found", `unknown tools: ${unknown.join(", ")}`);
+        this.activeNames = [...new Set(names)];
+    }
+    /** 宿主 / SDK 在会话创建后追加工具（下次请求前以 system 补丁声明）。 */
+    addTool(tool, active = true) {
+        if (this.allTools.has(tool.name))
+            throw new AmaError("tool_exists", `tool ${tool.name} already exists`);
+        this.allTools.set(tool.name, tool);
+        if (active)
+            this.activeNames.push(tool.name);
+    }
+    /** 更新系统提示的静态部分（SessionStart Hook 的 hookContext、宿主 instructions 等）。 */
+    updateSystem(patch) {
+        this.systemInput = { ...this.systemInput, ...patch };
+    }
+    getTools() {
+        return this.activeNames
+            .map((name) => this.allTools.get(name))
+            .filter((tool) => tool !== undefined)
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    /** 发 session_start（bootstrap / SDK 在会话就绪后调用一次）。 */
+    announceStart(reason) {
+        this.deps.core.emit(sessionStartEvent(this.deps.core.manager, reason));
+    }
+}

package/dist/agent/session-subagent.d.ts

@@ -1,39 +1,43 @@
 /**
- * 子 Agent（设计 §5.2 task、D14）：`ToolContext.spawnSubagent` 的实现，供 B3 的 task 工具调用。[B2]
+ * 子 Agent（设计 §5.2 task、D14；第五波 docs/wave5-plan.md §7，D22–D24）：`ToolContext.spawnSubagent`
+ * 的实现与 ama 自己的 runner（`AmaRunner`）。[B2 → W5-G]
  *
- * - 同进程新会话：独立 JSONL（头的 parentSession 指回父文件；父为内存会话则子也在内存），首条
- *   `custom{customType:"ama.task"}` 记父 toolCallId。
- * - 深度 ≤ 1（子会话 depth 1、无 spawnSubagent）；并发 ≤ 4（排队等待）。
- * - 工具子集缺省 = 父的活动集，总是去掉 task；继承父的权限管线、Hook 与系统提示静态部分；
- *   broker 包一层，请求带 `context{depth, parentToolCallId}`，审批事件转发到父会话。
- * - 父 abort 级联；结果 = 子的最后助手文本 + 用量 + 子会话文件。
- * - [W3-C1b] 子会话有自己的缓存控制器（统计独立、未命中不进父链，`warmSubagents` 为 false 时
- *   不保温）；结果带 `cache{hitRate, reBilledTokens}`，并汇总进父会话的「子任务」统计。
+ * - `runSubagent`：交给会话的任务注册表（subagent-registry.ts）——类型解析、并发池、前台 / 后台、
+ *   续聊、结果上限、事件都在那里；这里只提供「起一个 ama 子会话」的 runner。
+ * - 子会话：同进程新会话，独立 JSONL（头的 parentSession 指回父文件；父为内存会话则子也在内存），
+ *   首条 `custom{ama.task}` 记父 toolCallId 与 taskId；深度 ≤ 1（depth 1、无 spawnSubagent）。
+ * - **工具表与父字节一致**（D23）：活动集 = 父活动集，`task` / `task_ctl` 保留在表里、运行时按深度
+ *   拒绝，子会话首请求能命中父的 tools + system 前缀；角色说明进系统提示末位 `role` 节。只有类型
+ *   声明了 `tools` / `disallowed-tools`（或调用参数给了 `tools`）时工具表才不同。
+ * - 只读类型（`permission-mode: plan`）：子会话用一条 plan 模式的权限管线（规则同父），ask 一律转
+ *   deny——写类工具与识别不了的 bash 被拒且不弹审批；`inherit` 共用父的管线（不会比父宽）。
+ * - 轮数耗尽且最后停在工具结果上：以 `toolChoice:"none"` 再跑一轮要最终报告，状态 `max_turns`。
+ * - broker 包一层，请求带 `context{depth, parentToolCallId, taskId}`，审批事件转发到父会话；
+ *   [RW-B] 父的检查点钩子（worktree 里运行时不记）；[W3-C1b] 子会话命中与重计费汇总进父。
  */
+import type { CheckpointHooks } from "../checkpoints/types.js";
+import type { PermissionPipelineApi } from "../permissions/types.js";
 import { SessionManager } from "../session/manager.js";
-import type { SubagentRequest, SubagentResult } from "../tools/types.js";
+import type { AgentMessage } from "../session/types.js";
+import type { SubagentRequest, SubagentResult, SubagentRunner } from "../tools/types.js";
 import type { AgentSessionOptions } from "./session-core.js";
+import { DEFAULT_SUBAGENT_CONCURRENCY, SubagentPool, TASK_CUSTOM_TYPE, type AmaRunnerSpec, type RegistryHost } from "./subagent-registry.js";
 import type { SessionEvent, SessionStats } from "./types.js";
-export declare const DEFAULT_SUBAGENT_CONCURRENCY = 4;
+export { DEFAULT_SUBAGENT_CONCURRENCY, SubagentPool, TASK_CUSTOM_TYPE };
 export declare const DEFAULT_SUBAGENT_MAX_TURNS = 30;
-export declare const TASK_CUSTOM_TYPE = "ama.task";
-/** 计数信号量。 */
-export declare class SubagentPool {
-    private readonly limit;
-    private running;
-    private readonly waiters;
-    constructor(limit: number);
-    acquire(signal: AbortSignal): Promise<void>;
-    release(): void;
-}
-export interface SubagentParent {
+/** 子会话里保留在工具表、运行时拒绝的名字（深度 ≤ 1）。 */
+export declare const PARENT_ONLY_TOOLS: readonly string[];
+export declare const FINAL_REPORT_PROMPT: string;
+export interface SubagentParent extends RegistryHost {
     readonly options: AgentSessionOptions;
     readonly manager: SessionManager;
     readonly cwd: string;
     readonly depth: number;
     childBase(): Pick<AgentSessionOptions, "model" | "thinkingLevel" | "activeTools" | "system">;
     /** 子会话的审批事件转发给父会话的订阅者（RPC 客户端 / TUI 据此作答）。 */
-    emit?(event: SessionEvent): void;
+    emit(event: SessionEvent): void;
+    /** [RW-B] 父会话的检查点钩子：子会话的编辑记到父会话当前回合。 */
+    checkpointHooks?(): CheckpointHooks | undefined;
     /** [W3-C1b] 父会话的缓存控制器：汇总子会话的命中与重计费。 */
     readonly cache?: {
         addSubagent(tokens: {
@@ -44,6 +48,7 @@ export interface SubagentParent {
 }
 export interface ChildSession {
     readonly manager: SessionManager;
+    readonly messages: readonly AgentMessage[];
     prompt(text: string): Promise<unknown>;
     abort(): Promise<void>;
     subscribe(listener: (event: SessionEvent) => void): () => void;
@@ -51,4 +56,11 @@ export interface ChildSession {
     getLastAssistantText(): string | null;
     dispose(): Promise<void>;
 }
-export declare function runSubagent(parent: SubagentParent, request: SubagentRequest, pool: SubagentPool, createChild: (options: AgentSessionOptions) => ChildSession): Promise<SubagentResult>;
+/**
+ * 只读子会话的权限管线：plan 模式、规则同父；ask 一律转 deny（只读类型不弹审批）。
+ * 父管线不是 `PermissionPipeline`（宿主 / SDK 自带实现）时退化为「只放行 read 类」。
+ */
+export declare function readOnlyPermission(parent: PermissionPipelineApi | undefined, cwd: string): PermissionPipelineApi;
+export declare function runSubagent(parent: SubagentParent, request: SubagentRequest, _pool: SubagentPool, createChild: (options: AgentSessionOptions) => ChildSession): Promise<SubagentResult>;
+/** ama 自己的子会话 runner（同进程）。 */
+export declare function createAmaRunner(parent: SubagentParent, spec: AmaRunnerSpec, createChild: (options: AgentSessionOptions) => ChildSession): SubagentRunner;