@armadra/agent 0.4.0 → 0.5.1

package/dist/config/checker.js

@@ -0,0 +1,97 @@
+/**
+ * 配置校验的诊断收集器（从 schema.ts 抽出，schema-w5.ts 共用）。[W5-C0]
+ */
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
+export class Checker {
+    diagnostics = [];
+    error(path, message) {
+        this.diagnostics.push({ severity: "error", path, message });
+    }
+    warn(path, message) {
+        this.diagnostics.push({ severity: "warning", path, message });
+    }
+    object(value, path) {
+        if (typeof value === "object" && value !== null && !Array.isArray(value))
+            return true;
+        this.error(path, "应为对象");
+        return false;
+    }
+    /** 未知字段只警告（前向兼容）。 */
+    keys(value, path, allowed) {
+        for (const key of Object.keys(value)) {
+            if (!allowed.includes(key))
+                this.warn(join(path, key), "未知字段，已忽略");
+        }
+    }
+    version(value, path) {
+        if (value["version"] !== 1)
+            this.error(join(path, "version"), "version 必须为 1");
+    }
+    string(value, key, path, required = false) {
+        const v = value[key];
+        if (v === undefined) {
+            if (required)
+                this.error(join(path, key), "缺少必填字符串");
+            return;
+        }
+        if (typeof v !== "string")
+            this.error(join(path, key), "应为字符串");
+    }
+    boolean(value, key, path) {
+        const v = value[key];
+        if (v !== undefined && typeof v !== "boolean")
+            this.error(join(path, key), "应为布尔值");
+    }
+    number(value, key, path, min = 0, max = Number.MAX_SAFE_INTEGER) {
+        const v = value[key];
+        if (v === undefined)
+            return;
+        if (typeof v !== "number" || !Number.isFinite(v)) {
+            this.error(join(path, key), "应为数字");
+        }
+        else if (v < min || v > max) {
+            this.error(join(path, key), `应在 ${min}–${max} 之间`);
+        }
+    }
+    oneOf(value, key, path, choices) {
+        const v = value[key];
+        if (v === undefined)
+            return;
+        if (typeof v !== "string" || !choices.includes(v)) {
+            this.error(join(path, key), `取值应为 ${choices.join(" | ")}`);
+        }
+    }
+    stringArray(value, key, path) {
+        const v = value[key];
+        if (v === undefined)
+            return;
+        if (!Array.isArray(v) || v.some((item) => typeof item !== "string")) {
+            this.error(join(path, key), "应为字符串数组");
+        }
+    }
+    stringRecord(value, key, path) {
+        const v = value[key];
+        if (v === undefined)
+            return;
+        if (!this.object(v, join(path, key)))
+            return;
+        for (const [k, item] of Object.entries(v)) {
+            if (typeof item !== "string")
+                this.error(join(join(path, key), k), "应为字符串");
+        }
+    }
+}
+export function join(path, key) {
+    if (typeof key === "number")
+        return `${path}[${key}]`;
+    return path === "" ? key : `${path}.${key}`;
+}
+export function checkSection(c, config, key, allowed, body) {
+    const section = config[key];
+    if (section === undefined)
+        return;
+    if (!c.object(section, key))
+        return;
+    c.keys(section, key, allowed);
+    body(section, key);
+}

package/dist/config/json-schema.js

@@ -9,7 +9,9 @@ import { WARMING_MODES } from "../ai/cache/types.js";
 import { PERMISSION_MODES_STRICT_FIRST } from "../permissions/types.js";
 import { CONFIG_KEY_DOCS, DYNAMIC_DEFAULTS, defaultFor } from "./key-docs.js";
 import { HOOK_TIMEOUT_MAX_MS, THINKING_LEVELS } from "./schema.js";
