@armadra/agent 0.4.0 → 0.5.1

package/dist/permissions/readonly-bash.d.ts

@@ -0,0 +1,30 @@
+/**
+ * plan 模式与 allowlist 放行的只读 bash 子集 `READONLY_BASH`（docs/wave5-plan.md §6.2、D21）。[W5-F]
+ *
+ * 判定 = auto 的静态判定（`analyzeBashForAuto`：分词、嵌套展开、规则层的网络 / 删除 / 写入目标 /
+ * 机密路径、命令替换、变量展开、点文件通配）**全部通过**，再加四条更窄的限制：
+ * - 每段命令都命中 {@link READONLY_BASH}（比 auto 安全名单窄：去掉测试 / 构建运行器、`printenv`
+ *   这类会把环境变量里的密钥打进上下文的命令）；
+ * - 没有输出重定向（`/dev/null` 等设备除外）；
+ * - 没有嵌套 shell（`sh -c`、`eval`、`xargs`、`find -exec`）与进程替换；
+ * - 段首没有环境赋值或包装命令（`GIT_EXTERNAL_DIFF=… git diff`、`env …`、`nohup …`）。
+ *
+ * 机密路径（`cat .env`）由 auto 规则层判为「要询问」，这里因此不算只读；deny 规则仍先于模式判定。
+ */
+export interface ReadonlySpec {
+    /** 词前缀（`["git", "log"]`）；git 的全局选项只允许 `-C <dir>` 与 `--no-pager`。 */
+    words: readonly string[];
+    /** 前缀之后任一参数命中即不算只读。 */
+    forbid?: RegExp;
+}
+/** 只读命令名单（每条在 readonly-bash.test.ts 有正反例）。 */
+export declare const READONLY_BASH: readonly ReadonlySpec[];
+export interface ReadonlyBashOptions {
+    /** 相对路径（机密路径、写入目标）的解析基准；缺省 `process.cwd()`。 */
+    cwd?: string;
+    projectRoot?: string;
+}
+/** 不是只读的原因；只读返回 undefined。 */
+export declare function readonlyBashReason(command: string, options?: ReadonlyBashOptions): string | undefined;
+/** 每段命令都在 {@link READONLY_BASH} 且无重定向 / 命令替换 / 嵌套 shell。 */
+export declare function isReadonlyBash(command: string, options?: ReadonlyBashOptions): boolean;

package/dist/permissions/readonly-bash.js

