@armadra/agent 0.4.0 → 0.5.0

package/dist/modes/rpc/commands.js

@@ -8,9 +8,14 @@
  * - 审批：`RpcApprovals` 是 UI broker（`set_client_capabilities` 声明 approvals 后挂上），
  *   `permission_response` 按 requestId 作答；先到的回答暂存，等 broker 被问到时取用。
  * - 密钥不离开进程：`get_available_models` 只回 `hasKey` 与 `keySource`。
+ * - [W5-F] 计划：声明 `plans` 能力后计划审批交客户端（`plan_proposed` → `plan_response`），未声明按
+ *   `plan.unattended`；`approve_fresh` 在这里新建会话并以计划全文开新回合。`get_tasks / get_agents`
+ *   读 `RpcContext.tasks / agents`（W5-G 的注册表与发现结果；未装配时回空表）。
  */
 import { formatModelRef } from "../../ai/providers/channels.js";
 import { AgentSessionImpl } from "../../agent/session.js";
+import { planController } from "../../agent/session-plan.js";
+import { currentTodos } from "../../plan/store.js";
 import { getSupportedLevels } from "../../ai/thinking.js";
 import { switchSession } from "../../cli/compose-session.js";
 import { AmaError } from "../../errors.js";
@@ -62,6 +67,17 @@ function impl(session) {
         return session;
     throw new AmaError("not_implemented", "该会话不支持此命令");
 }
+/** [W5-F] 当前会话的计划控制面；会话没有装配 plan 扩展时报 not_implemented。 */
+function plans(ctx) {
+    const controller = planController(ctx.session());
+    if (controller === undefined)
+        throw new AmaError("not_implemented", "该会话没有装配 plan 扩展");
+    return controller;
+}
+/** 声明了 `plans` 能力 → 客户端作答；否则按 `plan.unattended`。换会话后重新应用。 */
+function applyPlanAttendance(ctx) {
+    planController(ctx.session())?.setAttendance(ctx.capabilities.has("plans") ? "client" : "unattended");
+}
 /** 开始一次运行：开始 / 入队 / 被处理后即返回，不等运行结束。 */
 async function startRun(ctx, run) {
     const session = ctx.session();
@@ -89,6 +105,7 @@ async function startRun(ctx, run) {
 async function switched(ctx, next, reason) {
     const session = await next;
     ctx.onSessionChanged(session);
+    applyPlanAttendance(ctx);
     if (session instanceof AgentSessionImpl)
         session.announceStart(reason);
     return { sessionId: session.state.sessionId, sessionFile: session.state.sessionFile };
@@ -213,12 +230,24 @@ export const handlers = {
             ]
             : []),
     }),
