@armadra/agent 0.7.2 → 0.7.4

package/dist/agent/session-compaction.js

@@ -18,12 +18,16 @@
  *   （只统计，不写分支、不改请求）；附档一 / 档二阈值。压缩调度本身仍只看 `estimate()`。
  * [W3-C1b] 阈值 / 手动压缩与分支摘要优先走会话前缀续写（缓存控制器给前缀），溢出恢复不走
  * （前缀本身已超窗口）；续写失败回落独立请求并记 warning。
+ * [ME-B] D6 档一 / 档二边界：先干跑档一；裁完仍超预算且续写可用（同模型、前缀成立、缓存未冷）→
+ * 不裁、直接续写摘要（被裁内容本来就进摘要，续写比全价独立请求便宜一个数量级）；裁完够 → 只裁；
+ * 缓存已冷 → 照旧先裁，摘要走独立请求。D16 软窗口：`compaction.contextBudget` 设了时档一 / 档二 /
+ * 熔断 / context_pressure 的窗口取 min(模型窗口, 它)。
  */
 import { AmaError } from "../errors.js";
 import { CompactionBreaker } from "../compaction/breaker.js";
 import { estimateMessageTokens, estimateProjectedTokens, } from "../compaction/estimate.js";
-import { estimatePrefixTokens, withPrefixBaseline } from "../compaction/prefix-estimate.js";
-import { planPrune, prunePolicy } from "../compaction/prune-tier.js";
+import { prefixSystemMessage, withPrefixBaseline } from "../compaction/prefix-estimate.js";
+import { planPrune, prunePolicy, } from "../compaction/prune-tier.js";
 import { createProtection, skillLocations } from "../compaction/protect.js";
 import { buildPostCompactBlock } from "../compaction/post-compact.js";
 import { prepareCompaction, prepareCompactionAt, runCompaction, } from "../compaction/summarize-tier.js";
@@ -37,6 +41,16 @@ export const DEFAULT_COMPACTION_SETTINGS = {
 };
 /** 保留区不超过 (窗口 − 预留) 的 40%，否则小窗口模型上摘要后仍然溢出。 */
 export const KEEP_RECENT_MAX_RATIO = 0.4;