@@ -0,0 +1,118 @@
+/**
+ * plan 模式与 allowlist 放行的只读 bash 子集 `READONLY_BASH`（docs/wave5-plan.md §6.2、D21）。[W5-F]
+ *
+ * 判定 = auto 的静态判定（`analyzeBashForAuto`：分词、嵌套展开、规则层的网络 / 删除 / 写入目标 /
+ * 机密路径、命令替换、变量展开、点文件通配）**全部通过**，再加四条更窄的限制：
+ * - 每段命令都命中 {@link READONLY_BASH}（比 auto 安全名单窄：去掉测试 / 构建运行器、`printenv`
+ *   这类会把环境变量里的密钥打进上下文的命令）；
+ * - 没有输出重定向（`/dev/null` 等设备除外）；
+ * - 没有嵌套 shell（`sh -c`、`eval`、`xargs`、`find -exec`）与进程替换；
+ * - 段首没有环境赋值或包装命令（`GIT_EXTERNAL_DIFF=… git diff`、`env …`、`nohup …`）。
+ *
+ * 机密路径（`cat .env`）由 auto 规则层判为「要询问」，这里因此不算只读；deny 规则仍先于模式判定。
+ */
+import { analyzeBashForAuto, extractRedirects } from "./auto-safe.js";
+import { collectNestedCommands, commandWords, gitArgv, shellWords } from "./dangerous.js";
+import { splitShellSegments } from "./rules.js";
+const spec = (text, forbid) => forbid === undefined ? { words: text.split(" ") } : { words: text.split(" "), forbid };
+const GIT_OUTPUT = /^(--output(=.*)?|--ext-diff|--textconv|-O.*|--open-files-in-pager.*)$/;
+/** 只读命令名单（每条在 readonly-bash.test.ts 有正反例）。 */
+export const READONLY_BASH = [
+    ...[
+        "ls",
+        "cat",
+        "head",
+        "tail",
+        "wc",
+        "stat",
+        "echo",
+        "printf",
+        "pwd",
+        "which",
+        "du",
+        "tree",
+        "basename",
+        "dirname",
+        "realpath",
+        "true",
+        "false",
+        "cd",
+    ].map((name) => spec(name, name === "tree" ? /^-o.*$/ : undefined)),
+    spec("file", /^(-C|--compile)$/),
+    ...["grep", "egrep", "fgrep"].map((name) => spec(name)),
+    spec("rg", /^--pre(=.*)?$/),
+    spec("fd", /^(-x|-X|--exec|--exec-batch)(=.*)?$/),
+    spec("find", /^-(exec|execdir|ok|okdir|delete|fprint0?|fprintf|fls)$/),
+    spec("jq", /^(-i|--in-place)$/),
+    ...["status", "rev-parse", "blame", "ls-files"].map((sub) => spec(`git ${sub}`, GIT_OUTPUT)),
+    ...["log", "show", "diff"].map((sub) => spec(`git ${sub}`, GIT_OUTPUT)),
+    spec("git branch", /^(-[A-Za-z]*[dDmMcCfuet][A-Za-z]*|--(delete|move|copy|force|set-upstream-to.*|unset-upstream|edit-description|track.*|no-track|create-reflog))$/),
+];
+/** auto 安全名单里没有、但属于只读子集的命令（交给 analyzeBashForAuto 当作追加项）。 */
+const EXTRA_FOR_AUTO = ["tree", "jq", "fd"];
+const DEVICE_TARGETS = /^(\/dev\/(null|stdout|stderr|tty)|NUL)$/i;
+function base(word) {
+    return (word ?? "").split("/").pop() ?? "";
+}
+/** git 子命令之前只允许 `-C <dir>` 与 `--no-pager`（`-c` 可改 pager / diff 程序）。 */
+function gitPrefixSafe(argv) {
+    for (let i = 1; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "-C")
+            i++;
+        else if (a === "--no-pager")
+            continue;
+        else
+            return !a.startsWith("-");
+    }
+    return true;
+}
+function matches(argv, entry) {
+    let words = argv;
+    if (entry.words[0] === "git") {
+        if (base(argv[0]) !== "git" || !gitPrefixSafe(argv))
+            return false;
+        words = ["git", ...(gitArgv(argv) ?? argv).slice(1)];
+    }
+    else if (argv[0] !== entry.words[0])
+        return false;
+    if (words.length < entry.words.length)
+        return false;
+    if (!entry.words.every((w, i) => words[i] === w))
+        return false;
+    const rest = words.slice(entry.words.length);
+    return entry.forbid === undefined || !rest.some((a) => entry.forbid.test(a));
+}
+/** 不是只读的原因；只读返回 undefined。 */
+export function readonlyBashReason(command, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const nested = collectNestedCommands(command);
+    if (nested.commands.length > 0 || nested.tooDeep)
+        return "nested shell command";
+    const auto = analyzeBashForAuto(command, {
+        cwd,
+        projectRoot: options.projectRoot ?? cwd,
+        extraSafe: EXTRA_FOR_AUTO,
+    });
+    if (!auto.safe)
+        return auto.ask ?? auto.reason;
+    for (const segment of splitShellSegments(command)) {
+        const redirects = extractRedirects(segment);
+        const target = redirects.outputs.find((t) => !DEVICE_TARGETS.test(t));
+        if (target !== undefined)
+            return `output redirection (${target})`;
+        const raw = shellWords(redirects.rest.replace(/^[({\s]+/, ""));
+        const argv = commandWords(redirects.rest, true);
+        if (argv.length === 0)
+            return "empty command";
+        if (raw[0] !== argv[0])
+            return `environment assignment or wrapper before ${argv[0]}`;
+        if (!READONLY_BASH.some((entry) => matches(argv, entry)))
+            return `${base(argv[0])} is not in the read-only list`;
+    }
+    return undefined;
+}
+/** 每段命令都在 {@link READONLY_BASH} 且无重定向 / 命令替换 / 嵌套 shell。 */
+export function isReadonlyBash(command, options = {}) {
+    return readonlyBashReason(command, options) === undefined;
+}

package/dist/permissions/types.d.ts

@@ -72,6 +72,43 @@ export interface ApprovalRequestContext {
     parentToolCallId?: string;
     /** [W3-C0] 本会话已 read 过的路径（`ToolContext.readFiles`），由 `gateToolCall` 填入。 */
     readFiles?: ReadonlySet<string>;
+    /** [W5-C0] 子 Agent 任务 id（对话框标注 `[task:<agent>]`）。 */
+    taskId?: string;
+    /**
+     * [W5-C0] 来自外部 Agent 的权限请求（docs/wave5-plan.md §5.3）：只走 broker 链（宿主 → UI →
+     * 无人值守拒绝），auto 分类器与模型都不参与；RPC `permission_request` 原样带出。
+     */
+    origin?: ExternalPermissionOrigin;
+}
+/** [W5-C0] 外部 Agent 权限选项的种类（ACP 词汇）。 */
+export type ExternalPermissionOptionKind = "allow_once" | "allow_always" | "reject_once" | "reject_always";
+/** [W5-C0] 外部 Agent 发来的权限请求（ACP `session/request_permission` 子集）。 */
+export interface ExternalPermissionOrigin {
+    /** 外部 Agent id（`claude` / `codex` / `acp:<program>`）。 */
+    agent: string;
+    /** 外部 CLI 自己的会话 id。 */
+    sessionId: string;
+    toolCall: {
+        title: string;
+        kind: string;
+        locations?: string[];
+        inputSummary?: string;
+    };
+    options: {
+        optionId: string;
+        kind: ExternalPermissionOptionKind;
+    }[];
+}
+/**
+ * [W5-EG] `permission_request` 事件的发起方（`ApprovalRequestContext` 的线上子集，可 JSON 序列化）：
+ * 只在来自子 Agent / 外部 Agent 时出现。
+ */
+export interface PermissionRequestContext {
+    /** > 0：来自 task 子 Agent（对话框标 `[task:<agent>]`）。 */
+    depth?: number;
+    taskId?: string;
+    /** 外部 Agent 的权限请求（对话框标 `[claude · 会话 abc1]`）。 */
+    origin?: ExternalPermissionOrigin;
 }
 /** [W3-C0] 预览涉及的路径（bash 的 rm / mv / 重定向目标，write / edit 的目标文件）。 */
 export interface ActionPreviewTarget {
@@ -129,6 +166,11 @@ export interface PermissionVerdict {
      * 的 decision（ask，无人值守时已是 deny）。不认识这个字段的调用方得到的就是保守结论。
      */
     classify?: boolean;
+    /**
+     * [S2] 这次 bash 调用将经 OS 沙箱运行（docs/sandbox.md「第二阶段」）。default / auto-edit 下因此免审批时
+     * 为真；auto 下随 `classify` 一起交给分类器作为输入。
+     */
+    sandboxed?: boolean;
 }
 export interface PermissionPipelineApi {
     readonly mode: PermissionMode;

package/dist/plan/compose.d.ts

@@ -0,0 +1,9 @@
+/**
+ * plan 扩展的装配（`cli/compose-extensions.ts` 的一行）。[W5-F]
+ *
+ * 交互 / line 模式由用户在输入框里回复审批（文本回复，正式审批框归 W5-U），TUI 且无宿主时显示一行
+ * 提示；print / rpc 缺省按 `plan.unattended`，RPC 客户端声明 `plans` 能力后改由客户端作答。
+ */
+import type { SessionExtensionFactory } from "../agent/session-extensions.js";
+import type { ComposeExtensionDeps } from "../cli/compose-extensions.js";
+export declare function planExtensionFor(deps: ComposeExtensionDeps): SessionExtensionFactory;

package/dist/plan/compose.js

@@ -0,0 +1,19 @@
+/**
+ * plan 扩展的装配（`cli/compose-extensions.ts` 的一行）。[W5-F]
+ *
+ * 交互 / line 模式由用户在输入框里回复审批（文本回复，正式审批框归 W5-U），TUI 且无宿主时显示一行
+ * 提示；print / rpc 缺省按 `plan.unattended`，RPC 客户端声明 `plans` 能力后改由客户端作答。
+ */
+import { createPlanExtensionFactory } from "../agent/session-plan.js";
+export function planExtensionFor(deps) {
+    const { assembly } = deps;
+    const attended = assembly.mode === "interactive" || assembly.mode === "line";
+    return createPlanExtensionFactory({
+        ...(assembly.config.plan !== undefined ? { config: assembly.config.plan } : {}),
+        // 组装表测试只给 config：其余材料按可缺省读取
+        ...(assembly.paths?.dataDir !== undefined ? { dataDir: assembly.paths.dataDir } : {}),
+        attendance: attended && !assembly.unattended ? "text" : "unattended",
+        notice: assembly.mode === "interactive" && assembly.host?.handle === undefined,
+        log: deps.log,
+    });
+}

package/dist/plan/controller.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 计划控制面的类型与登记表（RPC / SDK / 界面通过 `planController(session)` 使用）。[W5-F]
+ * 实现在 `agent/session-plan.ts`。
+ */
+import type { PlanData, PlanDecisionKind, TodoItemView } from "../agent/types.js";
+import type { PlanConfig } from "../config/types-w5.js";
+import type { PermissionMode } from "../permissions/types.js";
+/**
+ * 计划审批由谁回答：`text` 交互模式（回复 1 / 2 / 3 批准，其它文字即修改意见）；`client` RPC 客户端
+ * 声明了 `plans` 能力（`plan_response`）；`callback` SDK `plan.onProposed`；`unattended` 按
+ * `plan.unattended`。
+ */
+export type PlanAttendance = "text" | "client" | "callback" | "unattended";
+/** 审批回答（RPC `plan_response` 同构）。 */
+export interface PlanResponse {
+    planId: string;
+    decision: PlanDecisionKind;
+    mode?: PermissionMode;
+    feedback?: string;
+    editedMarkdown?: string;
+}
+/** SDK 回调的返回：不带 planId 的回答；undefined = 不作答（计划留在 proposed）。 */
+export type PlanDecision = Omit<PlanResponse, "planId">;
+export type PlanDecisionHandler = (plan: PlanData) => Promise<PlanDecision | undefined>;
+export interface PlanResponseResult {
+    planId: string;
+    decision: PlanDecisionKind;
+    /** 批准后的执行模式。 */
+    mode?: PermissionMode;
+    /** 最终计划（编辑过则是新版本）。 */
+    plan: PlanData;
+    /** `approve_fresh`：新会话的首条用户消息（调用方新建会话后先 `adopt(plan)` 再发它）。 */
+    freshPrompt?: string;
+}
+/** RPC / SDK / 界面使用的计划控制面（`planController(session)` 取得）。 */
+export interface PlanController {
+    /** 分支上最近的计划（任意状态）；没有为 null。 */
+    current(): PlanData | null;
+    get(planId?: string): PlanData | null;
+    /** 等待审批的计划（最近一条且 status = proposed）。 */
+    pending(): PlanData | undefined;
+    todos(): TodoItemView[];
+    /** 进入 plan 前的模式（不在 plan 时 undefined）。 */
+    prePlanMode(): PermissionMode | undefined;
+    respond(response: PlanResponse): Promise<PlanResponseResult>;
+    /** `/plan approve` 的回退：回复里没有计划块时把上一条回复当作计划提交审批。 */
+    proposeFromLastReply(): PlanData | undefined;
+    /** 「新上下文执行」的新会话：记下获批计划并生成 todo。 */
+    adopt(plan: PlanData): void;
+    setAttendance(kind: PlanAttendance, handler?: PlanDecisionHandler): void;
+}
+export interface PlanExtensionOptions {
+    config?: PlanConfig;
+    /** 计划文件缺省目录 `<dataDir>/plans`；不给且没有 `plan.directory` 时不写文件。 */
+    dataDir?: string;
+    /** 缺省 unattended。 */
+    attendance?: PlanAttendance;
+    /**
+     * 交互模式（无宿主）在计划待审批时显示一行文本提示：以不落盘的 `message_start`（custom、
+     * `display:true`）事件发出，TUI 显示为提示行。正式的审批框归 W5-U。
+     */
+    notice?: boolean;
+    log?(level: "debug" | "info" | "warn" | "error", message: string): void;
+}
+/** 扩展构造时登记（键 = 会话对象），dispose 时撤下。 */
+export declare function registerPlanController(session: object, controller: PlanController | undefined): void;
+/** 会话的计划控制面；会话没有装 plan 扩展（子会话、SDK 自装配）时 undefined。 */
+export declare function planController(session: object): PlanController | undefined;
+/** 文本提示行（只发事件，不落盘、不进上下文）。 */
+export declare const PLAN_NOTICE_TYPE = "ama.plan_notice";
+export declare const APPROVE_REPLY: Readonly<Record<string, PermissionMode | "pre">>;

package/dist/plan/controller.js

@@ -0,0 +1,27 @@
+/**
+ * 计划控制面的类型与登记表（RPC / SDK / 界面通过 `planController(session)` 使用）。[W5-F]
+ * 实现在 `agent/session-plan.ts`。
+ */
+const controllers = new WeakMap();
+/** 扩展构造时登记（键 = 会话对象），dispose 时撤下。 */
+export function registerPlanController(session, controller) {
+    if (controller === undefined)
+        controllers.delete(session);
+    else
+        controllers.set(session, controller);
+}
+/** 会话的计划控制面；会话没有装 plan 扩展（子会话、SDK 自装配）时 undefined。 */
+export function planController(session) {
+    return controllers.get(session);
+}
+/** 文本提示行（只发事件，不落盘、不进上下文）。 */
+export const PLAN_NOTICE_TYPE = "ama.plan_notice";
+export const APPROVE_REPLY = {
+    "1": "pre",
+    y: "pre",
+    yes: "pre",
+    approve: "pre",
+    批准: "pre",
+    "2": "auto-edit",
+    "3": "auto",
+};

package/dist/plan/done-markers.d.ts

@@ -0,0 +1,17 @@
+/**
+ * [W5-Z] `[DONE:<步骤>]` 文本交接（docs/plan.md「交接」，D20 / R6 的回退）：活动工具集里没有 `todo` 时，
+ * 批准计划的交接消息请模型每完成一步在回复里单独一行写 `[DONE:S1]`；ama 在回合结束时读这些标记，
+ * 把计划生成的待办（`planStep`）标为 done、下一个未完成项转 in_progress，照常落 `ama.todo` 与发
+ * `todo_updated`，界面与 RPC 的进度显示不依赖 todo 工具。
+ */
+import type { AgentMessage } from "../session/types.js";
+import type { TodoItem } from "../tools/todo.js";
+/** 文本里单独成行的 `[DONE:<id>]`（去重、按出现顺序）。 */
+export declare function parseDoneMarkers(text: string): string[];
+/**
+ * 按标记更新待办：只认带 `planStep` 的条目（按 `planStep` 或 `id` 匹配，大小写不敏感）。有变化时返回
+ * 新清单（被标记的 done；若此时没有 in_progress，第一个 pending 转 in_progress），否则 undefined。
+ */
+export declare function applyDoneMarkers(items: readonly TodoItem[], ids: readonly string[]): TodoItem[] | undefined;
+/** 一条助手回复里的标记 → 新待办清单（不是助手消息、没有标记或没有变化时 undefined）。 */
+export declare function todosFromDoneMarkers(message: AgentMessage, items: readonly TodoItem[]): TodoItem[] | undefined;

package/dist/plan/done-markers.js

@@ -0,0 +1,51 @@
+/**
+ * [W5-Z] `[DONE:<步骤>]` 文本交接（docs/plan.md「交接」，D20 / R6 的回退）：活动工具集里没有 `todo` 时，
+ * 批准计划的交接消息请模型每完成一步在回复里单独一行写 `[DONE:S1]`；ama 在回合结束时读这些标记，
+ * 把计划生成的待办（`planStep`）标为 done、下一个未完成项转 in_progress，照常落 `ama.todo` 与发
+ * `todo_updated`，界面与 RPC 的进度显示不依赖 todo 工具。
+ */
+const MARKER = /^[ \t]*\[DONE:\s*([A-Za-z0-9_.-]{1,32})\s*\][ \t]*$/gm;
+/** 文本里单独成行的 `[DONE:<id>]`（去重、按出现顺序）。 */
+export function parseDoneMarkers(text) {
+    const ids = [];
+    for (const match of text.matchAll(MARKER)) {
+        const id = match[1];
+        if (!ids.includes(id))
+            ids.push(id);
+    }
+    return ids;
+}
+/**
+ * 按标记更新待办：只认带 `planStep` 的条目（按 `planStep` 或 `id` 匹配，大小写不敏感）。有变化时返回
+ * 新清单（被标记的 done；若此时没有 in_progress，第一个 pending 转 in_progress），否则 undefined。
+ */
+export function applyDoneMarkers(items, ids) {
+    if (ids.length === 0)
+        return undefined;
+    const wanted = new Set(ids.map((id) => id.toLowerCase()));
+    let changed = false;
+    const next = items.map((item) => {
+        const step = item.planStep;
+        if (step === undefined || item.status === "done")
+            return { ...item };
+        if (!wanted.has(step.toLowerCase()) && !wanted.has(item.id.toLowerCase()))
+            return { ...item };
+        changed = true;
+        return { ...item, status: "done" };
+    });
+    if (!changed)
+        return undefined;
+    if (!next.some((item) => item.status === "in_progress")) {
+        const first = next.find((item) => item.status === "pending");
+        if (first !== undefined)
+            first.status = "in_progress";
+    }
+    return next;
+}
+/** 一条助手回复里的标记 → 新待办清单（不是助手消息、没有标记或没有变化时 undefined）。 */
+export function todosFromDoneMarkers(message, items) {
+    if (message.role !== "assistant" || items.length === 0)
+        return undefined;
+    const text = message.content.map((b) => (b.type === "text" ? b.text : "")).join("\n");
+    return applyDoneMarkers(items, parseDoneMarkers(text));
+}

package/dist/plan/extract.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `<proposed_plan>` 块的提取与步骤解析（docs/wave5-plan.md §6.3、D19）。[W5-F] 纯函数。
+ *
+ * - 只认开、闭标签**各占一行**（允许行首尾空白）、且不在代码围栏（``` / ~~~）内的块；
+ *   不闭合的块忽略；多个完整块取最后一个。
+ * - 步骤：优先 `- [ ] S1 …` 清单（任意位置的顶层清单项）；没有清单时取「步骤 / Steps」小节里的
+ *   编号列表（没有该小节则取全部顶层编号列表）。行内标注 `[depends: S1, S2]`、`[agent: codex]`
+ *   解析进 `dependsOn` / `agent` 并从文字里去掉。上限 {@link MAX_PLAN_STEPS} 条，超出截断。
+ */
+import type { PlanStep } from "../agent/types.js";
+export declare const PLAN_OPEN_TAG = "<proposed_plan>";
+export declare const PLAN_CLOSE_TAG = "</proposed_plan>";
+export declare const MAX_PLAN_STEPS = 30;
+export interface ExtractedPlan {
+    /** 块内正文（不含标签），首尾空行去掉。 */
+    markdown: string;
+    steps: PlanStep[];
+    /** 步骤超过上限被截断。 */
+    truncated?: boolean;
+}
+/** 从一条回复里取最后一个完整的 `<proposed_plan>` 块；没有返回 undefined。 */
+export declare function extractProposedPlan(text: string): ExtractedPlan | undefined;
+/** 计划正文 → 步骤（用户编辑过的全文、「把上一条回复当作计划」也走这里）。 */
+export declare function planFromMarkdown(markdown: string): ExtractedPlan;
+/** 计划正文里的步骤；没有可识别的列表返回空数组。 */
+export declare function parsePlanSteps(markdown: string): {
+    steps: PlanStep[];
+    truncated: boolean;
+};

package/dist/plan/extract.js

@@ -0,0 +1,160 @@
+/**
+ * `<proposed_plan>` 块的提取与步骤解析（docs/wave5-plan.md §6.3、D19）。[W5-F] 纯函数。
+ *
+ * - 只认开、闭标签**各占一行**（允许行首尾空白）、且不在代码围栏（``` / ~~~）内的块；
+ *   不闭合的块忽略；多个完整块取最后一个。
+ * - 步骤：优先 `- [ ] S1 …` 清单（任意位置的顶层清单项）；没有清单时取「步骤 / Steps」小节里的
+ *   编号列表（没有该小节则取全部顶层编号列表）。行内标注 `[depends: S1, S2]`、`[agent: codex]`
+ *   解析进 `dependsOn` / `agent` 并从文字里去掉。上限 {@link MAX_PLAN_STEPS} 条，超出截断。
+ */
+export const PLAN_OPEN_TAG = "<proposed_plan>";
+export const PLAN_CLOSE_TAG = "</proposed_plan>";
+export const MAX_PLAN_STEPS = 30;
+const FENCE = /^\s*(```|~~~)/;
+/** 从一条回复里取最后一个完整的 `<proposed_plan>` 块；没有返回 undefined。 */
+export function extractProposedPlan(text) {
+    const lines = text.split(/\r?\n/);
+    let fence;
+    let open;
+    let last;
+    for (const [i, line] of lines.entries()) {
+        const marker = FENCE.exec(line)?.[1];
+        if (marker !== undefined) {
+            if (fence === undefined)
+                fence = marker;
+            else if (marker === fence)
+                fence = undefined;
+            continue;
+        }
+        if (fence !== undefined)
+            continue;
+        const trimmed = line.trim();
+        if (trimmed === PLAN_OPEN_TAG)
+            open = i;
+        else if (trimmed === PLAN_CLOSE_TAG && open !== undefined) {
+            last = { from: open + 1, to: i };
+            open = undefined;
+        }
+    }
+    if (last === undefined)
+        return undefined;
+    const markdown = trimBlankLines(lines.slice(last.from, last.to)).join("\n");
+    if (markdown.trim() === "")
+        return undefined;
+    return planFromMarkdown(markdown);
+}
+/** 计划正文 → 步骤（用户编辑过的全文、「把上一条回复当作计划」也走这里）。 */
+export function planFromMarkdown(markdown) {
+    const parsed = parsePlanSteps(markdown);
+    const plan = { markdown, steps: parsed.steps };
+    if (parsed.truncated)
+        plan.truncated = true;
+    return plan;
+}
+function trimBlankLines(lines) {
+    let from = 0;
+    let to = lines.length;
+    while (from < to && lines[from].trim() === "")
+        from++;
+    while (to > from && lines[to - 1].trim() === "")
+        to--;
+    return lines.slice(from, to);
+}
+const CHECKBOX = /^ {0,1}[-*+]\s+\[[ xX~]\]\s+(.+)$/;
+const NUMBERED = /^ {0,1}(\d{1,3})[.)]\s+(.+)$/;
+const STEP_ID = /^(S\d{1,3})\b[.:)]?\s*/;
+const HEADING = /^#{1,6}\s+(.*)$/;
+const STEPS_HEADING = /步骤|steps|implementation|实施|执行/i;
+/** 计划正文里的步骤；没有可识别的列表返回空数组。 */
+export function parsePlanSteps(markdown) {
+    const lines = markdown.split(/\r?\n/);
+    const outside = linesOutsideFences(lines);
+    const checkbox = outside.flatMap((line) => {
+        const m = CHECKBOX.exec(line);
+        return m === null ? [] : [m[1]];
+    });
+    let raw;
+    if (checkbox.length > 0) {
+        raw = checkbox.map(splitId);
+    }
+    else {
+        const section = stepsSection(outside);
+        raw = section.flatMap((line) => {
+            const m = NUMBERED.exec(line);
+            if (m === null)
+                return [];
+            const item = splitId(m[2]);
+            return [{ id: item.id ?? `S${m[1]}`, text: item.text }];
+        });
+    }
+    const truncated = raw.length > MAX_PLAN_STEPS;
+    const seen = new Set();
+    const steps = raw.slice(0, MAX_PLAN_STEPS).map((item, i) => {
+        let id = item.id ?? `S${i + 1}`;
+        if (seen.has(id))
+            id = `S${i + 1}`;
+        while (seen.has(id))
+            id = `${id}'`;
+        seen.add(id);
+        return annotate(id, item.text);
+    });
+    return { steps, truncated };
+}
+function linesOutsideFences(lines) {
+    const out = [];
+    let fence;
+    for (const line of lines) {
+        const marker = FENCE.exec(line)?.[1];
+        if (marker !== undefined) {
+            if (fence === undefined)
+                fence = marker;
+            else if (marker === fence)
+                fence = undefined;
+            continue;
+        }
+        if (fence === undefined)
+            out.push(line);
+    }
+    return out;
+}
+/** 「步骤 / Steps」小节的行；没有该小节返回全部行。 */
+function stepsSection(lines) {
+    const start = lines.findIndex((line) => {
+        const m = HEADING.exec(line.trim());
+        return m !== null && STEPS_HEADING.test(m[1]);
+    });
+    if (start < 0)
+        return lines;
+    const level = (/^#+/.exec(lines[start].trim())?.[0] ?? "#").length;
+    const out = [];
+    for (const line of lines.slice(start + 1)) {
+        const m = /^(#+)\s/.exec(line.trim());
+        if (m !== null && m[1].length <= level)
+            break;
+        out.push(line);
+    }
+    return out;
+}
+function splitId(text) {
+    const m = STEP_ID.exec(text.trim());
+    return m === null ? { text: text.trim() } : { id: m[1], text: text.trim().slice(m[0].length) };
+}
+const ANNOTATION = /\[(depends|agent)\s*:\s*([^\]]*)\]/gi;
+function annotate(id, text) {
+    const step = { id, text: "" };
+    const cleaned = text.replace(ANNOTATION, (_all, key, value) => {
+        if (key.toLowerCase() === "depends") {
+            const ids = value
+                .split(/[,，\s]+/)
+                .map((v) => v.trim())
+                .filter((v) => v !== "");
+            if (ids.length > 0)
+                step.dependsOn = ids;
+        }
+        else if (value.trim() !== "")
+            step.agent = value.trim();
+        return "";
+    });
+    step.text = cleaned.replace(/\s{2,}/g, " ").trim() || id;
+    return step;
+}

package/dist/plan/prompts.d.ts

@@ -0,0 +1,36 @@
+/**
+ * plan 模式注入给模型的文本（docs/wave5-plan.md §6.2、D18）。[W5-F]
+ *
+ * 全部以 `custom_message`（`display:false`）追加在尾部，投影成 user 消息，不碰 system 节与工具表
+ * （design §9.1）。文本是给模型看的，用英文；界面文案不在这里。
+ */
+import type { PlanData } from "../agent/types.js";
+import type { AgentMessage } from "../session/types.js";
+export declare const PLAN_MODE_TYPE = "ama.plan_mode";
+export declare const PLAN_MODE_EXIT_TYPE = "ama.plan_mode_exit";
+export declare const PLAN_APPROVED_TYPE = "ama.plan_approved";
+/** 完整版（约 400 token）：进入 plan 后首个提示、每第 5 次提醒、压缩之后。 */
+export declare const PLAN_MODE_FULL = "Plan mode is active. You may read and search, run read-only shell commands (ls, cat, grep, rg, find, git status/log/show/diff, \u2026) and start read-only subagents with task. Do not modify files, run builds or tests, or change any state; write/execute tools are refused in this mode.\n\nHow to work:\n1. Explore first. Answer questions from the repository yourself instead of asking the user; ask only about decisions that the code cannot settle.\n2. When you are ready, write the plan as one block, with the tags on their own lines:\n\n<proposed_plan>\n# <title>\n\n## Background\n1\u20133 sentences: the goal and the key facts you found.\n\n## Steps\n- [ ] S1 <action> (files: path/a.ts)\n- [ ] S2 <action> [depends: S1] [agent: <name>]\n\n## Verification\n- <command or check>\n\n## Assumptions and risks\n- <defaults you chose for open questions>\n</proposed_plan>\n\nRules for the plan:\n- Make it specific enough that someone else could carry it out without making further decisions. List the key files; describe a repeated change once.\n- Always include a Verification section.\n- At most one <proposed_plan> block per reply; to revise, rewrite the whole block.\n- Do not ask \"is this OK?\" in prose: the plan block itself is shown to the user for approval.\n- If the user asks you to make changes while plan mode is active, treat it as a request to plan how to make them.\n- Do not use the todo tool to record the plan; the task list is created from the steps when the plan is approved.";
+/** 简版：两次完整版之间每 5 个提示一次。 */
+export declare const PLAN_MODE_BRIEF = "Plan mode is still active: read-only exploration only. Finish with a <proposed_plan> block (Background, Steps as - [ ] S1 \u2026, Verification, Assumptions and risks).";
+/** 手动退出 plan（没有获批的计划）。 */
+export declare const PLAN_MODE_EXIT = "Plan mode has ended. The read-only restrictions no longer apply; the current permission mode decides what you may do.";
+/** 获批交接时开启新回合的用户消息（之后紧跟 `ama.plan_approved`）。 */
+export declare const PLAN_APPROVED_PROMPT = "The plan is approved. Go ahead.";
+/**
+ * 提醒节奏：plan 模式下第 n 个提示（从 1 起）。每 5 个提示提醒一次（第 1、6、11 … 个），
+ * 第 1、6、11 … 次提醒里每第 5 次用完整版（即第 1、26、51 … 个提示）。
+ */
+export declare function reminderKind(promptIndex: number): "full" | "brief" | undefined;
+/**
+ * 交接时怎么记进度：活动工具集里有 `todo` 就用 `todo update`；没有（D20 未过门，`default` 预设不含 todo）
+ * 时请模型在回复里单独一行写 `[DONE:<步骤>]`，由 `done-markers.ts` 读回待办（[W5-Z]）。
+ */
+export interface HandoffOptions {
+    todoTool: boolean;
+}
+/** 交接消息：计划已批准 + plan 模式结束 + 计划全文 + 文件路径 + 进度记法。 */
+export declare function planApprovedText(plan: Pick<PlanData, "markdown" | "filePath" | "steps">, options?: HandoffOptions): string;
+/** 「批准，在新上下文执行」：新会话的首条用户消息。 */
+export declare function freshContextPrompt(plan: Pick<PlanData, "markdown" | "filePath" | "steps">, options?: HandoffOptions): string;
+export declare function planMessage(customType: string, content: string): AgentMessage;