-import { CACHE_RETENTIONS, CHANNEL_NAME_PATTERN, CODEMODE_MODES, TOOLS_PRESET_INPUTS, } from "./types.js";
+import { CACHE_RETENTIONS, CHANNEL_NAME_PATTERN, CHECKPOINT_MODES, SANDBOX_ENABLED_MODES, SANDBOX_NETWORK_MODES, CODEMODE_MODES, IMAGE_RESIZE_MODES, PLAN_BASH_MODES_STRICT_FIRST, PLAN_UNATTENDED_MODES, STATUS_LINE_MODES, TOOLS_PRESET_INPUTS, } from "./types.js";
+import { AGENT_ID_PATTERN } from "./schema-w5.js";
+import { AGENTS_RESERVED_KEYS } from "./types-w5.js";
 export const CONFIG_SCHEMA_FILE = "config.schema.json";
 export const CONFIG_SCHEMA_ID = "https://github.com/Owlbay/armadra-agent/config.schema.json";
 const KNOWN_APIS = [
@@ -121,6 +123,42 @@ const provider = object({
     models: { type: "array", items: model("自定义模型（同 id 整条替换）") },
     modelOverrides: { type: "array", items: model("只改已有模型的元数据") },
 });
+// [W5-C0] 第五波的段（规则同 schema-w5.ts）
+const agentEntry = object({
+    maxConcurrent: num(1, 64),
+    maxMode: oneOf(PERMISSION_MODES_STRICT_FIRST),
+    model: str(),
+    env: object({ passthrough: strings }),
+});
+function w5Sections() {
+    return {
+        images: object({ resize: oneOf(IMAGE_RESIZE_MODES) }),
+        plan: object({
+            bash: oneOf(PLAN_BASH_MODES_STRICT_FIRST),
+            directory: str(),
+            unattended: oneOf(PLAN_UNATTENDED_MODES),
+            model: str(),
+            thinkingLevel: oneOf(THINKING_LEVELS),
+        }),
+        agents: object({ maxConcurrent: num(1, 64), sessionBudgetUsd: num(0), dirs: strings }, {
+            additionalProperties: agentEntry,
+            propertyNames: {
+                pattern: `^(${AGENTS_RESERVED_KEYS.join("|")}|${AGENT_ID_PATTERN.source.slice(1, -1)})$`,
+            },
+        }),
+        subagents: object({ maxConcurrent: num(1, 64), maxPending: num(0, 1024), defaultModel: str() }),
+        models: object({ aliases: object({ fast: str(), strong: str() }) }),
+        fallbackModel: str(),
+        limits: object({ maxTurns: num(1), maxCostUsd: num(0) }),
+        reminders: object({
+            todo: bool(),
+            fileChanges: bool(),
+            contextPressure: bool(),
+            budget: bool(),
+        }),
+        todo: object({ reminder: num(0) }),
+    };
+}
 /** 给顶层与各段的键写上 description 与 default（key-docs.ts）；供应商内部不动。 */
 function annotate(properties, prefix = "") {
     for (const [key, shared] of Object.entries(properties)) {
@@ -166,7 +204,16 @@ function buildBaseSchema() {
                 autoModel: str("auto 模式分类器的模型 provider/model；缺省用当前会话模型"),
                 autoSafeCommands: strings,
             }),
-            compaction: object({ enabled: bool(), reserveTokens: num(0), keepRecentTokens: num(0) }),
+            compaction: object({
+                enabled: bool(),
+                reserveTokens: num(0),
+                keepRecentTokens: num(0),
+                prune: object({
+                    keepResults: num(0),
+                    clearAtLeast: { anyOf: [{ const: "auto" }, { type: "number", minimum: 0 }] },
+                }),
+                pruneExclude: strings,
+            }),
             retry: object({
                 enabled: bool(),
                 maxRetries: num(0, 100),
@@ -195,6 +242,8 @@ function buildBaseSchema() {
                 ascii: bool(),
                 compact: bool(),
                 animation: bool(),
+                restoreOnCancel: bool(),
+                statusLine: oneOf(STATUS_LINE_MODES),
             }),
             skills: object({ dirs: strings }),
             cache: object({
@@ -205,6 +254,18 @@ function buildBaseSchema() {
                 warmSubagents: bool(),
             }),
             request: object({ idleTimeoutMs: num(0) }),
+            checkpoints: object({
+                mode: oneOf(CHECKPOINT_MODES),
+                maxFileBytes: num(0),
+                keep: num(1),
+            }),
+            sandbox: object({
+                enabled: oneOf(SANDBOX_ENABLED_MODES),
+                bash: oneOf(SANDBOX_ENABLED_MODES, "bash 经 OS 沙箱运行（缺省 off）"),
+                network: oneOf(SANDBOX_NETWORK_MODES, "bash 沙箱里的网络（缺省 deny）"),
+                writable: { ...strings, description: "bash 沙箱追加的可写目录（绝对路径或 ~/…）" },
+            }),
+            ...w5Sections(),
         }),
         required: ["version"],
     };

package/dist/config/key-docs.js

@@ -12,7 +12,7 @@
 import { DEFAULT_IDLE_TIMEOUT_MS } from "../ai/http.js";
 import { DEFAULT_INLINE_BUDGET } from "../codemode/declarations.js";
 import { DEFAULT_CONFIG, mergeConfig } from "./merge.js";
-import { DEFAULT_CACHE_CONFIG } from "./types.js";
+import { DEFAULT_CACHE_CONFIG, DEFAULT_CHECKPOINTS_CONFIG } from "./types.js";
 /** 代码里生效、但 DEFAULT_CONFIG 不写的缺省（写进去会改变合并结果或 `config.codemode` 的有无）。 */
 const IMPLICIT_DEFAULTS = {
     providers: {},
@@ -21,7 +21,17 @@ const IMPLICIT_DEFAULTS = {
     codemode: { inlineBudget: DEFAULT_INLINE_BUDGET, requireStrict: false },
     cache: { ...DEFAULT_CACHE_CONFIG },
     request: { idleTimeoutMs: DEFAULT_IDLE_TIMEOUT_MS },
-    ui: { compact: false, animation: true },
+    ui: { compact: false, animation: true, restoreOnCancel: true },
+    checkpoints: { ...DEFAULT_CHECKPOINTS_CONFIG },
+    sandbox: { enabled: "auto", bash: "off", network: "deny", writable: [] },
+    // [W5-C0] 第五波键的缺省（行为由各批次实现）
+    compaction: { prune: { keepResults: 5, clearAtLeast: "auto" }, pruneExclude: [] },
+    images: { resize: "auto" },
+    plan: { bash: "readonly", unattended: "stop" },
+    agents: { maxConcurrent: 3, dirs: [] },
+    subagents: { maxConcurrent: 4, maxPending: 16 },
+    reminders: { todo: true, fileChanges: true, contextPressure: true, budget: true },
+    todo: { reminder: 10 },
 };
 /** 全部有固定缺省值的键（展示用；运行时仍以 DEFAULT_CONFIG 合并）。 */
 export const DISPLAY_DEFAULTS = Object.freeze(mergeConfig(DEFAULT_CONFIG, IMPLICIT_DEFAULTS));
@@ -32,6 +42,18 @@ export const DYNAMIC_DEFAULTS = Object.freeze({
     "permission.autoModel": "当前会话模型",
     "codemode.mode": "跟随预设",
     "ui.ascii": "自动检测",
+    // [W5-C0]
+    "ui.statusLine": "独立终端 full，嵌入宿主（有 profile）compact",
+    "plan.directory": "<数据目录>/plans",
+    "plan.model": "不设：沿用当前模型",
+    "plan.thinkingLevel": "不设：沿用当前思考强度",
+    "agents.sessionBudgetUsd": "不设：不限",
+    "subagents.defaultModel": "不设：继承父会话模型",
+    "models.aliases.fast": "不设：fast 按 inherit 处理",
+    "models.aliases.strong": "不设：strong 按 inherit 处理",
+    fallbackModel: "不设：不回退",
+    "limits.maxTurns": "不设：不限",
+    "limits.maxCostUsd": "不设：不限",
 });
 /** 键路径 → 说明（段落本身也有一条）。 */
 export const CONFIG_KEY_DOCS = Object.freeze({
@@ -51,13 +73,17 @@ export const CONFIG_KEY_DOCS = Object.freeze({
     "compaction.enabled": "上下文接近上限时自动压缩",
     "compaction.reserveTokens": "为回复预留的 token；剩余不足时触发压缩",
     "compaction.keepRecentTokens": "压缩时原样保留的最近消息 token",
+    "compaction.prune": "档一裁剪（旧工具结果换成占位）；只认用户级（第五波 W5-H1 起生效）",
+    "compaction.prune.keepResults": "保留最近 N 个工具结果不裁",
+    "compaction.prune.clearAtLeast": "一次至少能省这么多 token 才裁（避免频繁打断缓存）；auto = max(20000, 0.1 × 上下文预算)",
+    "compaction.pruneExclude": "不被档一裁剪的工具名；只认用户级（第五波 W5-H1 起生效）",
     retry: "请求失败重试",
     "retry.enabled": "可重试的错误（限流、服务端错误、连接中断等）自动重试",
     "retry.maxRetries": "最多重试次数",
     "retry.baseDelayMs": "首次重试等待（毫秒，指数退避；有 Retry-After 时按它）",
     "retry.maxDelayMs": "单次等待上限（毫秒）",
     tools: "内置工具",
-    "tools.preset": "工具预设：default（六个工具，Node ≥ 25 时另加 codemode）、minimal、codemode-only、coordinator；codemode 是 codemode-only 的旧名；项目级只能更严",
+    "tools.preset": "工具预设：default（六个工具；网络隔离时另加 codemode，todo 需在 tools.default 加 +todo）、minimal、codemode-only、coordinator；codemode 是 codemode-only 的旧名；项目级只能更严",
     "tools.default": "在预设上微调：+name 加、-name 去，不带前缀的名字整组替换预设的内置工具；只认用户级",
     "tools.maxToolResultChars": "单条工具结果进上下文的字符上限，超出保留首尾",
     "tools.bashTimeoutMs": "bash 缺省超时（毫秒，单次调用可覆盖，最大 600000）",
@@ -77,6 +103,8 @@ export const CONFIG_KEY_DOCS = Object.freeze({
     "ui.ascii": "ASCII 字形（> * L、+ - |）；不写时自动检测：区域设置不含 UTF-8、TERM=linux、旧 conhost 时开启；AMA_ASCII=1/0 覆盖",
     "ui.compact": "消息区块间不空行、启动头不画框",
     "ui.animation": "false：运行中 spinner 静止，只在秒数变化时重绘",
+    "ui.restoreOnCancel": "运行中 Esc 中断、本回合还没有任何回复或工具调用时，撤回该回合并把原消息放回输入框",
+    "ui.statusLine": "底部信息行：full 两行（速率行 + 状态行），compact 一行；运行时 Ctrl+G 或 /statusline 切换（第五波 W5-A 起生效）",
     skills: "Skill",
     "skills.dirs": "追加的 Skill 目录；各层累加",
     cache: "提示缓存；整段只认用户级",
@@ -87,6 +115,47 @@ export const CONFIG_KEY_DOCS = Object.freeze({
     "cache.minSavingsUsd": "保温的最低期望节省（美元）",
     "cache.missNotices": "在消息区提示缓存未命中与上下文余量",
     "cache.warmSubagents": "子会话（task）也保温",
+    checkpoints: "检查点：回滚代码用的文件备份（docs/sessions.md「检查点与文件备份」）",
+    "checkpoints.mode": "tools：跟踪 edit / write 改过的文件；shadow-git：另用影子 git 快照整个工作目录，bash 等直接改动也能回滚（需要 git，大目录自动降级为 tools）；off：关闭；AMA_CHECKPOINTS 覆盖；项目级只接受 off",
+    "checkpoints.maxFileBytes": "单个文件的备份上限（字节），超出不备份、回滚时报告无法恢复；项目级只能调小",
+    "checkpoints.keep": "可回滚的最近检查点数，更早的不再列为回滚点；只认用户级 / profile",
+    sandbox: '操作系统级沙箱（docs/sandbox.md）；只认用户级 / profile，项目级只接受 network: "deny"',
+    "sandbox.enabled": "auto：探测到可用的 macOS sandbox-exec / Linux bwrap、unshare 就用（codemode 子进程拒绝网络与写入；Node 22 / 24 上 codemode 因此网络隔离）；off：不用；AMA_SANDBOX=off 覆盖",
+    "sandbox.bash": "auto：bash 经 sandbox-exec / bwrap 运行（unshare 不算），写入只限工作区、临时目录、输出目录与 sandbox.writable，default 模式下沙箱内命令免审批；off：不用；只认用户级 / profile",
+    "sandbox.network": "bash 沙箱里的网络：deny 拒绝（沙箱内免审批的前提）；allow 允许联网但写入仍受限、照常审批；项目级只能设 deny",
+    "sandbox.writable": "bash 沙箱追加的可写目录（绝对路径或 ~/…）；只认用户级 / profile",
+    // [W5-C0] 第五波（docs/wave5-plan.md）；括号里是起生效的批次
+    images: "图像输入；只认用户级（第五波 W5-I 起生效）",
+    "images.resize": "auto：图片超过端点上限时用系统工具（sips / magick）缩放，找不到工具按原规则拒绝；off：从不缩放",
+    plan: "Plan 模式（第五波 W5-F 起生效）",
+    "plan.bash": "plan 模式下的 bash：readonly 只读命令放行其余拒绝，ask 其余询问，deny 全拒；项目级只能更严",
+    "plan.directory": "计划文件目录（必须在项目根之内，否则回落缺省）；只认用户级",
+    "plan.unattended": "无人值守（-p、RPC 未声明 plans 能力）时：stop 落盘计划后停下等人审批，approve 自动批准执行；只认用户级",
+    "plan.model": "规划用模型 provider/model[@channel]：进入 plan 时切换、批准时切回；只认用户级",
+    "plan.thinkingLevel": "规划时的思考强度；只认用户级",
+    agents: "外部 Agent（claude / codex / ACP）与子 Agent 类型；agents.<id> 设单个 Agent 的 maxConcurrent / maxMode / model / env.passthrough；只认用户级（第五波 W5-E / W5-G 起生效）",
+    "agents.maxConcurrent": "外部 Agent 的总并发",
+    "agents.sessionBudgetUsd": "本会话外部 Agent 的美元预算",
+    "agents.dirs": "追加的子 Agent 定义目录（*.md）；各层累加",
+    subagents: "ama 自己的 task 子会话；只认用户级（第五波 W5-G 起生效）",
+    "subagents.maxConcurrent": "同时运行的子会话数",
+    "subagents.maxPending": "排队上限，超出时 task 报错",
+    "subagents.defaultModel": "子会话缺省模型 provider/model[@channel]",
+    models: "模型别名；只认用户级（第五波 W5-G 起生效）",
+    "models.aliases": "子 Agent 定义里 model: fast / strong 指向的模型",
+    "models.aliases.fast": "fast 别名的模型 provider/model[@channel]",
+    "models.aliases.strong": "strong 别名的模型 provider/model[@channel]",
+    fallbackModel: "回退模型 provider/model[@channel]：可重试错误用尽或过载时切换重试一次，下一回合回主模型；只认用户级（第五波 W5-H2 起生效）",
+    limits: "会话预算，到限结束本次运行（-p 退出码 8）；--max-turns / --max-cost 覆盖；只认用户级（第五波 W5-H2 起生效）",
+    "limits.maxTurns": "一次运行最多回合数",
+    "limits.maxCostUsd": "一次运行的美元上限",
+    reminders: "附在对话尾部的提醒（不改缓存前缀）；项目级可设（第五波 W5-H2 起生效）",
+    "reminders.todo": "todo 有未完成项且多回合未更新时复述",
+    "reminders.fileChanges": "读过的文件被外部改动时列出",
+    "reminders.contextPressure": "上下文用量到 70% / 85% 时各提醒一次",
+    "reminders.budget": "预算剩余不足 20% 时提醒",
+    todo: "todo 工具；只认用户级（第五波 W5-F / W5-H2 起生效）",
+    "todo.reminder": "连续 N 回合未更新且有未完成项时提醒复述；0 关闭",
 });
 /** 叶子路径（段落不算）。 */
 export function documentedLeaves() {

package/dist/config/merge.d.ts

@@ -6,11 +6,13 @@
  *   `tools.disabled`、`skills.dirs` 跨层拼接去重。
  * - 项目级 `.ama/config.json` 只接受：`permission.deny`（追加）、`permission.mode`（只能更严，且不能是
  *   auto / full-auto）、
- *   `compaction`、`tools.disabled`、`tools.preset`（只能更严）、`codemode.mode: "off"`、`ui`；
+ *   `compaction`、`tools.disabled`、`tools.preset`（只能更严）、`codemode.mode: "off"`、`ui`、
+ *   `checkpoints.mode: "off"`、`checkpoints.maxFileBytes`（只能调小）、（W5-C0）`plan.bash`（只能更严）、
+ *   `reminders`；`compaction.prune / pruneExclude` 与第五波其余段只认用户级；
  *   其它字段与放宽项（含 `permission.builtinDeny / autoModel / autoSafeCommands`）被忽略并记 warning。
  * - 同时产出带来源的权限规则清单（`ruleSpecs`），交给权限管线（B3 的 rules.ts 解析）。
  */
-import type { AmaConfig, CodemodeMode, ToolsPresetInput } from "./types.js";
+import type { AmaConfig, CodemodeMode, PlanBashMode, ToolsPresetInput } from "./types.js";
 import type { PermissionMode, RuleSource } from "../permissions/types.js";
 import type { ModelThinkingLevel } from "../ai/types.js";
 export declare const DEFAULT_CONFIG: Readonly<AmaConfig>;
@@ -35,7 +37,7 @@ export declare function isPresetStricterOrEqual(a: ToolsPresetInput, b: ToolsPre
  * 把项目级配置裁剪为受限字段（§7.2）；`currentMode` / `currentPreset` 是合并到此为止的
  * 权限模式与工具预设。
  */
-export declare function restrictProjectConfig(project: AmaConfig, currentMode: PermissionMode, label?: string, currentPreset?: ToolsPresetInput): RestrictResult;
+export declare function restrictProjectConfig(project: AmaConfig, currentMode: PermissionMode, label?: string, currentPreset?: ToolsPresetInput, currentMaxFileBytes?: number, currentPlanBash?: PlanBashMode): RestrictResult;
 /** 命令行对配置的覆盖（只含与 config 同名的那部分参数）。 */
 export interface CliConfigOverrides {
     thinkingLevel?: ModelThinkingLevel | undefined;

package/dist/config/merge.js

@@ -6,11 +6,13 @@
  *   `tools.disabled`、`skills.dirs` 跨层拼接去重。
  * - 项目级 `.ama/config.json` 只接受：`permission.deny`（追加）、`permission.mode`（只能更严，且不能是
  *   auto / full-auto）、
- *   `compaction`、`tools.disabled`、`tools.preset`（只能更严）、`codemode.mode: "off"`、`ui`；
+ *   `compaction`、`tools.disabled`、`tools.preset`（只能更严）、`codemode.mode: "off"`、`ui`、
+ *   `checkpoints.mode: "off"`、`checkpoints.maxFileBytes`（只能调小）、（W5-C0）`plan.bash`（只能更严）、
+ *   `reminders`；`compaction.prune / pruneExclude` 与第五波其余段只认用户级；
  *   其它字段与放宽项（含 `permission.builtinDeny / autoModel / autoSafeCommands`）被忽略并记 warning。
  * - 同时产出带来源的权限规则清单（`ruleSpecs`），交给权限管线（B3 的 rules.ts 解析）。
  */
-import { CONFIG_FILE_VERSION, TOOLS_PRESETS_STRICT_FIRST, canonicalPreset } from "./types.js";
+import { CONFIG_FILE_VERSION, DEFAULT_CHECKPOINTS_CONFIG, PLAN_BASH_MODES_STRICT_FIRST, TOOLS_PRESETS_STRICT_FIRST, canonicalPreset, } from "./types.js";
 import { isAtLeastAsStrict } from "../permissions/rules.js";
 export const DEFAULT_CONFIG = Object.freeze({
     version: CONFIG_FILE_VERSION,
@@ -31,7 +33,8 @@ export const DEFAULT_CONFIG = Object.freeze({
 });
 /** 嵌入宿主（有 profile）时的缺省覆盖（§12.10）。 */
 export const PROFILE_DEFAULTS = Object.freeze({
-    ui: { quietStartup: "header" },
+    // [W5-A] 嵌入宿主以「最后一行 = 状态栏」锚定，底部信息行缺省单行
+    ui: { quietStartup: "header", statusLine: "compact" },
 });
 /** 层名 → 规则来源（RuleSource）。 */
 const RULE_SOURCE = {
@@ -47,6 +50,7 @@ const ACCUMULATING = new Set([
     "permission.autoSafeCommands",
     "tools.disabled",
     "skills.dirs",
+    "agents.dirs",
 ]);
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -94,7 +98,7 @@ export function isPresetStricterOrEqual(a, b) {
  * 把项目级配置裁剪为受限字段（§7.2）；`currentMode` / `currentPreset` 是合并到此为止的
  * 权限模式与工具预设。
  */
-export function restrictProjectConfig(project, currentMode, label = ".ama/config.json", currentPreset = "default") {
+export function restrictProjectConfig(project, currentMode, label = ".ama/config.json", currentPreset = "default", currentMaxFileBytes = DEFAULT_CHECKPOINTS_CONFIG.maxFileBytes, currentPlanBash = "readonly") {
     const warnings = [];
     const accepted = {};
     for (const [key, value] of Object.entries(project)) {
@@ -102,9 +106,24 @@ export function restrictProjectConfig(project, currentMode, label = ".ama/config
             continue;
         switch (key) {
             case "compaction":
-                if (project.compaction !== undefined)
-                    accepted.compaction = structuredClone(project.compaction);
+                if (project.compaction !== undefined) {
+                    const { prune, pruneExclude, ...rest } = structuredClone(project.compaction);
+                    if (prune !== undefined || pruneExclude !== undefined)
+                        warnings.push(`${label}: 项目级不能设 compaction.prune / pruneExclude，已忽略`);
+                    if (Object.keys(rest).length > 0)
+                        accepted.compaction = rest;
+                }
+                break;
+            case "reminders":
+                if (project.reminders !== undefined)
+                    accepted.reminders = structuredClone(project.reminders);
+                break;
+            case "plan": {
+                const plan = restrictPlan(project.plan ?? {}, currentPlanBash, label, warnings);
+                if (plan !== undefined)
+                    accepted.plan = plan;
                 break;
+            }
             case "ui":
                 if (project.ui !== undefined)
                     accepted.ui = structuredClone(project.ui);
@@ -139,18 +158,73 @@ export function restrictProjectConfig(project, currentMode, label = ".ama/config
                     accepted.codemode = { mode: "off" };
                 break;
             }
+            case "checkpoints": {
+                const checkpoints = restrictCheckpoints(project.checkpoints ?? {}, currentMaxFileBytes, label, warnings);
+                if (checkpoints !== undefined)
+                    accepted.checkpoints = checkpoints;
+                break;
+            }
             case "permission": {
                 const permission = restrictPermission(project.permission ?? {}, currentMode, label, warnings);
                 if (permission !== undefined)
                     accepted.permission = permission;
                 break;
             }
+            case "sandbox": {
+                // [S2] 只能收紧：network "deny"。enabled / bash 两个方向都不是单纯更严（打开 bash 沙箱会让 default
+                // 模式免审批，关闭会让命令裸跑），writable 是放宽，一律忽略。
+                const sandbox = project.sandbox ?? {};
+                for (const [sub, v] of Object.entries(sandbox)) {
+                    if (sub === "network" && v === "deny")
+                        continue;
+                    warnings.push(`${label}: 项目级只接受 sandbox.network "deny"，忽略 sandbox.${sub}${sub === "network" ? ` ${String(v)}` : ""}`);
+                }
+                if (sandbox.network === "deny")
+                    accepted.sandbox = { network: "deny" };
+                break;
+            }
             default:
                 warnings.push(`${label}: 项目级不能设 ${key}，已忽略`);
         }
     }
     return { accepted, warnings };
 }
+/** [W5-C0] 项目级 plan：只接受 `bash`，且只能更严（deny < readonly < ask）。 */
+function restrictPlan(plan, current, label, warnings) {
+    for (const sub of Object.keys(plan)) {
+        if (sub !== "bash")
+            warnings.push(`${label}: 项目级只能设 plan.bash，忽略 plan.${sub}`);
+    }
+    if (plan.bash === undefined)
+        return undefined;
+    const order = PLAN_BASH_MODES_STRICT_FIRST;
+    if (order.indexOf(plan.bash) <= order.indexOf(current))
+        return { bash: plan.bash };
+    warnings.push(`${label}: 项目级只能收紧 plan.bash，忽略 ${plan.bash}（当前 ${current}）`);
+    return undefined;
+}
+/** 项目级检查点：只能关闭、只能调小单文件上限（多备份即多占用户磁盘）；`keep` 只认用户级。 */
+function restrictCheckpoints(checkpoints, currentMaxFileBytes, label, warnings) {
+    const result = {};
+    for (const [sub, v] of Object.entries(checkpoints)) {
+        if (sub === "mode") {
+            if (v === "off")
+                result.mode = "off";
+            else
+                warnings.push(`${label}: 项目级只接受 checkpoints.mode "off"，忽略 ${String(v)}`);
+        }
+        else if (sub === "maxFileBytes" && typeof v === "number") {
+            if (v <= currentMaxFileBytes)
+                result.maxFileBytes = v;
+            else
+                warnings.push(`${label}: 项目级只能调小 checkpoints.maxFileBytes，忽略 ${v}（当前 ${currentMaxFileBytes}）`);
+        }
+        else {
+            warnings.push(`${label}: 项目级不能设 checkpoints.${sub}，已忽略`);
+        }
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
 function restrictPermission(permission, currentMode, label, warnings) {
     const result = {};
     if (permission.allow !== undefined && permission.allow.length > 0) {
@@ -242,7 +316,7 @@ export function mergeProjectAndCli(base, project, cli, projectLabel) {
     const present = [...base.layers];
     if (project !== undefined) {
         const baseline = config.permission?.mode ?? "default";
-        const restricted = restrictProjectConfig(project, baseline, projectLabel, config.tools?.preset ?? "default");
+        const restricted = restrictProjectConfig(project, baseline, projectLabel, config.tools?.preset ?? "default", config.checkpoints?.maxFileBytes ?? DEFAULT_CHECKPOINTS_CONFIG.maxFileBytes, config.plan?.bash ?? "readonly");
         warnings.push(...restricted.warnings);
         config = mergeConfig(config, restricted.accepted);
         present.push("project");

package/dist/config/profile.d.ts

@@ -12,6 +12,8 @@ export interface ProfileOptions {
     instructions: string[];
     skillDirs: string[];
     promptDirs: string[];
+    /** [W5-C0] 子 Agent 定义目录（W5-G 接入发现）。 */
+    agentDirs?: string[];
     hooksFile?: string;
     authFile?: string;
     /** false：key 只来自 authFile。 */

package/dist/config/profile.js

@@ -51,6 +51,8 @@ function profileToOptions(path, profile, warnings) {
         trustProject: profile.trustProject === true,
         warnings: [...warnings],
     };
+    if (profile.agentDirs !== undefined)
+        options.agentDirs = [...profile.agentDirs];
     if (profile.host !== undefined)
         options.host = profile.host;
     if (profile.hooksFile !== undefined)

package/dist/config/schema-w5.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 第五波配置键的校验（docs/wave5-plan.md §9；schema.ts 已近 600 行，新键放这里）。[W5-C0]
+ *
+ * 规则与 json-schema.ts 一一对应（json-schema.test.ts 的正反例守住）：类型 / 取值错误是 error，
+ * 未知字段是 warning。只校验形状；行为由各批次实现。
+ */
+import { Checker, type Obj } from "./checker.js";
+/** 第五波新增的顶层键（schema.ts 的 CONFIG_KEYS 并入）。 */
+export declare const W5_CONFIG_KEYS: readonly ["images", "plan", "agents", "subagents", "models", "fallbackModel", "limits", "reminders", "todo"];
+/** 已有段新增的键。 */
+export declare const W5_UI_KEYS: readonly ["statusLine"];
+export declare const W5_COMPACTION_KEYS: readonly ["prune", "pruneExclude"];
+/** `agents.<id>` 的 id：子 Agent 名（`^[a-z0-9-]`）或外部 Agent（可带 `acp:` 前缀）。 */
+export declare const AGENT_ID_PATTERN: RegExp;
+export declare function checkUiW5(c: Checker, ui: Obj, path: string): void;
+export declare function checkCompactionW5(c: Checker, compaction: Obj, path: string): void;
+/** 第五波顶层段的校验（validateConfig 末尾调用）。 */
+export declare function validateConfigW5(c: Checker, config: Obj): void;

package/dist/config/schema-w5.js

@@ -0,0 +1,109 @@
+/**
+ * 第五波配置键的校验（docs/wave5-plan.md §9；schema.ts 已近 600 行，新键放这里）。[W5-C0]
+ *
+ * 规则与 json-schema.ts 一一对应（json-schema.test.ts 的正反例守住）：类型 / 取值错误是 error，
+ * 未知字段是 warning。只校验形状；行为由各批次实现。
+ */
+import { PERMISSION_MODES_STRICT_FIRST } from "../permissions/types.js";
+import { Checker, THINKING_LEVELS, checkSection, join } from "./checker.js";
+import { AGENTS_RESERVED_KEYS, IMAGE_RESIZE_MODES, PLAN_BASH_MODES_STRICT_FIRST, PLAN_UNATTENDED_MODES, STATUS_LINE_MODES, } from "./types-w5.js";
+/** 第五波新增的顶层键（schema.ts 的 CONFIG_KEYS 并入）。 */
+export const W5_CONFIG_KEYS = [
+    "images",
+    "plan",
+    "agents",
+    "subagents",
+    "models",
+    "fallbackModel",
+    "limits",
+    "reminders",
+    "todo",
+];
+/** 已有段新增的键。 */
+export const W5_UI_KEYS = ["statusLine"];
+export const W5_COMPACTION_KEYS = ["prune", "pruneExclude"];
+/** `agents.<id>` 的 id：子 Agent 名（`^[a-z0-9-]`）或外部 Agent（可带 `acp:` 前缀）。 */
+export const AGENT_ID_PATTERN = /^(acp:)?[a-z0-9][a-z0-9._-]{0,63}$/;
+const AGENT_ENTRY_KEYS = ["maxConcurrent", "maxMode", "model", "env"];
+export function checkUiW5(c, ui, path) {
+    c.oneOf(ui, "statusLine", path, STATUS_LINE_MODES);
+}
+export function checkCompactionW5(c, compaction, path) {
+    c.stringArray(compaction, "pruneExclude", path);
+    const prune = compaction["prune"];
+    const p = join(path, "prune");
+    if (prune === undefined || !c.object(prune, p))
+        return;
+    c.keys(prune, p, ["keepResults", "clearAtLeast"]);
+    c.number(prune, "keepResults", p, 0);
+    const clear = prune["clearAtLeast"];
+    if (clear !== undefined && clear !== "auto" && (typeof clear !== "number" || clear < 0))
+        c.error(join(p, "clearAtLeast"), '应为 "auto" 或非负数字');
+}
+function checkAgentEntry(c, entry, path) {
+    if (!c.object(entry, path))
+        return;
+    c.keys(entry, path, AGENT_ENTRY_KEYS);
+    c.number(entry, "maxConcurrent", path, 1, 64);
+    c.oneOf(entry, "maxMode", path, PERMISSION_MODES_STRICT_FIRST);
+    c.string(entry, "model", path);
+    const env = entry["env"];
+    const envPath = join(path, "env");
+    if (env !== undefined && c.object(env, envPath)) {
+        c.keys(env, envPath, ["passthrough"]);
+        c.stringArray(env, "passthrough", envPath);
+    }
+}
+function checkAgents(c, config) {
+    const agents = config["agents"];
+    if (agents === undefined || !c.object(agents, "agents"))
+        return;
+    c.number(agents, "maxConcurrent", "agents", 1, 64);
+    c.number(agents, "sessionBudgetUsd", "agents", 0);
+    c.stringArray(agents, "dirs", "agents");
+    for (const [id, entry] of Object.entries(agents)) {
+        if (AGENTS_RESERVED_KEYS.includes(id))
+            continue;
+        const p = join("agents", id);
+        if (!AGENT_ID_PATTERN.test(id))
+            c.error(p, "Agent id 只能是小写字母、数字、- . _（可带 acp: 前缀）");
+        else
+            checkAgentEntry(c, entry, p);
+    }
+}
+/** 第五波顶层段的校验（validateConfig 末尾调用）。 */
+export function validateConfigW5(c, config) {
+    checkSection(c, config, "images", ["resize"], (s, p) => c.oneOf(s, "resize", p, IMAGE_RESIZE_MODES));
+    checkSection(c, config, "plan", ["bash", "directory", "unattended", "model", "thinkingLevel"], (s, p) => {
+        c.oneOf(s, "bash", p, PLAN_BASH_MODES_STRICT_FIRST);
+        c.string(s, "directory", p);
+        c.oneOf(s, "unattended", p, PLAN_UNATTENDED_MODES);
+        c.string(s, "model", p);
+        c.oneOf(s, "thinkingLevel", p, THINKING_LEVELS);
+    });
+    checkAgents(c, config);
+    checkSection(c, config, "subagents", ["maxConcurrent", "maxPending", "defaultModel"], (s, p) => {
+        c.number(s, "maxConcurrent", p, 1, 64);
+        c.number(s, "maxPending", p, 0, 1024);
+        c.string(s, "defaultModel", p);
+    });
+    checkSection(c, config, "models", ["aliases"], (s, p) => {
+        const aliases = s["aliases"];
+        const ap = join(p, "aliases");
+        if (aliases === undefined || !c.object(aliases, ap))
+            return;
+        c.keys(aliases, ap, ["fast", "strong"]);
+        c.string(aliases, "fast", ap);
+        c.string(aliases, "strong", ap);
+    });
+    c.string(config, "fallbackModel", "");
+    checkSection(c, config, "limits", ["maxTurns", "maxCostUsd"], (s, p) => {
+        c.number(s, "maxTurns", p, 1);
+        c.number(s, "maxCostUsd", p, 0);
+    });
+    checkSection(c, config, "reminders", ["todo", "fileChanges", "contextPressure", "budget"], (s, p) => {
+        for (const key of ["todo", "fileChanges", "contextPressure", "budget"])
+            c.boolean(s, key, p);
+    });
+    checkSection(c, config, "todo", ["reminder"], (s, p) => c.number(s, "reminder", p, 0));
+}