+/**
+ * [ME-B] D16 软窗口：模型窗口与 `compaction.contextBudget` 取小；窗口未知仍 undefined（不压缩）。
+ * `compaction` 是会话选项里展开的 config 段（`contextBudget` 不在 CompactionSettings 类型上）。
+ */
+export function effectiveWindow(contextWindow, compaction) {
+    const budget = compaction?.contextBudget;
+    if (contextWindow === undefined || budget === undefined)
+        return contextWindow;
+    return Math.min(contextWindow, budget);
+}
 /** Hook additionalContext 的 custom 类型（与 UserPromptSubmit 的相同）。 */
 const HOOK_CONTEXT_CUSTOM_TYPE = "ama.hook_context";
 export class CompactionController {
@@ -56,14 +70,18 @@ export class CompactionController {
             this.pruneConfig.prune = extra.prune;
         if (extra.pruneExclude !== undefined)
             this.pruneConfig.pruneExclude = extra.pruneExclude;
-        this.breaker = new CompactionBreaker(this.settings.enabled, core.model().contextWindow);
+        this.breaker = new CompactionBreaker(this.settings.enabled, this.window());
+    }
+    /** 档一 / 档二 / 熔断用的窗口（软窗口生效后的值）。 */
+    window() {
+        return effectiveWindow(this.core.model().contextWindow, this.settings);
     }
     get isCompacting() {
         return this.compacting;
     }
     /** 模型或开关变化后调用。 */
     refresh() {
-        this.breaker.configure(this.settings.enabled, this.core.model().contextWindow);
+        this.breaker.configure(this.settings.enabled, this.window());
     }
     setAuto(enabled) {
         this.settings = { ...this.settings, enabled };
@@ -96,17 +114,10 @@ export class CompactionController {
     }
     /** 将要发送的系统提示 + 工具声明的估算（与首条 system 消息同样装配，不落盘）。 */
     prefixTokens() {
-        const core = this.core;
-        const tools = core
-            .activeToolNames()
-            .map((name) => core.activeTool(name))
-            .filter((tool) => tool !== undefined);
-        const system = core.childBase?.().system ?? core.options.system ?? {};
-        const sections = definedSections(assembleSections({ ...system, tools, cwd: core.cwd }));
-        return estimatePrefixTokens(sections, toolDecls(tools));
+        return estimateMessageTokens(pendingPrefixMessage(this.core));
     }
     budget() {
-        const window = this.core.model().contextWindow;
+        const window = this.window();
         return window === undefined ? undefined : Math.max(0, window - this.settings.reserveTokens);
     }
     keepRecent() {
@@ -115,7 +126,10 @@ export class CompactionController {
             return this.settings.keepRecentTokens;
         return Math.max(1, Math.min(this.settings.keepRecentTokens, Math.floor(budget * KEEP_RECENT_MAX_RATIO)));
     }
-    /** 摘要请求的公共选项；`continuation` 时附上会话前缀续写的材料。 */
+    /**
+     * 摘要请求的公共选项；`continuation` 时附上会话前缀续写的材料（传入对象 = 调用方已算好的那份，
+     * 避免重算）。
+     */
     async summarizer(signal, instructions, continuation) {
         const core = this.core;
         const options = {
@@ -127,7 +141,9 @@ export class CompactionController {
             onFallback: (reason) => core.log("warn", `summary by prefix continuation failed (${reason}); used a separate request`),
             onInvalid: (reason) => core.log("warn", `${reason}; kept it after one retry`),
         };
-        if (continuation)
+        if (typeof continuation === "object")
+            options.continuation = continuation;
+        else if (continuation)
             options.continuation = core.cache?.summaryContinuation();
         return options;
     }
@@ -136,10 +152,8 @@ export class CompactionController {
         const budget = this.budget();
         return budget === undefined ? undefined : prunePolicy(budget, this.pruneConfig.prune);
     }
-    /**
-     * 档一；`need` = 清到目标还要省多少（undefined = 全部候选）。返回省下的 token 估算（0 = 未裁）。
-     */
-    prune(policy, need) {
+    /** 档一干跑；`need` = 清到目标还要省多少（undefined = 全部候选）。 */
+    prunePlan(policy, need) {
         const core = this.core;
         const items = buildProjection(core.manager.branch()).items;
         const isProtected = createProtection({
@@ -148,7 +162,10 @@ export class CompactionController {
             exclude: this.pruneConfig.pruneExclude ?? [],
             keepInContext: (name) => core.tool(name)?.annotations?.keepInContext === true,
         });
-        const plan = planPrune(items, { policy, need, outputDir: core.outputDir(), isProtected });
+        return planPrune(items, { policy, need, outputDir: core.outputDir(), isProtected });
+    }
+    /** 档一落盘：写 context_edit 并重载消息。返回省下的 token 估算（0 = 未裁）。 */
+    applyPrune(plan) {
         for (const item of plan.items) {
             this.core.appendEntry({
                 type: "context_edit",
@@ -161,7 +178,10 @@ export class CompactionController {
             this.core.reloadMessages();
         return plan.savedTokens;
     }
-    /** 阈值检查（档一 → 档二）。失败只记录，不打断 run。 */
+    /**
+     * 阈值检查（档一 → 档二，[ME-B] D6）。失败只记录，不打断 run。
+     * 先干跑档一：裁完仍超预算、熔断允许且续写可用 → 跳过裁剪直接续写摘要；否则照旧先裁。
+     */
     async checkThreshold(signal) {
         if (!this.breaker.autoEnabled || this.compacting || signal.aborted)
             return;
@@ -173,17 +193,24 @@ export class CompactionController {
         let tokens = this.estimate().tokens;
         // 缓存已冷（C3）：前缀反正要重写，未到阈值也把候选一次换掉（仍要可省 ≥ clearAtLeast）
         const cold = this.core.cache?.isCold() ?? false;
+        let continuation;
         if (tokens > policy.triggerTokens || cold) {
-            const need = cold ? undefined : tokens - policy.targetTokens;
-            if (this.prune(policy, need) > 0)
+            const plan = this.prunePlan(policy, cold ? undefined : tokens - policy.targetTokens);
+            if (!cold && tokens - plan.savedTokens > budget && this.summaryAllowed(budget))
+                continuation = this.core.cache?.summaryContinuation();
+            if (continuation === undefined && this.applyPrune(plan) > 0)
                 tokens = this.estimate().tokens;
         }
         if (tokens <= budget)
             return;
-        this.breaker.setPrefixOverflow(this.fixedPrefixTokens() > budget);
-        if (!this.breaker.canSummarize())
+        if (!this.summaryAllowed(budget))
             return this.warnBlocked();
-        await this.summarize("threshold", signal);
+        await this.summarize("threshold", signal, undefined, undefined, continuation);
+    }
+    /** 熔断是否允许自动摘要（顺带更新「固定前缀超预算」）。 */
+    summaryAllowed(budget) {
+        this.breaker.setPrefixOverflow(this.fixedPrefixTokens() > budget);
+        return this.breaker.canSummarize();
     }
     /** 回注块（todo、计划、已加载 Skill、最近文件、转录与 outputs 路径；不含文件正文）。 */
     postCompactBlock() {
@@ -256,7 +283,7 @@ export class CompactionController {
     async recoverOverflow(signal) {
         if (!this.settings.enabled)
             return { retry: false, warning: "context overflow: auto-compaction is disabled" };
-        if (this.core.model().contextWindow === undefined) {
+        if (this.window() === undefined) {
             return {
                 retry: false,
                 warning: "context overflow: model has no contextWindow, auto-compaction is off",
@@ -314,7 +341,7 @@ export class CompactionController {
             details: draft.details,
         });
     }
-    async summarize(trigger, signal, instructions, cutAt) {
+    async summarize(trigger, signal, instructions, cutAt, continuation) {
         const core = this.core;
         this.compacting = true;
         core.emit({ type: "compaction_start", trigger });
@@ -366,7 +393,7 @@ export class CompactionController {
         if (plan === undefined)
             return fail("nothing to compact");
         try {
-            const options = await this.summarizer(signal, customInstructions, trigger !== "overflow");
+            const options = await this.summarizer(signal, customInstructions, trigger === "overflow" ? false : (continuation ?? true));
             const draft = await runCompaction(plan, options);
             if (signal.aborted)
                 return fail("aborted", true);
@@ -411,3 +438,16 @@ export class CompactionController {
         }
     }
 }
+/**
+ * 首次请求前将要发送的首条 `system` 消息（系统提示 + 工具声明，与真正发送时同样装配）。只用于统计：
+ * `getStats` 的启动基线与 `/context` 的分类明细共用它，口径一致；不写分支、不改请求体。
+ */
+export function pendingPrefixMessage(core) {
+    const tools = core
+        .activeToolNames()
+        .map((name) => core.activeTool(name))
+        .filter((tool) => tool !== undefined);
+    const system = core.childBase?.().system ?? core.options.system ?? {};
+    const sections = definedSections(assembleSections({ ...system, tools, cwd: core.cwd }));
+    return prefixSystemMessage(sections, toolDecls(tools));
+}

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

@@ -35,6 +35,8 @@ export interface AgentSessionOptions {
     tools?: readonly ToolDefinition[];
     /** 活动集；缺省 = tools 全部。 */
     activeTools?: readonly string[];
+    /** [ME-C0] 留在请求工具表里、执行时拒绝的工具（fork 子会话的 tools / disallowed-tools）。 */
+    unavailableTools?: readonly string[];
     /** 权限管线（B3）；缺省 = 全部放行。 */
     permission?: PermissionPipelineApi;
     /** 审批回答者链：宿主 broker → UI broker；都返回 undefined → deny（无人值守）。 */

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

@@ -12,6 +12,9 @@
  * - 最终失败后若 followUp 队列非空，照常投递。
  * - [W5-H2] 模型回退：可重试错误在 overloaded 时、或重试用尽后，若配置了 `fallbackModel` 就切过去
  *   重试一次本请求（`model_fallback` 事件），回退模型回复后切回主模型；每个周期最多一次。
+ *   [ME-C] overloaded 先快速重试一次（1 s 基数 + 抖动，计一次 attempt），仍失败才回退（D8）。
+ * - [ME-C] 退避取 `retryDelayMs(attempt, settings, 失败消息的 retryAfterMs)`；限流（rate_limited）的
+ *   重试上限 = maxRetries + 2，`auto_retry_start.maxAttempts` 随之。
  * - [W5-H2] 扩展经 `noteSettleWarning` 登记的 warning（预算到限 `limit_reached`）写进本周期的 agent_settled；
  *   `limit_reached:` 开头的错误回复（预算拦下请求）不重试。
  * - [W5-H2] run 带 `warning`（重复调用检测 `repeated_tool_call`）：不跑 Stop Hook，agent_settled 带该 warning。
@@ -19,6 +22,7 @@
 import type { AssistantMessage, ImageBlock, UserMessage } from "../ai/types.js";
 import type { AgentMessage } from "../session/types.js";
 import type { RunOutcome } from "./loop.js";
+import { type FailureKind } from "./retry.js";
 import type { SessionCore } from "./session-core.js";
 import type { CompactionController } from "./session-compaction.js";
 import type { PromptDisposition, RetrySettings } from "./types.js";
@@ -34,6 +38,12 @@ export type RunDecision = {
 } | {
     kind: "retry";
     errorMessage: string;
+    /** [ME-C] 本次失败的种类（决定重试上限）。 */
+    failure?: FailureKind;
+    /** [ME-C] overloaded 回退前的快速重试：1 s 基数。 */
+    quick?: boolean;
+    /** [ME-C] 失败响应的 Retry-After（毫秒）。 */
+    retryAfterMs?: number;
 } | {
     kind: "overflow";
 } | {
@@ -61,6 +71,8 @@ export interface RunCycleDeps {
     afterSettled?(): Promise<void>;
 }
 export declare function decideAfterRun(deps: RunCycleDeps, outcome: RunOutcome, retryAttempt: number, overflowRecovered: boolean, fallbackUsed?: boolean): RunDecision;
+/** [ME-C] overloaded 快速重试的退避基数（设置的基数更小时取设置）。 */
+export declare const QUICK_RETRY_BASE_MS = 1000;
 /** 用 context_edit 把失败尝试（助手消息与其后补的结果）从上下文剔除。 */
 export declare function excludeFailedAttempt(core: SessionCore, failed: AssistantMessage | undefined, reason: "retry" | "overflow"): void;
 export declare function recordAbort(core: SessionCore): void;

package/dist/agent/session-run.js

@@ -12,13 +12,16 @@
  * - 最终失败后若 followUp 队列非空，照常投递。
  * - [W5-H2] 模型回退：可重试错误在 overloaded 时、或重试用尽后，若配置了 `fallbackModel` 就切过去
  *   重试一次本请求（`model_fallback` 事件），回退模型回复后切回主模型；每个周期最多一次。
+ *   [ME-C] overloaded 先快速重试一次（1 s 基数 + 抖动，计一次 attempt），仍失败才回退（D8）。
+ * - [ME-C] 退避取 `retryDelayMs(attempt, settings, 失败消息的 retryAfterMs)`；限流（rate_limited）的
+ *   重试上限 = maxRetries + 2，`auto_retry_start.maxAttempts` 随之。
  * - [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";
+import { classifyFailure, isRetryableKind, maxRetriesFor, retryDelayMs, sleep, } from "./retry.js";
 export const MAX_STOP_HOOK_CONTINUATIONS = 3;
 export const ABORTED_CUSTOM_TYPE = "ama.aborted";
 /** [W5-H2] 预算拦下请求时错误回复的前缀（limits.ts）：判为最终失败，不重试、不回退。 */
@@ -59,17 +62,34 @@ export function decideAfterRun(deps, outcome, retryAttempt, overflowRecovered, f
         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 };
+    const canFallback = isRetryableKind(kind) && !fallbackUsed && fallbackTarget(deps.core) !== undefined;
+    const retry = { kind: "retry", errorMessage, failure: kind };
+    if (last.retryAfterMs !== undefined)
+        retry.retryAfterMs = last.retryAfterMs;
+    if (canFallback && OVERLOADED.test(errorMessage)) {
+        return retryAttempt === 0 && settings.enabled
+            ? { ...retry, quick: true }
+            : { kind: "fallback", errorMessage };
+    }
+    if (isRetryableKind(kind) && settings.enabled && retryAttempt < maxRetriesFor(kind, settings)) {
+        return retry;
     }
     if (canFallback)
         return { kind: "fallback", errorMessage };
     return { kind: "failed", errorMessage };
 }
 const OVERLOADED = /overloaded/i;
+/** [ME-C] overloaded 快速重试的退避基数（设置的基数更小时取设置）。 */
+export const QUICK_RETRY_BASE_MS = 1000;
+/** 本次重试的等待与上限（`auto_retry_start` 的 delayMs / maxAttempts）。 */
+function retryPlan(decision, attempt, settings) {
+    const quickBase = Math.min(QUICK_RETRY_BASE_MS, settings.baseDelayMs);
+    const base = decision.quick === true ? { ...settings, baseDelayMs: quickBase } : settings;
+    return {
+        delayMs: retryDelayMs(decision.quick === true ? 1 : attempt, base, decision.retryAfterMs),
+        maxAttempts: maxRetriesFor(decision.failure ?? "retryable", settings),
+    };
+}
 /** 配置了与当前模型不同、且能找到的回退模型时返回它的引用。 */
 function fallbackTarget(core) {
     const target = core.options.fallbackModel?.trim();
@@ -225,19 +245,18 @@ async function runSettledCycle(deps, prompts, signal) {
             retryAttempt++;
             deps.setRetrying(true);
             excludeFailedAttempt(core, outcome.lastAssistant, "retry");
-            const settings = deps.retry();
-            const delayMs = retryDelayMs(retryAttempt, settings);
+            const { delayMs, maxAttempts } = retryPlan(current, retryAttempt, deps.retry());
             core.emit({
                 type: "auto_retry_start",
                 attempt: retryAttempt,
-                maxAttempts: settings.maxRetries,
+                maxAttempts,
                 delayMs,
                 errorMessage: current.errorMessage,
             });
             void core.runHook("Notification", {
                 notification: {
                     kind: "retry",
-                    message: `retry ${retryAttempt}/${settings.maxRetries}: ${current.errorMessage}`,
+                    message: `retry ${retryAttempt}/${maxAttempts}: ${current.errorMessage}`,
                 },
             });
             try {

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

@@ -11,7 +11,11 @@
  *   声明了 `tools` / `disallowed-tools`（或调用参数给了 `tools`）时工具表才不同。
  * - 只读类型（`permission-mode: plan`）：子会话用一条 plan 模式的权限管线（规则同父），ask 一律转
  *   deny——写类工具与识别不了的 bash 被拒且不弹审批；`inherit` 共用父的管线（不会比父宽）。
- * - 轮数耗尽且最后停在工具结果上：以 `toolChoice:"none"` 再跑一轮要最终报告，状态 `max_turns`。
+ * - 轮数耗尽且最后停在工具结果上：以 `maxTurns: 1` 再跑一轮要最终报告（只靠提示、不发 `toolChoice`，
+ *   [ME-A] D13 请求选项不变才能命中缓存；仍调用工具则结果回落为「没有文本」），状态 `max_turns`。
+ * - [ME-A] `context: "fork"`（D1–D3，subagent-fork.ts）：子会话复制父分支到发起调用的 assistant 之前，
+ *   不写 `role` 节、工具表与父相同、类型限制改由 `unavailableTools` 在执行层拒绝；任务以 `<task>` 消息
+ *   追加在继承的历史之后。不满足条件时回落 fresh（记 info 日志），结果的 `context` 标实际模式。
  * - broker 包一层，请求带 `context{depth, parentToolCallId, taskId}`，审批事件转发到父会话；
  *   [RW-B] 父的检查点钩子（worktree 里运行时不记）；[W3-C1b] 子会话命中与重计费汇总进父。
  * - [W6-A] 句柄外露 `observe` / `entries`（子 Agent 视图跟随）与 `message`（视图里直接发的消息，
@@ -23,6 +27,7 @@ import { SessionManager } from "../session/manager.js";
 import type { AgentMessage } from "../session/types.js";
 import type { MessageOrigin } from "../ai/types.js";
 import type { SubagentRequest, SubagentResult, SubagentRunner } from "../tools/types.js";
+import type { RequestRecord } from "../ai/cache/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";
@@ -47,6 +52,8 @@ export interface SubagentParent extends RegistryHost {
             cacheRead: number;
             prompt: number;
         }, reBilledTokens: number): void;
+        /** [ME-A] 父会话上一次真实请求（fork 的前提与上下文比例）。 */
+        readonly lastTurn?: RequestRecord | undefined;
     };
 }
 export interface ChildSession {

package/dist/agent/session-subagent.js

@@ -11,7 +11,11 @@
  *   声明了 `tools` / `disallowed-tools`（或调用参数给了 `tools`）时工具表才不同。
  * - 只读类型（`permission-mode: plan`）：子会话用一条 plan 模式的权限管线（规则同父），ask 一律转
  *   deny——写类工具与识别不了的 bash 被拒且不弹审批；`inherit` 共用父的管线（不会比父宽）。
- * - 轮数耗尽且最后停在工具结果上：以 `toolChoice:"none"` 再跑一轮要最终报告，状态 `max_turns`。
+ * - 轮数耗尽且最后停在工具结果上：以 `maxTurns: 1` 再跑一轮要最终报告（只靠提示、不发 `toolChoice`，
+ *   [ME-A] D13 请求选项不变才能命中缓存；仍调用工具则结果回落为「没有文本」），状态 `max_turns`。
+ * - [ME-A] `context: "fork"`（D1–D3，subagent-fork.ts）：子会话复制父分支到发起调用的 assistant 之前，
+ *   不写 `role` 节、工具表与父相同、类型限制改由 `unavailableTools` 在执行层拒绝；任务以 `<task>` 消息
+ *   追加在继承的历史之后。不满足条件时回落 fresh（记 info 日志），结果的 `context` 标实际模式。
  * - broker 包一层，请求带 `context{depth, parentToolCallId, taskId}`，审批事件转发到父会话；
  *   [RW-B] 父的检查点钩子（worktree 里运行时不记）；[W3-C1b] 子会话命中与重计费汇总进父。
  * - [W6-A] 句柄外露 `observe` / `entries`（子 Agent 视图跟随）与 `message`（视图里直接发的消息，
@@ -22,6 +26,7 @@ import { PermissionPipeline } from "../permissions/pipeline.js";
 import { SessionManager } from "../session/manager.js";
 import { agentRole } from "../agents/builtin.js";
 import { ZERO_USAGE } from "./loop.js";
+import { forkBrief, forkPlan, requestedContext } from "./subagent-fork.js";
 import { DEFAULT_SUBAGENT_CONCURRENCY, SubagentPool, TASK_CUSTOM_TYPE, subagentRegistryFor, } from "./subagent-registry.js";
 export { DEFAULT_SUBAGENT_CONCURRENCY, SubagentPool, TASK_CUSTOM_TYPE };
 export const DEFAULT_SUBAGENT_MAX_TURNS = 30;
@@ -130,22 +135,29 @@ async function startAmaChild(parent, spec, createChild, run) {
             throw new AmaError("model_not_found", `unknown model ${spec.modelRef}`);
         model = lookup.model;
     }
-    const manager = childManager(parent, spec);
+    const thinkingLevel = spec.request.thinkingLevel ?? spec.agent.thinking ?? base.thinkingLevel ?? "off";
+    const wanted = spec.resumeFile === undefined && requestedContext(spec.request, spec.agent) === "fork";
+    const plan = wanted ? forkPlan(parent, spec, model, thinkingLevel) : undefined;
+    if (plan !== undefined && "fallback" in plan)
+        parent.log("info", `task ${spec.taskId}: fork falls back to fresh (${plan.fallback})`);
+    const forked = plan !== undefined && "manager" in plan ? plan.manager : undefined;
+    const mode = !wanted ? undefined : forked ? "fork" : "fresh";
+    const manager = forked ?? childManager(parent, spec);
     const checkpointHooks = spec.isolated ? undefined : parent.checkpointHooks?.();
-    let finalRound = false;
-    const finalRoundExtension = () => ({
-        id: "ama.subagent-final-round",
-        wrapStream: (stream) => (m, context, options) => stream(m, context, finalRound ? { ...options, toolChoice: "none" } : options),
-    });
     const maxTurns = spec.request.maxTurns ?? spec.agent.maxTurns ?? DEFAULT_SUBAGENT_MAX_TURNS;
+    const allowed = childToolNames(parent, spec, base.activeTools);
+    // fork：工具表 = 父活动集（前缀不变），类型限制的工具在执行层拒绝
+    const inherited = base.activeTools ?? (parent.options.tools ?? []).map((tool) => tool.name);
+    const unavailable = inherited.filter((name) => !allowed.includes(name) && !PARENT_ONLY_TOOLS.includes(name));
     const options = {
         ...parent.options,
         ...base,
-        system: { ...base.system, role: agentRole(spec.agent) },
+        // fork：系统提示与父相同（base.system，不加 role 节）
+        ...(forked === undefined ? { system: { ...base.system, role: agentRole(spec.agent) } } : {}),
         sessionManager: manager,
         model,
-        thinkingLevel: spec.request.thinkingLevel ?? spec.agent.thinking ?? base.thinkingLevel ?? "off",
-        activeTools: childToolNames(parent, spec, base.activeTools),
+        thinkingLevel,
+        ...(forked === undefined ? { activeTools: allowed } : {}),
         brokers: brokersForChild(parent.options.brokers, {
             depth: parent.depth + 1,
             parentToolCallId: spec.request.parentToolCallId,
@@ -154,8 +166,9 @@ async function startAmaChild(parent, spec, createChild, run) {
         depth: parent.depth + 1,
         maxTurns,
         subagents: false,
-        extensions: [...(parent.options.extensions ?? []), finalRoundExtension],
     };
+    if (forked !== undefined && unavailable.length > 0)
+        options.unavailableTools = [...(parent.options.unavailableTools ?? []), ...unavailable];
     delete options.checkpointHooks;
     if (checkpointHooks !== undefined)
         options.checkpointHooks = checkpointHooks;
@@ -182,6 +195,8 @@ async function startAmaChild(parent, spec, createChild, run) {
         else if (event.type === "permission_request" || event.type === "permission_resolved")
             parent.emit(event);
     });
+    if (mode !== undefined)
+        run.onEvent({ type: "context", mode });
     const onAbort = () => void child.abort();
     run.signal.addEventListener("abort", onAbort, { once: true });
     let billed = { cacheRead: 0, prompt: 0, reBilled: 0 };
@@ -212,7 +227,6 @@ async function startAmaChild(parent, spec, createChild, run) {
         active = false;
         const exhausted = error === undefined && !run.signal.aborted && turns - startTurns >= maxTurns && toolUse;
         if (exhausted) {
-            finalRound = true;
             options.maxTurns = 1;
             try {
                 await child.prompt(FINAL_REPORT_PROMPT);
@@ -221,18 +235,27 @@ async function startAmaChild(parent, spec, createChild, run) {
                 error = caught instanceof Error ? caught.message : String(caught);
             }
             finally {
-                finalRound = false;
                 options.maxTurns = maxTurns;
             }
         }
         const result = collect(child, error, exhausted, run.signal.aborted);
+        if (mode !== undefined)
+            result.context = mode;
         billed = addCache(parent, child.getStats(), billed);
         const file = manager.file();
         if (file !== undefined)
             result.sessionFile = file;
         return result;
     };
-    let current = runOnce(run.prompt, spec.origin);
+    const first = forked === undefined
+        ? run.prompt
+        : forkBrief({
+            prompt: run.prompt,
+            role: spec.agent.prompt,
+            unavailable,
+            ...(spec.isolated ? { worktree: { cwd: spec.cwd, parentCwd: parent.cwd } } : {}),
+        });
+    let current = runOnce(first, spec.origin);
     const handle = {
         id: manager.id,
         model: `${model.provider}/${model.id}`,

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

@@ -4,7 +4,8 @@
  * - `persistMessage`：Agent 的 message_end → 会话条目（LLM 消息 → `message`；custom → `custom_message`）。
  * - `recordModelState`：路径上最近的 model_change / thinking_level_change 与当前不同则补记。
  * - `syncSystemMessage`：目标系统提示 + 工具表与转录重放的状态比对，落全量（首条）或补丁；
- *   中途只追加工具时 tools / rules 节保持已发送的文本（前缀稳定，§9.1）。
+ *   对话开始后 tools / rules 节冻结为已发送的文本（[ME-B] D5：工具增删只经请求工具表与尾部提醒体现，
+ *   开头永不改写，§9.1）。
  * - `runHookWithEvents`：调 HookDispatcher（公共字段按本会话的 depth / sessionId / sessionFile 覆盖），
  *   逐条发 hook_executed；Hook 自身出错记 warning、按无决策处理。
  */
@@ -15,13 +16,18 @@ import type { ToolDefinition } from "../tools/types.js";
 import type { SessionManager } from "../session/manager.js";
 import type { SessionCore } from "./session-core.js";
 import type { SessionEvent } from "./types.js";
-import { type SystemPromptInput } from "./system-prompt.js";
+import { currentSystemState, type SystemPromptInput } from "./system-prompt.js";
 export declare function persistMessage(core: SessionCore, message: AgentMessage): SessionEntry | undefined;
 export declare function recordModelState(core: SessionCore, model: Model, thinkingLevel: ModelThinkingLevel): void;
 /** 落一条 model_change，返回模型引用（`setModel` 发 model_changed 用）。 */
 export declare function appendModelChange(core: SessionCore, model: Model): ModelRef;
 export declare function findModelOrThrow(providers: ProviderRegistryApi, ref: string): Model;
 export declare function syncSystemMessage(core: SessionCore, input: Omit<SystemPromptInput, "tools" | "cwd">, tools: readonly ToolDefinition[]): void;
+/**
+ * 对话开始后保留已发送的 tools / rules 节：新工具的声明经请求工具表末尾追加，移除的工具保留声明、
+ * 尾部提醒「no longer available」，system 文本不变，前缀缓存不失效（设计 §9.1、[ME-B] D5）。
+ */
+export declare function keepSectionsAfterStart(current: NonNullable<ReturnType<typeof currentSystemState>>, sections: Record<string, string>): void;
 export declare function runHookWithEvents(core: Pick<SessionCore, "options" | "emit" | "log" | "depth" | "manager">, event: HookEvent, payload: HookEventPayload, signal?: AbortSignal): Promise<HookOutcome | undefined>;
 /** session_start 事件（bootstrap / SDK 在会话就绪后发一次）。 */
 export declare function sessionStartEvent(manager: SessionManager, reason: "startup" | "resume" | "new" | "fork"): SessionEvent;

package/dist/agent/session-sync.js

@@ -4,7 +4,8 @@
  * - `persistMessage`：Agent 的 message_end → 会话条目（LLM 消息 → `message`；custom → `custom_message`）。
  * - `recordModelState`：路径上最近的 model_change / thinking_level_change 与当前不同则补记。
  * - `syncSystemMessage`：目标系统提示 + 工具表与转录重放的状态比对，落全量（首条）或补丁；
- *   中途只追加工具时 tools / rules 节保持已发送的文本（前缀稳定，§9.1）。
+ *   对话开始后 tools / rules 节冻结为已发送的文本（[ME-B] D5：工具增删只经请求工具表与尾部提醒体现，
+ *   开头永不改写，§9.1）。
  * - `runHookWithEvents`：调 HookDispatcher（公共字段按本会话的 depth / sessionId / sessionFile 覆盖），
  *   逐条发 hook_executed；Hook 自身出错记 warning、按无决策处理。
  */
@@ -71,8 +72,8 @@ export function syncSystemMessage(core, input, tools) {
     recordModelState(core, core.model(), core.thinkingLevel());
     const sections = definedSections(assembleSections({ ...input, tools, cwd: core.cwd }));
     const current = currentSystemState(core.agent.messages);
-    if (current !== undefined)
-        keepSectionsOnToolAppend(current, sections, tools);
+    if (current !== undefined && core.agent.messages.some((message) => message.role !== "system"))
+        keepSectionsAfterStart(current, sections);
     const patch = diffSystem(current, sections, toolDecls(tools));
     if (patch === undefined)
         return;
@@ -80,14 +81,10 @@ export function syncSystemMessage(core, input, tools) {
     core.agent.messages.push(patch);
 }
 /**
- * 会话中途只**追加**工具（宿主晚注册、setActiveTools 加名字）时，保留已发送的 tools / rules 节：
- * 新工具的声明经请求工具表末尾追加，system 文本不变，前缀缓存不失效（设计 §9.1）。
- * 有工具被移除时照常重写这两节。
+ * 对话开始后保留已发送的 tools / rules 节：新工具的声明经请求工具表末尾追加，移除的工具保留声明、
+ * 尾部提醒「no longer available」，system 文本不变，前缀缓存不失效（设计 §9.1、[ME-B] D5）。
  */
-function keepSectionsOnToolAppend(current, sections, tools) {
-    const now = new Set(tools.map((tool) => tool.name));
-    if (current.tools.some((tool) => !now.has(tool.name)))
-        return;
+export function keepSectionsAfterStart(current, sections) {
     for (const name of ["tools", "rules"]) {
         const sent = current.sections[name];
         if (sent === undefined)

package/dist/agent/session-tools.js

@@ -16,6 +16,7 @@ import { previewAction } from "../permissions/preview.js";
 import { PermissionPipeline } from "../permissions/pipeline.js";
 import { classifierRequest } from "./session-classifier.js";
 import { runSingleToolCall } from "./tool-runner.js";
+import { toolUnavailableText } from "./tool-availability.js";
 /** 外层是这个工具时，嵌套调用的 Hook 输入带 `viaCodemode: true`。 */
 const CODEMODE_TOOL_NAME = "codemode";
 function textOf(content) {
@@ -128,8 +129,8 @@ function safePreview(core, request) {
 }
 export async function gateToolCall(core, call, ctx) {
     const tool = ctx.tool;
-    if (tool === undefined)
-        return { block: true, reason: `Tool ${call.name} not found` };
+    if (tool === undefined || core.options.unavailableTools?.includes(call.name) === true)
+        return { block: true, reason: toolUnavailableText(call.name) };
     let input = call.arguments;
     let replaced = false;
     let hookDecision;

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

@@ -0,0 +1,67 @@
+/**
+ * fork 式子 Agent（docs/model-efficiency-plan.md §2.1，D1–D3）。[ME-A]
+ *
+ * - fork 点 = 发出本次 `task` 调用的那条 assistant **之前一条**条目（= 父会话上一次真实请求的转录）；
+ *   同一条 assistant 里并行的多个 fork 任务共享同一个 fork 点。
+ * - `forkPlan`：满足条件时用 `SessionManager.fork(entryId, { head })` 复制分支，`head` 是
+ *   `custom{ama.task, context:"fork", forkedFrom}`（子会话首条仍是 `ama.task`）；否则给出回落原因：
+ *   与父不同的模型 / 思考级别、父还没有真实请求、父上一次请求超过 `FORK_MAX_CONTEXT_RATIO` ×
+ *  （窗口 − reserveTokens）、找不到发起调用的 assistant。续聊与 resume 不经过这里（照原文件重开）。
+ * - `forkBrief`：角色说明 + 任务合成一条 user 消息（固定英文），追加在继承的历史之后；子会话不写
+ *   `role` 节，工具表与父逐字节相同，类型限制的工具在执行层拒绝（`unavailableTools`）。
+ */
+import type { Model, ModelThinkingLevel } from "../ai/types.js";
+import type { AgentDefinition } from "../agents/types.js";
+import type { SessionManager } from "../session/manager.js";
+import type { SessionEntry } from "../session/types.js";
+import type { SubagentRequest } from "../tools/types.js";
+import type { AgentSessionOptions } from "./session-core.js";
+/** 父上一次请求的输入 token 超过（子模型窗口 − reserveTokens）的这个比例时回落 fresh。 */
+export declare const FORK_MAX_CONTEXT_RATIO = 0.5;
+export type ContextMode = "fork" | "fresh";
+/** 请求的上下文模式：调用参数 > 类型 frontmatter > `fresh`。 */
+export declare function requestedContext(request: Pick<SubagentRequest, "context">, agent: Pick<AgentDefinition, "context">): ContextMode;
+/** 父分支里发出 `parentToolCallId` 的 assistant 之前一条条目的 id；找不到（或它是首条）返回 undefined。 */
+export declare function forkPoint(branch: readonly SessionEntry[], parentToolCallId: string): string | undefined;
+export interface ForkParent {
+    readonly manager: SessionManager;
+    readonly options: Pick<AgentSessionOptions, "compaction">;
+    readonly cache?: {
+        readonly lastTurn?: {
+            readonly promptTokens: number;
+        } | undefined;
+    };
+    childBase(): Pick<AgentSessionOptions, "model" | "thinkingLevel">;
+}
+export interface ForkSpec {
+    taskId: string;
+    agent: Pick<AgentDefinition, "name">;
+    request: Pick<SubagentRequest, "parentToolCallId" | "description">;
+    /** 子会话 cwd（隔离时是 worktree）。 */
+    cwd: string;
+}
+export type ForkPlan = {
+    manager: SessionManager;
+    forkedFrom: string;
+} | {
+    fallback: string;
+};
+/**
+ * D3 的回落条件依次检查，全部通过才复制分支（复制即落盘：父有文件时子会话文件立即写出）。
+ * `model` / `thinking` 是子会话按类型与参数解析出的值。
+ */
+export declare function forkPlan(parent: ForkParent, spec: ForkSpec, model: Model, thinking: ModelThinkingLevel): ForkPlan;
+export interface ForkBriefInput {
+    prompt: string;
+    /** 类型正文（不含通用前言：这里的首句已说明子 Agent 身份）。 */
+    role: string;
+    /** 不可用（执行层拒绝）的工具名。 */
+    unavailable: readonly string[];
+    /** 隔离运行时：子会话 cwd 与父 cwd。 */
+    worktree?: {
+        cwd: string;
+        parentCwd: string;
+    };
+}
+/** fork 子会话的首条 user 消息（固定英文，发给模型）。 */
+export declare function forkBrief(input: ForkBriefInput): string;