@armadra/agent 0.3.0 → 0.5.0

package/dist/permissions/pipeline.js

@@ -1,9 +1,10 @@
 /**
- * 权限管线（设计 §6.3 第 3 步、§7.1、D11）。[B3]
+ * 权限管线（设计 §6.3 第 3 步、§7.1、§7.4、D11）。[B3]
  *
  *   ① 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 全部允许
@@ -11,16 +12,36 @@
  *      Hook ask：随后把 allow 变 ask——净效果是 Hook ask 总得到 ask（reason "hook"，对话框显示 Hook 的 reason）
  *   无人值守：最终 ask → deny。
  *
+ * auto（§7.4）：①② 同上；规则层再把受保护路径、项目外写入、网络命令、删除类命令判 ask（不能被 allow
+ * 规则越过）；Hook ask → ask；allow 规则 / Hook allow / 会话记忆 → allow；静态判定（只读工具、项目内写入、
+ * 安全名单里的 bash）→ allow；都没决定 → ask 且 `classify: true`，由调用方问模型分类器（分类器只能
+ * 把它变 allow）。每个结论带 `auto{layer, decision, reason}`。
+ *
+ * allowlist：①② 同上；只读工具、只读 bash（[W5-F] 与 plan 同一子集，保持 plan ⊆ allowlist）与
+ * allow 规则 / Hook allow 命中放行，task 同 plan 放行（子会话共用本管线），其余 deny——从不询问
+ * （危险命令、Hook ask 也 deny）。
+ *
  * allow_session 记忆（内存，不落盘）：bash 记命令的前两个词（`npm test`），之后以它开头的命令
  * 命中；带 path 的工具记文件所在目录，之后该目录下的路径命中；其它工具只记工具名。
- * 记忆只作用于第 ③ 步模式产生的 ask。
+ * 记忆只作用于第 ③ 步模式产生的 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, 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 原样返回。 */
 function layeredInputs(toolName, input) {
     const command = toolName === "bash" ? inputCommand(input) : undefined;
@@ -32,17 +53,67 @@ function layeredInputs(toolName, input) {
         tooDeep: nested.tooDeep,
     };
 }