+    get_rewind_points: async (_p, ctx) => ({ points: ctx.session().rewindPoints() }),
+    rewind: async (p, ctx) => {
+        const request = { entryId: p.entryId, mode: p.mode };
+        if (p.dryRun !== undefined)
+            request.dryRun = p.dryRun;
+        if (p.onConflict !== undefined)
+            request.onConflict = p.onConflict;
+        return ctx.session().rewind(request);
+    },
+    summarize_from: async (p, ctx) => ctx.session().summarizeFrom(p.entryId, p.instructions),
+    summarize_up_to: async (p, ctx) => ctx.session().summarizeUpTo(p.entryId, p.instructions),
     set_client_capabilities: async (p, ctx) => {
         ctx.capabilities = new Set(p.capabilities);
         const approvals = ctx.capabilities.has("approvals");
         ctx.runtime.approvals.setUiBroker(approvals ? ctx.approvals : undefined);
         if (!approvals)
             ctx.approvals.cancelAll();
+        applyPlanAttendance(ctx);
         return { capabilities: [...ctx.capabilities] };
     },
     permission_response: async (p, ctx) => ({
@@ -264,5 +293,20 @@ export const handlers = {
     },
     get_commands: async (_p, ctx) => ({ commands: commands(ctx.runtime) }),
     get_skills: async (_p, ctx) => ({ skills: ctx.runtime.resources.skills }),
+    // [W5-F] 计划 / 任务命令（docs/wave5-plan.md §6.5、§7.5）
+    plan_response: async (p, ctx) => {
+        const result = await plans(ctx).respond(p);
+        if (result.freshPrompt !== undefined) {
+            const prompt = result.freshPrompt;
+            await switched(ctx, switchSession(ctx.runtime, { kind: "new" }), "new");
+            planController(ctx.session())?.adopt(result.plan);
+            await startRun(ctx, () => ctx.session().prompt(prompt, { origin: "plan" }));
+        }
+        return { planId: result.planId, decision: result.decision };
+    },
+    get_plan: async (p, ctx) => plans(ctx).get(p.planId),
+    get_todos: async (_p, ctx) => ({ items: currentTodos(impl(ctx.session()).manager.branch()) }),
+    get_tasks: async (_p, ctx) => ({ tasks: [...(ctx.tasks?.()?.list() ?? [])] }),
+    get_agents: async (_p, ctx) => ({ agents: [...(ctx.agents?.() ?? [])] }),
 };
 export const RPC_COMMAND_TYPES = Object.keys(handlers);

package/dist/modes/rpc/rpc-mode.js

@@ -19,9 +19,11 @@ import { RPC_PROTOCOL_VERSION } from "../../rpc.js";
 import { AMA_VERSION } from "../../version.js";
 import { toJsonLine, toWireEvent } from "../print/json-event.js";
 import { errorText, onTerminationSignals } from "../shared.js";
+import { sessionAgents, taskRegistryView } from "../../agent/subagent-registry.js";
+import { cachedAgentInfos } from "../../agents/external.js";
 import { RpcApprovals, handlers } from "./commands.js";
 import { createLineReader, writeChunked } from "./jsonl.js";
-export const RPC_CAPABILITIES = ["approvals", "images", "hooks"];
+export const RPC_CAPABILITIES = ["approvals", "images", "hooks", "plans"];
 export async function runRpcMode(runtime, context, options = {}) {
     const stdin = options.stdin ?? process.stdin;
     const stdout = options.stdout ?? process.stdout;
@@ -48,6 +50,10 @@ export async function runRpcMode(runtime, context, options = {}) {
         onBackgroundError(error) {
             void write({ type: "notification", level: "error", message: errorText(error) });
         },
+        // [W5-G] get_tasks / get_agents：当前会话的任务注册表与可用类型
+        tasks: () => taskRegistryView(session.state.sessionId),
+        // [W5-EG] 外部 Agent 的安装 / 版本要异步探测：会话建立时缓存、变化时刷新，未就绪时只列类型目录
+        agents: () => cachedAgentInfos(session.state.sessionId) ?? sessionAgents(session.state.sessionId),
     };
     runtime.notifier.set((message, level) => {
         void write({ type: "notification", level, message });

package/dist/modes/session-report.d.ts

@@ -47,6 +47,17 @@ export declare function warmStopText(reason: string | undefined): string;
 export declare function warmingText(status: WarmerStatus, now: number, minSavingsUsd: number | undefined): string;
 /** 缓存段的键值行（`/session` 与 `/cache` 共用）。 */
 export declare function cacheRows(session: AgentSession, now?: number): KeyValueRow[];
+/** [W5-U] 外部 Agent 用量一项：美元 / token / 请求数按各自单位，不换算。 */
+export declare function externalUsageText(usage: {
+    runs: number;
+    unit: "usd" | "tokens" | "requests";
+    amount: number;
+    tokens?: number;
+}): string;
+/** [W5-U] 「外部 Agent」段（`getStats().external.byAgent`）；没有外部运行时为空。 */
+export declare function externalRows(session: AgentSession): KeyValueRow[];
+/** [W5-U] 子 Agent 任务汇总（`getStats().tasks`）；没有任务时 undefined。 */
+export declare function taskStatsText(session: AgentSession): string | undefined;
 /** 键值行 → 纯文本（键列对齐、去行尾空白）。 */
 export declare function renderRows(rows: readonly KeyValueRow[], indent?: string): string[];
 export declare function describeCache(session: AgentSession, now?: number): string;

package/dist/modes/session-report.js

@@ -219,6 +219,45 @@ export function cacheRows(session, now = Date.now()) {
     }
     return rows;
 }
+/** [W5-U] 外部 Agent 用量一项：美元 / token / 请求数按各自单位，不换算。 */
+export function externalUsageText(usage) {
+    const amount = usage.unit === "usd"
+        ? formatUsd(usage.amount)
+        : usage.unit === "tokens"
+            ? `${formatTokenCount(usage.amount)} token`
+            : `${usage.amount} 次请求`;
+    const tokens = usage.unit !== "tokens" && usage.tokens !== undefined && usage.tokens > 0
+        ? ` · ${formatTokenCount(usage.tokens)} token`
+        : "";
+    return `${usage.runs} 次运行 · ${amount}${tokens}`;
+}
+/** [W5-U] 「外部 Agent」段（`getStats().external.byAgent`）；没有外部运行时为空。 */
+export function externalRows(session) {
+    const byAgent = session.getStats().external?.byAgent ?? {};
+    return Object.entries(byAgent)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([agent, usage]) => ({ key: agent, value: externalUsageText(usage) }));
+}
+/** [W5-U] 子 Agent 任务汇总（`getStats().tasks`）；没有任务时 undefined。 */
+export function taskStatsText(session) {
+    const tasks = session.getStats().tasks;
+    if (tasks === undefined || tasks.total === 0)
+        return undefined;
+    const parts = [`${tasks.total} 个任务`];
+    if (tasks.running > 0)
+        parts.push(`运行中 ${tasks.running}`);
+    const labels = {
+        completed: "完成",
+        failed: "失败",
+        aborted: "已停止",
+        max_turns: "轮数耗尽",
+        interrupted: "已中断",
+    };
+    for (const [status, count] of Object.entries(tasks.byStatus))
+        if (count !== undefined && count > 0)
+            parts.push(`${labels[status] ?? status} ${count}`);
+    return `${parts.join(" · ")}（/tasks）`;
+}
 /** 键值行 → 纯文本（键列对齐、去行尾空白）。 */
 export function renderRows(rows, indent = "") {
     return new KeyValue(rows)
@@ -257,7 +296,15 @@ export function describeSession(session, now = Date.now()) {
             value: `${stats.contextTokens ?? "?"} / ${stats.contextWindow ?? "?"}（${percent}%）`,
         },
     ];
-    return [...renderRows(rows), describeCache(session, now)].join("\n");
+    const tasks = taskStatsText(session);
+    if (tasks !== undefined)
+        rows.push({ key: "子 Agent", value: tasks });
+    const external = externalRows(session);
+    return [
+        ...renderRows(rows),
+        describeCache(session, now),
+        ...(external.length > 0 ? ["外部 Agent", ...renderRows(external, "  ")] : []),
+    ].join("\n");
 }
 /** `/cache fingerprint`：最近一次真实请求的前缀指纹（system / tools 哈希与模型）。 */
 export function describeFingerprint(session) {

package/dist/permissions/auto-safe.d.ts

@@ -58,3 +58,8 @@ export interface BashAutoAnalysis {
 }
 /** auto 模式下一条 bash 命令的规则层与静态判定结论。 */
 export declare function analyzeBashForAuto(command: string, options: BashAutoOptions): BashAutoAnalysis;
+/**
+ * [S2] 命令文本里出现的机密路径（读写都算，含嵌套命令）；没有返回 undefined。default 模式「沙箱内免审批」
+ * 用它把 `cat .env` 之类留给正常审批：OS 沙箱挡不住读工作区里的机密文件，输出会进模型上下文。
+ */
+export declare function secretReferenceReason(command: string, cwd: string): string | undefined;

package/dist/permissions/auto-safe.js

@@ -527,3 +527,21 @@ export function analyzeBashForAuto(command, options) {
     }
     return { safe: true, reason: "every command is in the auto safe list" };
 }
+/**
+ * [S2] 命令文本里出现的机密路径（读写都算，含嵌套命令）；没有返回 undefined。default 模式「沙箱内免审批」
+ * 用它把 `cat .env` 之类留给正常审批：OS 沙箱挡不住读工作区里的机密文件，输出会进模型上下文。
+ */
+export function secretReferenceReason(command, cwd) {
+    const nested = collectNestedCommands(command);
+    for (const text of [command, ...nested.commands]) {
+        for (const segment of splitShellSegments(text)) {
+            const { argv, redirects } = parseSegment(segment);
+            for (const word of [...argv.slice(1), ...redirects.inputs, ...redirects.outputs]) {
+                const reason = secretInWord(word, cwd);
+                if (reason !== undefined)
+                    return reason;
+            }
+        }
+    }
+    return undefined;
+}

package/dist/permissions/classifier.d.ts

@@ -24,6 +24,10 @@ export interface ClassifierRequest {
     projectRoot: string;
     /** 最近一条用户消息（会被截断）。 */
     userMessage?: string;
+    /** [S2] bash 将经 OS 沙箱运行（写入只限工作区与临时目录、网络按配置）：交给分类器作为输入之一。 */
+    sandbox?: {
+        network: "deny" | "allow";
+    };
 }
 export interface ClassifierVerdict {
     decision: "allow" | "ask";

package/dist/permissions/classifier.js

@@ -65,6 +65,8 @@ export function buildClassifierPrompt(request) {
         `project_root: ${neutralize(JSON.stringify(request.projectRoot))}`,
         `arguments_json: ${neutralize(args)}`,
     ];
+    if (request.sandbox !== undefined)
+        lines.push(`os_sandbox: "writes limited to the project and temp dirs; network ${request.sandbox.network === "deny" ? "blocked" : "allowed"}"`);
     if (request.userMessage !== undefined && request.userMessage.trim() !== "") {
         const summary = truncate(request.userMessage.replace(/\s+/g, " ").trim(), CLASSIFIER_USER_LIMIT);
         lines.push(`latest_user_message: ${neutralize(JSON.stringify(summary))}`);

package/dist/permissions/modes.js

@@ -8,7 +8,7 @@ import { PERMISSION_MODES_STRICT_FIRST } from "./types.js";
 export const PERMISSION_MODE_INFO = {
     default: { label: "Manual", description: "写文件、执行命令前询问" },
     "auto-edit": { label: "Accept edits", description: "自动接受文件编辑，执行命令仍询问" },
-    plan: { label: "Plan", description: "只读，不改文件、不跑命令" },
+    plan: { label: "Plan", description: "只读调研，只跑只读命令，出计划后审批执行" },
     auto: { label: "Auto", description: "由 ama 判断每一步：安全的自动放行，有风险的才问" },
     "full-auto": { label: "Bypass permissions", description: "全部放行（危险命令仍询问）" },
     allowlist: {

package/dist/permissions/pipeline.d.ts

@@ -3,7 +3,8 @@
  *
  *   ① deny 规则 ∪ Hook deny                         → deny
  *   ② 危险命令（仅 bash）                            → ask（无人值守 deny），之后各步不能放宽
- *   ③ 模式：plan  read 允许，write / execute deny
+ *   ③ 模式：plan  read 允许，write / execute deny（[W5-F] 细化见 {@link planDecision}：只读 bash、
+ *                 task 放行，`todo set / update` 拒绝）
  *           default  read 允许，write / execute 问
  *           auto-edit read / write 允许，execute 问
  *           full-auto 全部允许
@@ -16,23 +17,45 @@
  * 安全名单里的 bash）→ allow；都没决定 → ask 且 `classify: true`，由调用方问模型分类器（分类器只能
  * 把它变 allow）。每个结论带 `auto{layer, decision, reason}`。
  *
- * allowlist：①② 同上；只读工具与 allow 规则 / Hook allow 命中放行，其余 deny——从不询问（危险命令、
- * Hook ask 也 deny）。
+ * allowlist：①② 同上；只读工具、只读 bash（[W5-F] 与 plan 同一子集，保持 plan ⊆ allowlist）与
+ * allow 规则 / Hook allow 命中放行，task 同 plan 放行（子会话共用本管线），其余 deny——从不询问
+ * （危险命令、Hook ask 也 deny）。
  *
  * allow_session 记忆（内存，不落盘）：bash 记命令的前两个词（`npm test`），之后以它开头的命令
  * 命中；带 path 的工具记文件所在目录，之后该目录下的路径命中；其它工具只记工具名。
  * 记忆只作用于第 ③ 步模式产生的 ask（auto 里只作用于规则层之后）。
  *
+ * [S2] bash 沙箱（docs/permissions.md「判定顺序」）：default / auto-edit 下，bash 调用若将在 OS 沙箱内
+ * 运行且沙箱拒绝网络、没请求 `sandbox: false`、命令文本不碰机密路径、嵌套不超深，第 ③ 步的 ask 变
+ * allow（`sandboxed: true`）；①② 与 Hook ask 照旧优先。auto 下沙箱不直接放行，只作为分类器输入；
+ * 请求 `sandbox: false` 越出沙箱时规则层询问（allow 规则 / Hook allow / 会话记忆仍可放行）。
+ *
  * 包装里的命令（`sh -c '…'`、`eval`、`xargs`、`find -exec`，见 dangerous.ts）逐层核对：deny 规则命中
  * 任一层即 deny；allow 规则与会话记忆要求外层与每一层嵌套命令都被覆盖，嵌套超深时不放行。
  */
 import type { AutoAuditEntry, AutoDecision, Decision, PermissionCheckInput, PermissionMode, PermissionPipelineApi, PermissionVerdict, Rule } from "./types.js";
 import type { ToolPermission } from "../tools/types.js";
+import { type BashSandbox } from "../sandbox/bash.js";
+import type { PlanBashMode } from "../config/types-w5.js";
 /**
  * 第 ③ 步的模式真值表（不看输入）。auto 的 write / execute 在这里是 ask，真正的结论由规则层、
  * 静态判定与分类器给出；allowlist 的 write / execute 是 deny（allow 规则可放行）。
  */
 export declare function modeDecision(mode: PermissionMode, permission: ToolPermission): Decision;
+/** [W5-F] plan 模式拒绝写 / 执行时的说明：带指引，提醒被压缩掉后模型也能从拒绝结果里恢复。 */
+export declare const PLAN_MODE_MESSAGE = "Plan mode is active: write/execute tools are disabled. Finish the plan with a <proposed_plan> block.";
+/** [W5-F] plan 下 `todo set / update` 的拒绝说明（计划与清单分开，避免跳过审批）。 */
+export declare const PLAN_TODO_MESSAGE = "Plan mode is active: the todo list is created from the approved plan. Write the steps in a <proposed_plan> block instead.";
+/**
+ * [W5-F] plan 模式第 ③ 步（输入可见，docs/wave5-plan.md §6.2）：
+ * read 放行（`todo` 只放行 get）；bash 按 `plan.bash`（readonly：只读子集放行其余拒绝；ask：其余询问；
+ * deny：全拒）；task 放行（子会话共用同一管线，同样处在 plan）；其余 write / execute 拒绝。
+ * 返回 undefined = 交给通常的模式真值表。
+ */
+export declare function planDecision(input: Pick<PermissionCheckInput, "toolName" | "permission" | "input">, planBash: PlanBashMode, cwd: string, projectRoot?: string): {
+    decision: Decision;
+    message?: string;
+};
 export declare const UNATTENDED_MESSAGE = "This tool call requires approval, but no one is available to approve it (unattended mode).";
 export declare const ALLOWLIST_MESSAGE = "Not in the allowlist (\u4E0D\u5728\u5141\u8BB8\u540D\u5355): permission mode \"allowlist\" only runs read-only tools and calls matched by an allow rule, and never asks.";
 interface SessionGrant {
@@ -49,6 +72,10 @@ export interface PermissionPipelineOptions {
     projectRoot?: string;
     /** auto：安全名单追加（`permission.autoSafeCommands`）。 */
     autoSafeCommands?: readonly string[];
+    /** [W5-F] plan 模式下的 bash（config `plan.bash`），缺省 readonly。 */
+    planBash?: PlanBashMode;
+    /** [S2] bash 的 OS 沙箱设定（与 bash 工具用同一份，保证「会不会在沙箱里跑」两边结论一致）。 */
+    bashSandbox?: BashSandbox;
 }
 export declare class PermissionPipeline implements PermissionPipelineApi {
     private currentMode;
@@ -58,16 +85,28 @@ export declare class PermissionPipeline implements PermissionPipelineApi {
     readonly cwd: string;
     readonly projectRoot: string;
     readonly autoSafeCommands: readonly string[];
+    private planBashMode;
+    readonly bashSandbox: BashSandbox | undefined;
     constructor(options: PermissionPipelineOptions);
     get mode(): PermissionMode;
     setMode(mode: PermissionMode): void;
+    /** [W5-F] config `plan.bash`（plan 扩展在会话装配时设置）。 */
+    get planBash(): PlanBashMode;
+    setPlanBash(mode: PlanBashMode): void;
     get rules(): readonly Rule[];
     rememberForSession(toolName: string, input: unknown): void;
     clearSessionGrants(): void;
     recordAutoDecision(toolName: string, input: unknown, decision: AutoDecision): void;
     autoDecisions(): readonly AutoAuditEntry[];
-    check(input: PermissionCheckInput): PermissionVerdict;
+    check(request: PermissionCheckInput): PermissionVerdict;
     private evaluate;
+    /**
+     * [S2] default / auto-edit 的「沙箱内免审批」：将在沙箱内运行、沙箱拒绝网络（联网可外带数据）、
+     * 命令文本不碰机密路径（沙箱挡不住读工作区里的 `.env`）、嵌套不超深。
+     */
+    private sandboxAllows;
+    /** [S2] 沙箱生效时请求 `sandbox: false` 越出沙箱。 */
+    private escapesSandbox;
     /** allow 规则（每层都覆盖）/ Hook allow / 会话记忆；都不命中返回 undefined。 */
     private allowedBy;
     /** auto 规则层（受保护路径、项目外写入、网络、删除类）要询问的原因。 */

package/dist/permissions/pipeline.js

@@ -3,7 +3,8 @@
  *
  *   ① deny 规则 ∪ Hook deny                         → deny
  *   ② 危险命令（仅 bash）                            → ask（无人值守 deny），之后各步不能放宽
- *   ③ 模式：plan  read 允许，write / execute deny
+ *   ③ 模式：plan  read 允许，write / execute deny（[W5-F] 细化见 {@link planDecision}：只读 bash、
+ *                 task 放行，`todo set / update` 拒绝）
  *           default  read 允许，write / execute 问
  *           auto-edit read / write 允许，execute 问
  *           full-auto 全部允许
@@ -16,20 +17,29 @@
  * 安全名单里的 bash）→ allow；都没决定 → ask 且 `classify: true`，由调用方问模型分类器（分类器只能
  * 把它变 allow）。每个结论带 `auto{layer, decision, reason}`。
  *
- * allowlist：①② 同上；只读工具与 allow 规则 / Hook allow 命中放行，其余 deny——从不询问（危险命令、
- * Hook ask 也 deny）。
+ * allowlist：①② 同上；只读工具、只读 bash（[W5-F] 与 plan 同一子集，保持 plan ⊆ allowlist）与
+ * allow 规则 / Hook allow 命中放行，task 同 plan 放行（子会话共用本管线），其余 deny——从不询问
+ * （危险命令、Hook ask 也 deny）。
  *
  * allow_session 记忆（内存，不落盘）：bash 记命令的前两个词（`npm test`），之后以它开头的命令
  * 命中；带 path 的工具记文件所在目录，之后该目录下的路径命中；其它工具只记工具名。
  * 记忆只作用于第 ③ 步模式产生的 ask（auto 里只作用于规则层之后）。
  *
+ * [S2] bash 沙箱（docs/permissions.md「判定顺序」）：default / auto-edit 下，bash 调用若将在 OS 沙箱内
+ * 运行且沙箱拒绝网络、没请求 `sandbox: false`、命令文本不碰机密路径、嵌套不超深，第 ③ 步的 ask 变
+ * allow（`sandboxed: true`）；①② 与 Hook ask 照旧优先。auto 下沙箱不直接放行，只作为分类器输入；
+ * 请求 `sandbox: false` 越出沙箱时规则层询问（allow 规则 / Hook allow / 会话记忆仍可放行）。
+ *
  * 包装里的命令（`sh -c '…'`、`eval`、`xargs`、`find -exec`，见 dangerous.ts）逐层核对：deny 规则命中
  * 任一层即 deny；allow 规则与会话记忆要求外层与每一层嵌套命令都被覆盖，嵌套超深时不放行。
  */
 import { dirname, sep } from "node:path";
+import { isBackgroundJobQuery } from "../tools/background-jobs.js";
 import { findAllowRule, findDenyRule, inputCommand, inputPath, normalizeCommand, splitShellSegments, } from "./rules.js";
 import { collectNestedCommands, matchDangerous } from "./dangerous.js";
-import { analyzeBashForAuto } from "./auto-safe.js";
+import { analyzeBashForAuto, secretReferenceReason } from "./auto-safe.js";
+import { runsSandboxed, wantsUnsandboxed } from "../sandbox/bash.js";
+import { isReadonlyBash } from "./readonly-bash.js";
 import { secretPathReason, writeProtectionReason } from "./protected.js";
 import { AUTO_AUDIT_LIMIT } from "./types.js";
 /** bash 调用拆成「外层 + 每层嵌套命令」各自的输入；嵌套超深时 tooDeep 为真。非 bash 原样返回。 */
@@ -56,6 +66,42 @@ export function modeDecision(mode, permission) {
         return permission === "write" ? "allow" : "ask";
     return "ask";
 }
+/** [W5-F] plan 模式拒绝写 / 执行时的说明：带指引，提醒被压缩掉后模型也能从拒绝结果里恢复。 */
+export const PLAN_MODE_MESSAGE = "Plan mode is active: write/execute tools are disabled. Finish the plan with a <proposed_plan> block.";
+/** [W5-F] plan 下 `todo set / update` 的拒绝说明（计划与清单分开，避免跳过审批）。 */
+export const PLAN_TODO_MESSAGE = "Plan mode is active: the todo list is created from the approved plan. Write the steps in a <proposed_plan> block instead.";
+/**
+ * [W5-F] plan 模式第 ③ 步（输入可见，docs/wave5-plan.md §6.2）：
+ * read 放行（`todo` 只放行 get）；bash 按 `plan.bash`（readonly：只读子集放行其余拒绝；ask：其余询问；
+ * deny：全拒）；task 放行（子会话共用同一管线，同样处在 plan）；其余 write / execute 拒绝。
+ * 返回 undefined = 交给通常的模式真值表。
+ */
+export function planDecision(input, planBash, cwd, projectRoot = cwd) {
+    const { toolName, permission } = input;
+    if (toolName === "todo") {
+        const action = typeof input.input === "object" && input.input !== null
+            ? input.input["action"]
+            : undefined;
+        return action === "get"
+            ? { decision: "allow" }
+            : { decision: "deny", message: PLAN_TODO_MESSAGE };
+    }
+    if (permission === "read")
+        return { decision: "allow" };
+    if (toolName === "task")
+        return { decision: "allow" };
+    if (toolName === "bash") {
+        if (planBash === "deny")
+            return { decision: "deny", message: PLAN_MODE_MESSAGE };
+        const command = inputCommand(input.input);
+        if (command !== undefined && isReadonlyBash(command, { cwd, projectRoot }))
+            return { decision: "allow" };
+        return planBash === "ask"
+            ? { decision: "ask" }
+            : { decision: "deny", message: PLAN_MODE_MESSAGE };
+    }
+    return { decision: "deny", message: PLAN_MODE_MESSAGE };
+}
 export const UNATTENDED_MESSAGE = "This tool call requires approval, but no one is available to approve it (unattended mode).";
 export const ALLOWLIST_MESSAGE = 'Not in the allowlist (不在允许名单): permission mode "allowlist" only runs read-only tools and calls matched by an allow rule, and never asks.';
 /** 审计摘要：bash 取命令，带 path 的取路径，其它取工具名；单行、截断。 */
@@ -103,8 +149,12 @@ export class PermissionPipeline {
     cwd;
     projectRoot;
     autoSafeCommands;
+    planBashMode;
+    bashSandbox;
     constructor(options) {
+        this.bashSandbox = options.bashSandbox;
         this.currentMode = options.mode;
+        this.planBashMode = options.planBash ?? "readonly";
         this.ruleList = [...options.rules];
         this.cwd = options.cwd;
         this.projectRoot = options.projectRoot ?? options.cwd;
@@ -116,6 +166,13 @@ export class PermissionPipeline {
     setMode(mode) {
         this.currentMode = mode;
     }
+    /** [W5-F] config `plan.bash`（plan 扩展在会话装配时设置）。 */
+    get planBash() {
+        return this.planBashMode;
+    }
+    setPlanBash(mode) {
+        this.planBashMode = mode;
+    }
     get rules() {
         return this.ruleList;
     }
@@ -138,7 +195,11 @@ export class PermissionPipeline {
     autoDecisions() {
         return [...this.audit];
     }
-    check(input) {
+    check(request) {
+        // [W5-H2] 后台 bash 的查询（bash{job, action}，不带 command）只读 / 结束本会话自己启动的任务：按 read
+        const input = isBackgroundJobQuery(request.toolName, request.input)
+            ? { ...request, permission: "read" }
+            : request;
         const verdict = this.evaluate(input);
         if (this.currentMode === "auto" && verdict.auto === undefined) {
             verdict.auto = {
@@ -200,13 +261,16 @@ export class PermissionPipeline {
             return this.evaluateAuto(input, layers, command);
         if (this.currentMode === "allowlist")
             return this.evaluateAllowlist(input, layers);
-        // ③ 模式
-        const byMode = modeDecision(this.currentMode, permission);
+        // ③ 模式（plan 细化见 planDecision）
+        const plan = this.currentMode === "plan"
+            ? planDecision(input, this.planBashMode, this.cwd, this.projectRoot)
+            : undefined;
+        const byMode = plan?.decision ?? modeDecision(this.currentMode, permission);
         if (byMode === "deny") {
             return {
                 decision: "deny",
                 step: "mode",
-                message: `Permission mode "${this.currentMode}" allows only read-only tools`,
+                message: plan?.message ?? PLAN_MODE_MESSAGE,
             };
         }
         let verdict = byMode === "allow"
@@ -228,6 +292,10 @@ export class PermissionPipeline {
             else if (granted) {
                 verdict = { decision: "allow", step: "session" };
             }
+            else if ((this.currentMode === "default" || this.currentMode === "auto-edit") &&
+                this.sandboxAllows(input, command, layers.tooDeep)) {
+                verdict = { decision: "allow", step: "mode", sandboxed: true };
+            }
         }
         if (input.hookDecision === "ask") {
             const reason = "hook";
@@ -240,6 +308,25 @@ export class PermissionPipeline {
         }
         return verdict;
     }
+    /**
+     * [S2] default / auto-edit 的「沙箱内免审批」：将在沙箱内运行、沙箱拒绝网络（联网可外带数据）、
+     * 命令文本不碰机密路径（沙箱挡不住读工作区里的 `.env`）、嵌套不超深。
+     */
+    sandboxAllows(input, command, tooDeep) {
+        if (input.toolName !== "bash" || command === undefined || tooDeep)
+            return false;
+        if (!runsSandboxed(this.bashSandbox, input.input))
+            return false;
+        if (this.bashSandbox?.network !== "deny")
+            return false;
+        return secretReferenceReason(command, this.cwd) === undefined;
+    }
+    /** [S2] 沙箱生效时请求 `sandbox: false` 越出沙箱。 */
+    escapesSandbox(input) {
+        return (input.toolName === "bash" &&
+            this.bashSandbox?.active === true &&
+            wantsUnsandboxed(input.input));
+    }
     /** allow 规则（每层都覆盖）/ Hook allow / 会话记忆；都不命中返回 undefined。 */
     allowedBy(input, layers, useGrants) {
         const { toolName } = input;
@@ -329,6 +416,16 @@ export class PermissionPipeline {
                     : "allowed for this session";
             return { ...allowed, auto: rule("allow", reason) };
         }
+        if (this.escapesSandbox(input)) {
+            const why = "runs outside the OS sandbox (sandbox:false)";
+            return {
+                decision: "ask",
+                step: "auto-rule",
+                approvalReason: "mode",
+                message: `Auto mode asks before this: ${why}`,
+                auto: rule("ask", why),
+            };
+        }
         const fixed = (reason) => ({
             decision: "allow",
             step: "auto-static",
@@ -349,6 +446,9 @@ export class PermissionPipeline {
             step: "auto-classify",
             approvalReason: "mode",
             classify: true,
+            ...(command !== undefined && runsSandboxed(this.bashSandbox, input.input)
+                ? { sandboxed: true }
+                : {}),
             auto: {
                 layer: "classifier",
                 decision: "ask",
@@ -364,7 +464,12 @@ export class PermissionPipeline {
         });
         if (input.hookDecision === "ask")
             return deny(input.hookReason);
-        if (input.permission === "read")
+        // task 与 plan 同样放行：子会话共用本管线，同样只放行只读与名单内调用
+        if (input.permission === "read" || input.toolName === "task")
+            return { decision: "allow", step: "mode" };
+        const command = input.toolName === "bash" ? inputCommand(input.input) : undefined;
+        if (command !== undefined &&
+            isReadonlyBash(command, { cwd: this.cwd, projectRoot: this.projectRoot }))
             return { decision: "allow", step: "mode" };
         return this.allowedBy(input, layers, false) ?? deny();
     }

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;