@armadra/agent 0.7.5 → 0.7.6

package/CHANGELOG.md

@@ -5,6 +5,27 @@ English · [简体中文](CHANGELOG.zh-CN.md)
 > This file is in English starting with 0.6.0. Release notes for 0.1 through 0.5.1 are in Chinese in
 > [CHANGELOG.zh-CN.md](CHANGELOG.zh-CN.md). New entries go into both files.
 
+## 0.7.6 (2026-10-10)
+
+### Model efficiency
+
+- **The auto-mode classifier picks a small model on relays and custom providers too**: when the session model inherits an official catalog entry by id (e.g. `packy/deepseek-v4-pro`), the classifier uses the same vendor's catalog `small` model if the provider's model table lists it (`packy/deepseek-v4-flash`); only listed models are used, never synthesized ones. `permission.autoModel` still overrides (#153).
+- **Fork sub-agents are steered back to their task when `task` / `task_ctl` is rejected**: the rejection now says the caller is a forked sub-agent that cannot start sub-agents, asks it to do the sub-task itself, and quotes the first line of its `<task>` instructions (fresh sub-agents keep the old text; the tool list and the first request are unchanged). DeepSeek retest: one run made no `task` call, the other made one and then read the file and reported (#191).
+- **Learned `max_tokens` limits persist across processes**: when an endpoint rejects with a 400 stating its output limit, the limit is now also written to `<dataDir>/models/max-tokens-caps.json` and loaded back on startup, so later processes no longer get the first request rejected once per model (packy `kimi-k2.5`: second process 0 rejections, previously 1). Entries expire after 30 days; delete the file to re-probe.
+- **Warning for a wrong `models[].catalog` reference**: `catalog: "provider/id"` that matches no catalog entry now produces a registry warning (startup header count, `ama models list`, `AMA_LOG`) instead of silently inheriting nothing.
+
+### Sessions
+
+- **Unreadable session images are reported**: when a downgraded image cannot be read back because the session file was changed by another process, the warning now reaches the session log (`ama: [warn] cannot read session entry …` on stderr, filtered by `AMA_LOG`; a notice in the TUI) instead of being dropped. Warnings raised while the file is being opened are buffered and shown once the session is ready (at most 16, the rest counted); the source session of `--fork` reports through the same log.
+- **`subagents.forkMaxContextRatio`**: the share of (window − `compaction.reserveTokens`) above which a fork sub-agent falls back to fresh is now configurable (0.05–0.95, default 0.5, user level only). Built-in types, `general` included, stay fresh by default; docs/agents.md explains the per-turn cost of re-reading the parent context.
+- **Fork sub-agents are told `task` / `task_ctl` are unavailable**: the `<task>` message now lists them and asks not to call them (they stay in the tool list and are still rejected by depth). In two DeepSeek retests the sub-agent still made one rejected `task` call each time.
+- **Background fork tasks report their mode right away**: the `running` result of a background `task` now carries `details.context` (`fork` / `fresh`) once the mode is known; a queued task or one waiting for its worktree still gets it later in `TaskInfo.context`.
+- **Background `bash` job output fits the session result limit in one cut**: `{job, action: "wait" | "output" | "stop"}` now tail-truncates to the same byte limit as foreground `bash` (50 KB or `maxToolResultChars` − 512, whichever is smaller) instead of a fixed 2000 lines / 50 KB that the session then cut again in the middle; the note still gives the shown line count and `Full output: <path>`.
+
+### Checkpoints
+
+- **A slow first shadow snapshot no longer downgrades the session**: the first snapshot (which builds the index) is no longer timed, and the session downgrades to `tools` only after two snapshots in a row exceed 3 seconds (one slow snapshot followed by a normal one keeps shadow-git). The one-time notice now says so (#194).
+
 ## 0.7.5 (2026-10-10)
 
 ### Memory footprint

package/CHANGELOG.zh-CN.md

@@ -4,6 +4,27 @@
 
 > 从 0.6.0 起 [CHANGELOG.md](CHANGELOG.md) 为英文，本文件保留中文记录（0.1–0.5.1 的完整历史在此）。新条目两份都要加。
 
+## 0.7.6（2026-10-10）
+
+### 模型调用效率
+
+- **中转 / 自定义供应商的 auto 分类器也用小模型**：会话模型按 id 继承了官方目录条目时（如 `packy/deepseek-v4-pro`），若该供应商模型表里列有同厂商目录的 `small` 模型（`packy/deepseek-v4-flash`）就用它分类；只认模型表里列出的条目，不用合成模型。`permission.autoModel` 仍优先（#153）。
+- **fork 子 Agent 调 `task` / `task_ctl` 被拒后回到子任务**：拒绝文案说明它是 fork 出的子 Agent、不能再派生，要求自己完成子任务并附 `<task>` 指令首行（fresh 子 Agent 文案不变；工具表与首请求不变）。DeepSeek 复测：一次没调 `task`，另一次调了一次被拒后读文件并给出报告（#191）。
+- **学到的 `max_tokens` 上限跨进程保留**：端点以 400 说出输出上限时，上限同时写入 `<dataDir>/models/max-tokens-caps.json`，启动时载回，之后的进程不再每个模型首个请求被拒一次（packy `kimi-k2.5`：第二个进程 0 次 400，原为 1 次）。条目 30 天过期，删掉该文件即重测。
+- **`models[].catalog` 写错时给 warning**：`catalog: "provider/id"` 不命中任何目录条目时，注册表记一条 warning（启动头部计数、`ama models list`、`AMA_LOG`），不再静默不继承。
+
+### 会话
+
+- **会话图片读不回时有提示**：降级图片因会话文件被其它进程改写而读不回时，告警进会话日志（stderr 一行 `ama: [warn] cannot read session entry …`，受 `AMA_LOG` 过滤；TUI 显示在通知区），不再被丢弃。打开文件期间的告警先缓冲、会话建好时补出（最多 16 条，其余计数）；`--fork` 的源会话走同一日志。
+- **`subagents.forkMaxContextRatio`**：fork 子 Agent 回落为 fresh 的比例（父上一次请求占（窗口 − `compaction.reserveTokens`）的份额）可配置，0.05–0.95，缺省 0.5，只认用户级。内置类型（包括 `general`）仍缺省 fresh；docs/agents.md 说明了每回合重读父上下文的成本。
+- **fork 子 Agent 被告知 `task` / `task_ctl` 不可用**：`<task>` 消息列出这两个工具并要求不要调用（它们仍在工具表里、按深度拒绝）。两次 DeepSeek 复测里子 Agent 仍各调了一次被拒的 `task`。
+- **后台 fork 任务立即给出模式**：后台 `task` 的 `running` 结果在模式已知时带 `details.context`（`fork` / `fresh`）；排队或等待 worktree 的任务仍在之后的 `TaskInfo.context` 里给出。
+- **后台 `bash` 任务输出按会话结果上限一次截到位**：`{job, action: "wait" | "output" | "stop"}` 改为按与前台 `bash` 相同的字节上限（50 KB 与 `maxToolResultChars` − 512 取小）尾截断，不再固定 2000 行 / 50 KB 再被会话层截掉中段；说明行照旧写显示行数与 `Full output: <路径>`。
+
+### 检查点
+
+- **首次影子快照偏慢不再让会话降级**：首次快照（建索引）不计时，之后连续两次快照超过 3 秒才降级为 `tools`（单次偏慢、下一次正常则继续用影子 git）；降级仍只提示一次，文案改为说明是连续两次（#194）。
+
 ## 0.7.5（2026-10-10）
 
 ### 内存占用

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

@@ -4,6 +4,8 @@
  * - 模型：`options.permissionClassifier.model`（config `permission.autoModel`）解析成功就用它；
  *   否则（未配置、找不到；找不到时记一次 warning）[ME-D] 用会话供应商目录里的小模型（目录文件级
  *   `small`，D12；要能找到且有 key），再否则用当前会话模型；选择结果记一次 debug。
+ * - [#153] 中转 / 自定义供应商（没有目录文件）：会话模型按 id 继承的目录条目 → 原厂 `small` →
+ *   本供应商模型表（config `models[]`、发现缓存）里**已列出**的同一条目；不走合成路径。
  * - 请求是**独立**的：只有分类系统提示与一条用户消息，不带会话转录与工具表；`purpose: "classify"`
  *   让会话层缓存包装直接透传（不观测、不暂停 / 触发保温、不成为下一次请求的前缀依据）；
  *   `cacheRetention: "none"`，关闭思考，`maxTokens` 256。

package/dist/agent/session-classifier.js

@@ -4,13 +4,15 @@
  * - 模型：`options.permissionClassifier.model`（config `permission.autoModel`）解析成功就用它；
  *   否则（未配置、找不到；找不到时记一次 warning）[ME-D] 用会话供应商目录里的小模型（目录文件级
  *   `small`，D12；要能找到且有 key），再否则用当前会话模型；选择结果记一次 debug。
+ * - [#153] 中转 / 自定义供应商（没有目录文件）：会话模型按 id 继承的目录条目 → 原厂 `small` →
+ *   本供应商模型表（config `models[]`、发现缓存）里**已列出**的同一条目；不走合成路径。
  * - 请求是**独立**的：只有分类系统提示与一条用户消息，不带会话转录与工具表；`purpose: "classify"`
  *   让会话层缓存包装直接透传（不观测、不暂停 / 触发保温、不成为下一次请求的前缀依据）；
  *   `cacheRetention: "none"`，关闭思考，`maxTokens` 256。
  * - 用量记一条 `usage{kind:"permission_classify"}` 条目：计入 `/session` 费用，不进上下文。
  */
 import { CLASSIFIER_MAX_TOKENS, PermissionClassifier, } from "../permissions/classifier.js";
-import { catalogSmall } from "../ai/providers/catalog.js";
+import { catalogByAlias, catalogSmall } from "../ai/providers/catalog.js";
 export const CLASSIFY_USAGE_KIND = "permission_classify";
 function textOf(message) {
     return message.content
@@ -19,9 +21,28 @@ function textOf(message) {
         .join("")
         .trim();
 }
-/** 会话供应商的目录小模型：能找到且 key 可用（或无需 key）才用。 */
+/** [#153] 会话模型继承的目录条目所属厂商的 `small`，在本供应商模型表里列出的条目 id。 */
+function inferredSmall(core, session) {
+    const hit = catalogByAlias(session.id);
+    if (hit === undefined)
+        return undefined;
+    const origin = hit.ref.slice(0, hit.ref.indexOf("/"));
+    const small = catalogSmall(origin);
+    const target = `${origin}/${small}`;
+    if (small === undefined || hit.ref === target)
+        return undefined;
+    const listed = core.options.providers.get(session.provider)?.models ?? [];
+    return listed.find((m) => {
+        if (m.id === small)
+            return true;
+        const entry = catalogByAlias(m.id);
+        return entry?.ref === target && entry.tier === undefined;
+    })?.id;
+}
+/** 分类用的小模型：会话供应商的目录 small，或 [#153] 推断出的同厂商小模型；能找到且 key 可用（或无需 key）才用。 */
 async function smallModel(core, session) {
-    const small = catalogSmall(session.provider);
+    const own = catalogSmall(session.provider);
+    const small = own === undefined ? inferredSmall(core, session) : own;
     if (small === undefined || small === session.id)
         return undefined;
     const lookup = core.options.providers.findModel(`${session.provider}/${small}`);

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

@@ -20,6 +20,7 @@
  *   工厂在会话构造中途调用：只可读 `core.options / depth / cwd / manager`，不要 emit 或请求模型。
  * - 钩子抛错不影响会话：同步钩子的异常记 warn 日志后忽略；`beforePrompts` / `onAgentSettled`
  *   的异常同样记日志、按「无追加」处理。
+ * - 会话级诊断（#183）：构造时顺带把 `core.manager` 的告警接到 `core.log`（每个会话实例一次）。
  * - `onAgentSettled` 不要等待人工输入（计划审批等）：需要等待的流程自行异步进行，之后用
  *   `prompt / followUp` 开新回合。
  */

package/dist/agent/session-extensions.js

@@ -20,6 +20,7 @@
  *   工厂在会话构造中途调用：只可读 `core.options / depth / cwd / manager`，不要 emit 或请求模型。
  * - 钩子抛错不影响会话：同步钩子的异常记 warn 日志后忽略；`beforePrompts` / `onAgentSettled`
  *   的异常同样记日志、按「无追加」处理。
+ * - 会话级诊断（#183）：构造时顺带把 `core.manager` 的告警接到 `core.log`（每个会话实例一次）。
  * - `onAgentSettled` 不要等待人工输入（计划审批等）：需要等待的流程自行异步进行，之后用
  *   `prompt / followUp` 开新回合。
  */
@@ -36,6 +37,8 @@ export class SessionExtensions {
                 list.push(extension);
         }
         this.list = list;
+        // 会话级诊断（#183）：manager 的告警（图片读不回）走会话日志；动态读 options.log，TUI 换掉也生效
+        core.manager.setWarn((message) => core.log("warn", message));
     }
     get size() {
         return this.list.length;

package/dist/agent/session-subagent.js

@@ -137,7 +137,9 @@ async function startAmaChild(parent, spec, createChild, run) {
     }
     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;
+    // #149：比例来自 `subagents.forkMaxContextRatio`（注册表环境里的整段配置）
+    const ratio = subagentRegistryFor(parent).env.modelConfig?.subagents?.forkMaxContextRatio;
+    const plan = wanted ? forkPlan(parent, spec, model, thinkingLevel, ratio) : 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;
@@ -149,6 +151,11 @@ async function startAmaChild(parent, spec, createChild, run) {
     // 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));
+    // #150：<task> 里也列出按深度拒绝的 task / task_ctl（执行层的拒绝文案不变）
+    const briefUnavailable = [
+        ...unavailable,
+        ...PARENT_ONLY_TOOLS.filter((name) => inherited.includes(name)),
+    ];
     const options = {
         ...parent.options,
         ...base,
@@ -252,7 +259,7 @@ async function startAmaChild(parent, spec, createChild, run) {
         : forkBrief({
             prompt: run.prompt,
             role: spec.agent.prompt,
-            unavailable,
+            unavailable: briefUnavailable,
             ...(spec.isolated ? { worktree: { cwd: spec.cwd, parentCwd: parent.cwd } } : {}),
         });
     let current = runOnce(first, spec.origin);

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

@@ -18,7 +18,11 @@ export type BackgroundReason = "user" | "timeout" | "host";
 export type BackgroundSetting = "auto" | "always" | "never";
 /** `auto`：交互 / RPC / ACP 缺省后台，`-p`（无人值守）缺省前台。 */
 export declare function resolveTaskBackground(setting: BackgroundSetting | undefined, unattended: boolean): boolean;
-export declare function startedResult(record: TaskRecord, outputFile?: string): SubagentResult;
+/**
+ * 直接后台的工具结果。`settle`（任务的运行 promise）给出时先等一个宏任务：ama 子会话在第一个
+ * await 之前就发出 `context` 事件，池有空位时此刻模式已知；排队或 worktree 隔离未就绪时不带。
+ */
+export declare function startedResult(record: TaskRecord, outputFile?: string, settle?: Promise<unknown>): Promise<SubagentResult>;
 export declare function backgroundedResult(record: TaskRecord, reason: BackgroundReason, afterMs: number, outputFile?: string): SubagentResult;
 /** 前台任务的等待者：`resolve` 让工具调用先返回，`detachParent` 解绑父 signal 与进度回调。 */
 export declare function foregroundWaiter(detachParent: () => void): {

package/dist/agent/subagent-background.js

@@ -32,9 +32,21 @@ function runningResult(record, text, outputFile) {
     };
     if (outputFile !== undefined)
         result.outputFile = outputFile;
+    // #156：fork / fresh 已定时带上实际模式（与完成结果的 details.context 同源）
+    if (record.info.context !== undefined)
+        result.context = record.info.context;
     return result;
 }
-export function startedResult(record, outputFile) {
+/**
+ * 直接后台的工具结果。`settle`（任务的运行 promise）给出时先等一个宏任务：ama 子会话在第一个
+ * await 之前就发出 `context` 事件，池有空位时此刻模式已知；排队或 worktree 隔离未就绪时不带。
+ */
+export async function startedResult(record, outputFile, settle) {
+    if (settle !== undefined)
+        await Promise.race([
+            settle.catch(() => undefined),
+            new Promise((resolve) => setImmediate(resolve)),
+        ]);
     return runningResult(record, startedText(record.info.taskId, record.agent.name), outputFile);
 }
 export function backgroundedResult(record, reason, afterMs, outputFile) {

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

@@ -5,7 +5,7 @@
  *   同一条 assistant 里并行的多个 fork 任务共享同一个 fork 点。
  * - `forkPlan`：满足条件时用 `SessionManager.fork(entryId, { head })` 复制分支，`head` 是
  *   `custom{ama.task, context:"fork", forkedFrom}`（子会话首条仍是 `ama.task`）；否则给出回落原因：
- *   与父不同的模型 / 思考级别、父还没有真实请求、父上一次请求超过 `FORK_MAX_CONTEXT_RATIO` ×
+ *   与父不同的模型 / 思考级别、父还没有真实请求、父上一次请求超过 `subagents.forkMaxContextRatio`（缺省 0.5）×
  *  （窗口 − reserveTokens）、找不到发起调用的 assistant。续聊与 resume 不经过这里（照原文件重开）。
  * - `forkBrief`：角色说明 + 任务合成一条 user 消息（固定英文），追加在继承的历史之后；子会话不写
  *   `role` 节，工具表与父逐字节相同，类型限制的工具在执行层拒绝（`unavailableTools`）。
@@ -16,8 +16,13 @@ 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。 */
+/**
+ * 父上一次请求的输入 token 超过（子模型窗口 − reserveTokens）的这个比例时回落 fresh；
+ * 缺省值，可由 `subagents.forkMaxContextRatio` 覆盖（#149）。
+ */
 export declare const FORK_MAX_CONTEXT_RATIO = 0.5;
+/** 配置的比例：非有限数或不在 (0, 1) 内时用缺省。 */
+export declare function forkRatio(ratio: number | undefined): number;
 export type ContextMode = "fork" | "fresh";
 /** 请求的上下文模式：调用参数 > 类型 frontmatter > `fresh`。 */
 export declare function requestedContext(request: Pick<SubagentRequest, "context">, agent: Pick<AgentDefinition, "context">): ContextMode;
@@ -36,7 +41,7 @@ export interface ForkParent {
 export interface ForkSpec {
     taskId: string;
     agent: Pick<AgentDefinition, "name">;
-    request: Pick<SubagentRequest, "parentToolCallId" | "description">;
+    request: Pick<SubagentRequest, "parentToolCallId" | "description" | "prompt">;
     /** 子会话 cwd（隔离时是 worktree）。 */
     cwd: string;
 }
@@ -48,9 +53,9 @@ export type ForkPlan = {
 };
 /**
  * D3 的回落条件依次检查，全部通过才复制分支（复制即落盘：父有文件时子会话文件立即写出）。
- * `model` / `thinking` 是子会话按类型与参数解析出的值。
+ * `model` / `thinking` 是子会话按类型与参数解析出的值；`ratio` 是 `subagents.forkMaxContextRatio`。
  */
-export declare function forkPlan(parent: ForkParent, spec: ForkSpec, model: Model, thinking: ModelThinkingLevel): ForkPlan;
+export declare function forkPlan(parent: ForkParent, spec: ForkSpec, model: Model, thinking: ModelThinkingLevel, ratio?: number): ForkPlan;
 export interface ForkBriefInput {
     prompt: string;
     /** 类型正文（不含通用前言：这里的首句已说明子 Agent 身份）。 */

package/dist/agent/subagent-fork.js

@@ -5,14 +5,24 @@
  *   同一条 assistant 里并行的多个 fork 任务共享同一个 fork 点。
  * - `forkPlan`：满足条件时用 `SessionManager.fork(entryId, { head })` 复制分支，`head` 是
  *   `custom{ama.task, context:"fork", forkedFrom}`（子会话首条仍是 `ama.task`）；否则给出回落原因：
- *   与父不同的模型 / 思考级别、父还没有真实请求、父上一次请求超过 `FORK_MAX_CONTEXT_RATIO` ×
+ *   与父不同的模型 / 思考级别、父还没有真实请求、父上一次请求超过 `subagents.forkMaxContextRatio`（缺省 0.5）×
  *  （窗口 − reserveTokens）、找不到发起调用的 assistant。续聊与 resume 不经过这里（照原文件重开）。
  * - `forkBrief`：角色说明 + 任务合成一条 user 消息（固定英文），追加在继承的历史之后；子会话不写
  *   `role` 节，工具表与父逐字节相同，类型限制的工具在执行层拒绝（`unavailableTools`）。
  */
+import { FORK_CUSTOM_TYPE, taskLine } from "../tools/task.js";
 import { DEFAULT_COMPACTION_SETTINGS } from "./session-compaction.js";
-/** 父上一次请求的输入 token 超过（子模型窗口 − reserveTokens）的这个比例时回落 fresh。 */
+/**
+ * 父上一次请求的输入 token 超过（子模型窗口 − reserveTokens）的这个比例时回落 fresh；
+ * 缺省值，可由 `subagents.forkMaxContextRatio` 覆盖（#149）。
+ */
 export const FORK_MAX_CONTEXT_RATIO = 0.5;
+/** 配置的比例：非有限数或不在 (0, 1) 内时用缺省。 */
+export function forkRatio(ratio) {
+    return ratio !== undefined && Number.isFinite(ratio) && ratio > 0 && ratio < 1
+        ? ratio
+        : FORK_MAX_CONTEXT_RATIO;
+}
 const TASK_CUSTOM_TYPE = "ama.task";
 /** 请求的上下文模式：调用参数 > 类型 frontmatter > `fresh`。 */
 export function requestedContext(request, agent) {
@@ -27,9 +37,9 @@ export function forkPoint(branch, parentToolCallId) {
 }
 /**
  * D3 的回落条件依次检查，全部通过才复制分支（复制即落盘：父有文件时子会话文件立即写出）。
- * `model` / `thinking` 是子会话按类型与参数解析出的值。
+ * `model` / `thinking` 是子会话按类型与参数解析出的值；`ratio` 是 `subagents.forkMaxContextRatio`。
  */
-export function forkPlan(parent, spec, model, thinking) {
+export function forkPlan(parent, spec, model, thinking, ratio) {
     const base = parent.childBase();
     if (model.provider !== base.model.provider || model.id !== base.model.id)
         return { fallback: `model ${model.provider}/${model.id} differs from the parent` };
@@ -40,7 +50,7 @@ export function forkPlan(parent, spec, model, thinking) {
         return { fallback: "the parent has not sent a request yet" };
     const reserve = parent.options.compaction?.reserveTokens ?? DEFAULT_COMPACTION_SETTINGS.reserveTokens;
     const window = model.contextWindow;
-    const limit = window === undefined ? Infinity : FORK_MAX_CONTEXT_RATIO * Math.max(0, window - reserve);
+    const limit = window === undefined ? Infinity : forkRatio(ratio) * Math.max(0, window - reserve);
     if (last.promptTokens > limit)
         return { fallback: `parent context ${last.promptTokens} tokens exceeds ${Math.floor(limit)}` };
     const forkedFrom = forkPoint(parent.manager.branch(), spec.request.parentToolCallId);
@@ -63,6 +73,12 @@ export function forkPlan(parent, spec, model, thinking) {
             },
         },
     });
+    // #191：fork 标记（不进上下文）；复制来的父 `ama.task` 快照可能更晚，故不复用那个类型
+    manager.append({
+        type: "custom",
+        customType: FORK_CUSTOM_TYPE,
+        data: { taskLine: taskLine(spec.request.prompt) },
+    });
     return { manager, forkedFrom };
 }
 /** fork 子会话的首条 user 消息（固定英文，发给模型）。 */
@@ -72,7 +88,7 @@ export function forkBrief(input) {
         "You are a sub-agent forked from the conversation above at this point. The main agent cannot " +
             "see your work, only your final reply; do not delegate further. Requests above were for the " +
             "main agent: do only this task. Instructions in this block take precedence over earlier " +
-            "plans or reminders above.",
+            "plans or reminders above. Do not call task or task_ctl.",
     ];
     if (input.worktree !== undefined)
         lines.push(`Working directory for this task: ${input.worktree.cwd}. Relative paths in the ` +

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

@@ -62,7 +62,7 @@ export declare function registryOf(sessionId: string): SubagentRegistry | undefi
 export declare function subagentRegistryFor(host: RegistryHost, env?: SubagentEnvironment): SubagentRegistry;
 export declare class SubagentRegistry implements TaskControl {
     private readonly host;
-    private readonly env;
+    readonly env: SubagentEnvironment;
     readonly catalog: AgentCatalog;
     private readonly pool;
     private readonly tasks;

package/dist/agent/subagent-registry.js

@@ -245,7 +245,7 @@ export class SubagentRegistry {
         const file = this.outputFileFor(record.info.taskId);
         if (background) {
             void running.then((result) => this.notifier.notify(record, result));
-            return Promise.resolve(startedResult(record, file));
+            return startedResult(record, file, running);
         }
         // [W7-B1] 前台：转后台（background()）时等待者先行 resolve，工具调用立即返回
         const { waiter, promise } = foregroundWaiter(() => {

package/dist/agents/catalog.d.ts

@@ -14,6 +14,7 @@ export interface AgentModelConfig {
     agents?: AgentsConfig;
     subagents?: {
         defaultModel?: string;
+        forkMaxContextRatio?: number;
     };
     models?: ModelsConfig;
 }

package/dist/ai/apis/max-tokens.d.ts

@@ -8,6 +8,8 @@
  *   以上限重发一次；之后同一模型的请求直接用上限。Anthropic「输入 + max_tokens 超出上下文」只按这次
  *   的输入算出可用值重发、不记上限；可用值不足 `MIN_OUTPUT_TOKENS` 判为溢出（overflow.ts 认得该文案）。
  *   重发只发生在 `start` 之前，流契约不变（与 `postWithCacheFallback` 同模式，包在它外层）。
+ * - 跨进程：学到的上限经 `onMaxTokensCap` 写进 `<dataDir>/models/max-tokens-caps.json`（30 天），
+ *   组装注册表时载回（providers/max-tokens-cache.ts，#152）。
  */
 import { type PostOptions } from "../http.js";
 import type { Model } from "../types.js";
@@ -19,6 +21,8 @@ export declare const OUTPUT_HEADROOM_TOKENS = 2048;
 export type MaxTokensField = "max_tokens" | "max_completion_tokens" | "max_output_tokens";
 /** `${provider}/${model}` → 已知上限（被动修正时记入，之后的请求直接用）。 */
 export declare const maxTokensCaps: Map<string, number>;
+/** 被动修正学到新上限时通知（数据目录持久化用，max-tokens-cache.ts）；返回取消函数。 */
+export declare function onMaxTokensCap(listener: (key: string, cap: number) => void): () => void;
 type Json = Record<string, unknown>;
 /** 主动收紧后的 max_tokens；`window` 未知或 `fixed`（预算型思考）时返回 requested。 */
 export declare function clampMaxTokens(requested: number, window: number | undefined, estimatedInput: number, fixed: boolean): number;

package/dist/ai/apis/max-tokens.js

@@ -8,6 +8,8 @@
  *   以上限重发一次；之后同一模型的请求直接用上限。Anthropic「输入 + max_tokens 超出上下文」只按这次
  *   的输入算出可用值重发、不记上限；可用值不足 `MIN_OUTPUT_TOKENS` 判为溢出（overflow.ts 认得该文案）。
  *   重发只发生在 `start` 之前，流契约不变（与 `postWithCacheFallback` 同模式，包在它外层）。
+ * - 跨进程：学到的上限经 `onMaxTokensCap` 写进 `<dataDir>/models/max-tokens-caps.json`（30 天），
+ *   组装注册表时载回（providers/max-tokens-cache.ts，#152）。
  */
 import { HttpError, errorText } from "../http.js";
 import { postWithCacheFallback } from "./cache-params.js";
@@ -17,6 +19,12 @@ export const MIN_OUTPUT_TOKENS = 1024;
 export const OUTPUT_HEADROOM_TOKENS = 2048;
 /** `${provider}/${model}` → 已知上限（被动修正时记入，之后的请求直接用）。 */
 export const maxTokensCaps = new Map();
+const capListeners = new Set();
+/** 被动修正学到新上限时通知（数据目录持久化用，max-tokens-cache.ts）；返回取消函数。 */
+export function onMaxTokensCap(listener) {
+    capListeners.add(listener);
+    return () => capListeners.delete(listener);
+}
 /** 主动收紧后的 max_tokens；`window` 未知或 `fixed`（预算型思考）时返回 requested。 */
 export function clampMaxTokens(requested, window, estimatedInput, fixed) {
     if (fixed || window === undefined || !Number.isFinite(window) || window <= 0)
@@ -111,8 +119,11 @@ export async function postWithMaxTokensFallback(model, url, options, field) {
             throw error;
         if (rejection.cap >= sent || !budgetFits(body, rejection.cap))
             throw error;
-        if (!rejection.transient)
+        if (!rejection.transient) {
             maxTokensCaps.set(key, rejection.cap);
+            for (const listener of capListeners)
+                listener(key, rejection.cap);
+        }
         return postWithCacheFallback(model, url, {
             ...options,
             body: withCap(body, field, rejection.cap),

package/dist/ai/providers/enrich.d.ts

@@ -25,6 +25,8 @@ export interface ModelMetadata {
     toolCall?: boolean;
     /** [ME-D] 按 id 继承的内置目录条目 `provider/id`。 */
     catalog?: string;
+    /** 显式 `catalog` / `modelsDev` 引用不命中时的告警（注册表转成 warnings，#154）。 */
+    warnings?: string[];
 }
 export type ModelsDevSource = ModelsDevIndex | (() => ModelsDevIndex | undefined) | undefined;
 /** 惰性取索引：只有真的要补字段时才读缓存（启动时没有自定义模型就不读约 2 MB 的缓存）。 */
@@ -32,9 +34,11 @@ export declare function lazyIndex(source: ModelsDevSource): () => ModelsDevIndex
 type EnrichedEntry = Omit<ModelConfig, "modelsDev" | "channels" | "catalog">;
 /**
  * 补全一个自定义模型条目（config 的 `models[]` 或合成的模型）。返回补过字段的条目（不含
- * `modelsDev` / `channels` / `catalog` 这些配置专用键）与每个字段的来源。
+ * `modelsDev` / `channels` / `catalog` 这些配置专用键）与每个字段的来源。显式 `catalog: "provider/id"`
+ * 或 `modelsDev` 引用不命中时记入 `metadata.warnings`（`providerId` 用于告警文案）；写错的 `catalog`
+ * 不回落按 id 继承——用户显式指定，按指定失败处理。
  */
-export declare function enrichEntry(entry: ModelConfig, index: () => ModelsDevIndex | undefined): {
+export declare function enrichEntry(entry: ModelConfig, index: () => ModelsDevIndex | undefined, providerId?: string): {
     entry: EnrichedEntry;
     metadata: ModelMetadata;
 };

package/dist/ai/providers/enrich.js

@@ -79,9 +79,11 @@ function fillLimits(out, hit, sources) {
 }
 /**
  * 补全一个自定义模型条目（config 的 `models[]` 或合成的模型）。返回补过字段的条目（不含
- * `modelsDev` / `channels` / `catalog` 这些配置专用键）与每个字段的来源。
+ * `modelsDev` / `channels` / `catalog` 这些配置专用键）与每个字段的来源。显式 `catalog: "provider/id"`
+ * 或 `modelsDev` 引用不命中时记入 `metadata.warnings`（`providerId` 用于告警文案）；写错的 `catalog`
+ * 不回落按 id 继承——用户显式指定，按指定失败处理。
  */
-export function enrichEntry(entry, index) {
+export function enrichEntry(entry, index, providerId) {
     const { modelsDev, channels: _channels, catalog: _catalog, ...rest } = entry;
     const sources = {};
     for (const field of ENRICHABLE_FIELDS) {
@@ -89,11 +91,16 @@ export function enrichEntry(entry, index) {
     }
     const metadata = { sources, looked: false };
     const out = { ...rest };
+    const warnings = [];
+    const ref = `${providerId ?? "?"}/${entry.id}`;
     const hit = catalogHit(entry);
     if (hit !== undefined) {
         metadata.catalog = hit.ref;
         inheritIntrinsic(out, hit, sources);
     }
+    else if (typeof entry.catalog === "string") {
+        warnings.push(`catalog "${entry.catalog}" for "${ref}" not found; ignored`);
+    }
     const explicit = typeof modelsDev === "string" ? modelsDev : hit?.snapshotRef;
     const lookup = modelsDev !== false && (needsLookup(out) || modelsDev !== undefined);
     const idx = lookup ? index() : undefined;
@@ -127,8 +134,12 @@ export function enrichEntry(entry, index) {
             }
         }
     }
+    if (typeof modelsDev === "string" && metadata.looked && metadata.match === undefined)
+        warnings.push(`modelsDev "${modelsDev}" for "${ref}" not found`);
     if (hit !== undefined && modelsDev !== false)
         fillLimits(out, hit, sources);
+    if (warnings.length > 0)
+        metadata.warnings = warnings;
     return { entry: out, metadata };
 }
 /**

package/dist/ai/providers/max-tokens-cache.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `max_tokens` 上限的跨进程缓存：`<dataDir>/models/max-tokens-caps.json`（#152）。
+ *
+ * 被动修正（apis/max-tokens.ts）学到的 `provider/model` 上限原本只在进程内，重启后每个模型的首个请求仍被
+ * 400 拒一次。这里把它写进数据目录：组装注册表时载回进程内的表（进程内已有的键优先），学到新上限就把文件里
+ * 未过期的条目加上这一条原子写回（临时文件 + 改名；并发进程后写者赢，丢的一条下次再学）。条目 30 天过期，
+ * 过期后重新探测（中转放宽上限时不会一直压低输出）；删掉文件即重测。只存模型引用、上限与时间，没有凭据。
+ */
+export declare const MAX_TOKENS_CACHE_VERSION = 1;
+/** 条目有效期：30 天。 */
+export declare const MAX_TOKENS_CACHE_TTL_MS: number;
+/** 缓存文件位置。 */
+export declare function maxTokensCachePath(dataDir: string): string;
+/** 载入未过期的上限到进程内的表（已有的键不覆盖）；返回载入条数。 */
+export declare function loadMaxTokensCaps(dataDir: string, now?: () => number): number;
+/** 把一条新上限并入文件（顺带清掉过期条目）；写失败不抛（缓存只是省一次 400）。 */
+export declare function recordMaxTokensCap(dataDir: string, key: string, cap: number, now?: () => number): void;
+/**
+ * 载入并订阅：之后学到的上限写回该数据目录。按 `dataDir` 幂等（同一进程重复组装注册表不重复订阅）；
+ * 返回取消函数（取消后可重新 attach）。
+ */
+export declare function attachMaxTokensCache(dataDir: string, now?: () => number): () => void;

package/dist/ai/providers/max-tokens-cache.js

@@ -0,0 +1,95 @@
+/**
+ * `max_tokens` 上限的跨进程缓存：`<dataDir>/models/max-tokens-caps.json`（#152）。
+ *
+ * 被动修正（apis/max-tokens.ts）学到的 `provider/model` 上限原本只在进程内，重启后每个模型的首个请求仍被
+ * 400 拒一次。这里把它写进数据目录：组装注册表时载回进程内的表（进程内已有的键优先），学到新上限就把文件里
+ * 未过期的条目加上这一条原子写回（临时文件 + 改名；并发进程后写者赢，丢的一条下次再学）。条目 30 天过期，
+ * 过期后重新探测（中转放宽上限时不会一直压低输出）；删掉文件即重测。只存模型引用、上限与时间，没有凭据。
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { maxTokensCaps, onMaxTokensCap } from "../apis/max-tokens.js";
+export const MAX_TOKENS_CACHE_VERSION = 1;
+/** 条目有效期：30 天。 */
+export const MAX_TOKENS_CACHE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/** 缓存文件位置。 */
+export function maxTokensCachePath(dataDir) {
+    return join(dataDir, "models", "max-tokens-caps.json");
+}
+/** 读文件里未过期的条目；不存在、坏 JSON、版本不符或形状不对的条目一律忽略。 */
+function readEntries(dataDir, now) {
+    const out = new Map();
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(maxTokensCachePath(dataDir), "utf8"));
+    }
+    catch {
+        return out;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return out;
+    const file = parsed;
+    if (file.version !== MAX_TOKENS_CACHE_VERSION)
+        return out;
+    if (typeof file.caps !== "object" || file.caps === null)
+        return out;
+    for (const [key, value] of Object.entries(file.caps)) {
+        if (typeof value !== "object" || value === null)
+            continue;
+        const { cap, learnedAt } = value;
+        if (typeof cap !== "number" || !Number.isInteger(cap) || cap < 1)
+            continue;
+        if (typeof learnedAt !== "number" || !Number.isFinite(learnedAt))
+            continue;
+        if (now - learnedAt > MAX_TOKENS_CACHE_TTL_MS)
+            continue;
+        out.set(key, { cap, learnedAt });
+    }
+    return out;
+}
+/** 载入未过期的上限到进程内的表（已有的键不覆盖）；返回载入条数。 */
+export function loadMaxTokensCaps(dataDir, now = Date.now) {
+    let loaded = 0;
+    for (const [key, entry] of readEntries(dataDir, now())) {
+        if (maxTokensCaps.has(key))
+            continue;
+        maxTokensCaps.set(key, entry.cap);
+        loaded++;
+    }
+    return loaded;
+}
+/** 把一条新上限并入文件（顺带清掉过期条目）；写失败不抛（缓存只是省一次 400）。 */
+export function recordMaxTokensCap(dataDir, key, cap, now = Date.now) {
+    const at = now();
+    const entries = readEntries(dataDir, at);
+    entries.set(key, { cap, learnedAt: at });
+    const path = maxTokensCachePath(dataDir);
+    const tmp = `${path}.${process.pid}.tmp`;
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        const caps = Object.fromEntries([...entries].sort(([a], [b]) => (a < b ? -1 : 1)));
+        writeFileSync(tmp, `${JSON.stringify({ version: MAX_TOKENS_CACHE_VERSION, caps }, null, 2)}\n`);
+        renameSync(tmp, path);
+    }
+    catch {
+        // 只读数据目录等：本进程内的表仍有效
+    }
+}
+const attached = new Map();
+/**
+ * 载入并订阅：之后学到的上限写回该数据目录。按 `dataDir` 幂等（同一进程重复组装注册表不重复订阅）；
+ * 返回取消函数（取消后可重新 attach）。
+ */
+export function attachMaxTokensCache(dataDir, now = Date.now) {
+    const existing = attached.get(dataDir);
+    if (existing !== undefined)
+        return existing;
+    loadMaxTokensCaps(dataDir, now);
+    const unsubscribe = onMaxTokensCap((key, cap) => recordMaxTokensCap(dataDir, key, cap, now));
+    const detach = () => {
+        unsubscribe();
+        attached.delete(dataDir);
+    };
+    attached.set(dataDir, detach);
+    return detach;
+}

package/dist/ai/providers/registry.js

@@ -256,9 +256,9 @@ export class ProviderRegistry {
         const channelsOf = (wanted, modelId) => modelChannels(wanted, provider.channels ?? [], provider.defaultChannel ?? "", (name) => this.warn(`model "${id}/${modelId}" channel "${name}" not found; ignored`));
         for (const entry of config.models ?? []) {
             // 模型级 api（第三波 §2.3）：同一中转下不同模型走不同协议；缺省沿用供应商（或渠道）的。
-            const { entry: filled, metadata } = enrichEntry(entry, this.modelsDev);
-            if (typeof entry.modelsDev === "string" && metadata.looked && metadata.match === undefined)
-                this.warn(`modelsDev "${entry.modelsDev}" for "${id}/${entry.id}" not found`);
+            const { entry: filled, metadata } = enrichEntry(entry, this.modelsDev, id);
+            for (const warning of metadata.warnings ?? [])
+                this.warn(warning);
             const model = withCustomDefaults(filled, id, entry.api ?? provider.api);
             // 内置供应商上没写 channels 的模型：定渠道时挂全部渠道（settleBuiltinChannels）
             if (provider.channels !== undefined && (entry.channels !== undefined || !provider.builtin))