-/** 第 ③ 步的模式真值表。 */
+/**
+ * 第 ③ 步的模式真值表（不看输入）。auto 的 write / execute 在这里是 ask，真正的结论由规则层、
+ * 静态判定与分类器给出；allowlist 的 write / execute 是 deny（allow 规则可放行）。
+ */
 export function modeDecision(mode, permission) {
     if (permission === "read" || mode === "full-auto")
         return "allow";
-    if (mode === "plan")
+    if (mode === "plan" || mode === "allowlist")
         return "deny";
     if (mode === "auto-edit")
         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 的取路径，其它取工具名；单行、截断。 */
+function auditSummary(toolName, input) {
+    const command = inputCommand(input);
+    const raw = command ??
+        (typeof input === "object" && input !== null
+            ? input["path"]
+            : undefined);
+    const text = typeof raw === "string" ? raw.replace(/\s+/g, " ").trim() : toolName;
+    return text.length > 80 ? `${text.slice(0, 79)}…` : text;
+}
 export function sessionGrantFor(toolName, input, cwd) {
     const command = inputCommand(input);
     if (command !== undefined) {
@@ -74,11 +145,20 @@ export class PermissionPipeline {
     currentMode;
     ruleList;
     grants = [];
+    audit = [];
     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;
+        this.autoSafeCommands = [...(options.autoSafeCommands ?? [])];
     }
     get mode() {
         return this.currentMode;
@@ -86,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;
     }
@@ -95,8 +182,32 @@ export class PermissionPipeline {
     clearSessionGrants() {
         this.grants.length = 0;
     }
-    check(input) {
+    recordAutoDecision(toolName, input, decision) {
+        this.audit.push({
+            ...decision,
+            at: Date.now(),
+            toolName,
+            summary: auditSummary(toolName, input),
+        });
+        if (this.audit.length > AUTO_AUDIT_LIMIT)
+            this.audit.splice(0, this.audit.length - AUTO_AUDIT_LIMIT);
+    }
+    autoDecisions() {
+        return [...this.audit];
+    }
+    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 = {
+                layer: "rule",
+                decision: verdict.decision,
+                reason: verdict.message ?? verdict.step,
+            };
+        }
         if (verdict.decision === "ask" && input.unattended) {
             return { ...verdict, decision: "deny", message: UNATTENDED_MESSAGE };
         }
@@ -131,20 +242,35 @@ export class PermissionPipeline {
         const command = toolName === "bash" ? inputCommand(input.input) : undefined;
         const danger = command !== undefined ? matchDangerous(command) : undefined;
         if (danger) {
-            return {
+            const message = `Potentially dangerous command: ${danger.description}`;
+            if (this.currentMode === "allowlist") {
+                return { decision: "deny", step: "allowlist", message: `${ALLOWLIST_MESSAGE} ${message}` };
+            }
+            const verdict = {
                 decision: "ask",
                 step: "dangerous",
                 approvalReason: "dangerous",
-                message: `Potentially dangerous command: ${danger.description}`,
+                message,
             };
+            if (this.currentMode === "auto") {
+                verdict.auto = { layer: "rule", decision: "ask", reason: danger.description };
+            }
+            return verdict;
         }
-        // ③ 模式
-        const byMode = modeDecision(this.currentMode, permission);
+        if (this.currentMode === "auto")
+            return this.evaluateAuto(input, layers, command);
+        if (this.currentMode === "allowlist")
+            return this.evaluateAllowlist(input, layers);
+        // ③ 模式（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"
@@ -166,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";
@@ -178,4 +308,169 @@ 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;
+        const allow = layers.tooDeep
+            ? undefined
+            : findAllowRule(this.ruleList, toolName, input.input, this.cwd);
+        if (allow !== undefined &&
+            layers.inputs.every((l) => findAllowRule(this.ruleList, toolName, l, this.cwd))) {
+            return { decision: "allow", step: "allow-rule", rule: allow };
+        }
+        if (input.hookDecision === "allow")
+            return { decision: "allow", step: "hook" };
+        if (useGrants &&
+            !layers.tooDeep &&
+            layers.inputs.every((l) => this.grants.some((g) => grantCovers(g, toolName, l, this.cwd)))) {
+            return { decision: "allow", step: "session" };
+        }
+        return undefined;
+    }
+    /** auto 规则层（受保护路径、项目外写入、网络、删除类）要询问的原因。 */
+    autoRuleReason(input, command) {
+        if (command !== undefined) {
+            const analysis = analyzeBashForAuto(command, {
+                cwd: this.cwd,
+                projectRoot: this.projectRoot,
+                extraSafe: this.autoSafeCommands,
+            });
+            const out = {
+                bashSafe: analysis.safe,
+                bashReason: analysis.reason,
+            };
+            if (analysis.ask !== undefined)
+                out.ask = analysis.ask;
+            return out;
+        }
+        const raw = typeof input.input === "object" && input.input !== null
+            ? input.input["path"]
+            : undefined;
+        if (typeof raw !== "string" && input.permission !== "write")
+            return {};
+        const path = inputPath(input.toolName, input.input, this.cwd);
+        if (path === undefined)
+            return {};
+        const secret = secretPathReason(path);
+        if (secret !== undefined)
+            return { ask: secret };
+        if (input.permission === "write") {
+            const reason = writeProtectionReason(path, this.projectRoot);
+            if (reason !== undefined)
+                return { ask: reason };
+        }
+        return {};
+    }
+    evaluateAuto(input, layers, command) {
+        const rule = (decision, reason) => ({
+            layer: "rule",
+            decision,
+            reason,
+        });
+        const checked = this.autoRuleReason(input, command);
+        if (checked.ask !== undefined) {
+            return {
+                decision: "ask",
+                step: "auto-rule",
+                approvalReason: "mode",
+                message: `Auto mode asks before this: ${checked.ask}`,
+                auto: rule("ask", checked.ask),
+            };
+        }
+        if (input.hookDecision === "ask") {
+            const verdict = {
+                decision: "ask",
+                step: "hook",
+                approvalReason: "hook",
+                auto: rule("ask", input.hookReason ?? "PreToolUse hook asked"),
+            };
+            if (input.hookReason !== undefined)
+                verdict.message = input.hookReason;
+            return verdict;
+        }
+        const allowed = this.allowedBy(input, layers, true);
+        if (allowed !== undefined) {
+            const reason = allowed.step === "allow-rule"
+                ? `allow rule ${allowed.rule?.raw ?? ""}`.trim()
+                : allowed.step === "hook"
+                    ? "PreToolUse hook allowed"
+                    : "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",
+            auto: { layer: "static", decision: "allow", reason },
+        });
+        if (input.permission === "read")
+            return fixed("read-only tool");
+        if (command !== undefined && checked.bashSafe === true) {
+            return fixed(checked.bashReason ?? "safe command");
+        }
+        if (command === undefined && input.permission === "write") {
+            const path = inputPath(input.toolName, input.input, this.cwd);
+            if (path !== undefined)
+                return fixed("write inside the project");
+        }
+        return {
+            decision: "ask",
+            step: "auto-classify",
+            approvalReason: "mode",
+            classify: true,
+            ...(command !== undefined && runsSandboxed(this.bashSandbox, input.input)
+                ? { sandboxed: true }
+                : {}),
+            auto: {
+                layer: "classifier",
+                decision: "ask",
+                reason: checked.bashReason ?? `${input.toolName} needs a judgement`,
+            },
+        };
+    }
+    evaluateAllowlist(input, layers) {
+        const deny = (why) => ({
+            decision: "deny",
+            step: "allowlist",
+            message: why === undefined ? ALLOWLIST_MESSAGE : `${ALLOWLIST_MESSAGE} ${why}`,
+        });
+        if (input.hookDecision === "ask")
+            return deny(input.hookReason);
+        // 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/protected.d.ts

@@ -0,0 +1,19 @@
+/**
+ * auto 模式规则层的受保护路径（§7.4，docs/permissions.md「规则层」）。
+ *
+ * - **机密路径**（读写都询问）：`.env` / `.env.*`（`.example` / `.sample` / `.template` / `.dist` 除外）、
+ *   `*.env`、`.ssh/`、`.gnupg/`、`.aws/`、`.kube/config`、`.docker/config.json`、`.config/gcloud/`、
+ *   `.netrc`、`.pgpass`、`.git-credentials`、私钥（`id_rsa` 等、`*.pem`、`*.key`、`*.p12`、`*.pfx`、
+ *   `*.jks`、`*.keystore`、`*.ppk`）、ama 自己的 `ama/auth.json`。
+ * - **受保护写入**（只对写询问）：机密路径，`.git` 目录内部，项目里的 `.ama/`（Hook 与配置可能借此放宽），
+ *   项目目录外的任何路径（`/dev/null`、`/dev/stdout`、`/dev/stderr`、`/dev/tty` 除外）。
+ *
+ * 判断按词法路径（不跟随符号链接，与规则匹配一致）。返回英文短说明（进审计与 tool_result），
+ * 不受保护返回 undefined。
+ */
+/** 机密文件或目录：读与写都要询问。 */
+export declare function secretPathReason(absPath: string): string | undefined;
+/** 写入受保护的原因：机密、`.git` 内部、项目 `.ama/`、项目外；可以写返回 undefined。 */
+export declare function writeProtectionReason(absPath: string, projectRoot: string): string | undefined;
+/** 是否在项目目录内（含项目根本身）。 */
+export declare function insideProject(absPath: string, projectRoot: string): boolean;

package/dist/permissions/protected.js

@@ -0,0 +1,74 @@
+/**
+ * auto 模式规则层的受保护路径（§7.4，docs/permissions.md「规则层」）。
+ *
+ * - **机密路径**（读写都询问）：`.env` / `.env.*`（`.example` / `.sample` / `.template` / `.dist` 除外）、
+ *   `*.env`、`.ssh/`、`.gnupg/`、`.aws/`、`.kube/config`、`.docker/config.json`、`.config/gcloud/`、
+ *   `.netrc`、`.pgpass`、`.git-credentials`、私钥（`id_rsa` 等、`*.pem`、`*.key`、`*.p12`、`*.pfx`、
+ *   `*.jks`、`*.keystore`、`*.ppk`）、ama 自己的 `ama/auth.json`。
+ * - **受保护写入**（只对写询问）：机密路径，`.git` 目录内部，项目里的 `.ama/`（Hook 与配置可能借此放宽），
+ *   项目目录外的任何路径（`/dev/null`、`/dev/stdout`、`/dev/stderr`、`/dev/tty` 除外）。
+ *
+ * 判断按词法路径（不跟随符号链接，与规则匹配一致）。返回英文短说明（进审计与 tool_result），
+ * 不受保护返回 undefined。
+ */
+import { basename, relative } from "node:path";
+import { isWithin, toPosix } from "../tools/paths.js";
+const ENV_EXEMPT = /\.(example|sample|template|dist)$/i;
+const KEY_FILE = /^id_(rsa|dsa|ecdsa|ed25519)(_sk)?$/;
+const KEY_EXT = /\.(pem|key|p12|pfx|jks|keystore|ppk)$/i;
+const SECRET_DIRS = new Set([".ssh", ".gnupg", ".aws"]);
+const SECRET_FILES = new Set([".netrc", ".pgpass", ".git-credentials"]);
+const DEVICE_SINKS = new Set(["/dev/null", "/dev/stdout", "/dev/stderr", "/dev/tty"]);
+function segments(absPath) {
+    return toPosix(absPath).split("/").filter(Boolean);
+}
+/** 机密文件或目录：读与写都要询问。 */
+export function secretPathReason(absPath) {
+    const parts = segments(absPath);
+    const name = basename(absPath);
+    if ((/^\.env(\..+)?$/.test(name) || /\.env$/.test(name)) && !ENV_EXEMPT.test(name)) {
+        return `secret file ${name}`;
+    }
+    if (KEY_FILE.test(name) || KEY_EXT.test(name))
+        return `private key or certificate ${name}`;
+    if (SECRET_FILES.has(name))
+        return `credentials file ${name}`;
+    const dir = parts.slice(0, -1);
+    const secretDir = parts.find((p) => SECRET_DIRS.has(p));
+    if (secretDir !== undefined)
+        return `credentials directory ${secretDir}/`;
+    for (let i = 0; i < dir.length; i++) {
+        const a = dir[i];
+        const b = parts[i + 1];
+        if (a === ".kube" && b === "config")
+            return "kubeconfig";
+        if (a === ".docker" && b === "config.json")
+            return "docker credentials";
+        if (a === ".config" && b === "gcloud")
+            return "gcloud credentials";
+        if ((a === "ama" || a === ".ama") && b === "auth.json" && i + 2 === parts.length) {
+            return "ama API key file";
+        }
+    }
+    return undefined;
+}
+/** 写入受保护的原因：机密、`.git` 内部、项目 `.ama/`、项目外；可以写返回 undefined。 */
+export function writeProtectionReason(absPath, projectRoot) {
+    if (DEVICE_SINKS.has(toPosix(absPath)))
+        return undefined;
+    const secret = secretPathReason(absPath);
+    if (secret !== undefined)
+        return secret;
+    if (segments(absPath).includes(".git"))
+        return "writes inside .git";
+    if (!isWithin(projectRoot, absPath))
+        return "writes outside the project directory";
+    const rel = toPosix(relative(projectRoot, absPath));
+    if (rel === ".ama" || rel.startsWith(".ama/"))
+        return "writes to the project .ama/ config";
+    return undefined;
+}
+/** 是否在项目目录内（含项目根本身）。 */
+export function insideProject(absPath, projectRoot) {
+    return isWithin(projectRoot, absPath);
+}

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/rules.js

@@ -229,6 +229,9 @@ export function resolvePermissionLayers(layers, options = {}) {
             if (!PERMISSION_MODES_STRICT_FIRST.includes(layer.mode)) {
                 warnings.push(`${layer.source}: unknown permission mode "${String(layer.mode)}"`);
             }
+            else if (restricted && (layer.mode === "auto" || layer.mode === "full-auto")) {
+                warnings.push(`project config cannot set permission mode "${layer.mode}"; ignored`);
+            }
             else if (restricted && !isAtLeastAsStrict(layer.mode, mode)) {
                 warnings.push(`project config cannot relax permission mode from "${mode}" to "${layer.mode}"; ignored`);
             }