@armadra/agent 0.0.0-stage → 0.2.1

package/dist/permissions/dangerous.js

@@ -0,0 +1,370 @@
+/**
+ * 危险命令表（设计 §7.2；v1 §7.1 的表 + `git branch -D`、`npm publish`、`docker system prune -a`、
+ * `shutdown/reboot`）。[B3]
+ *
+ * 命中 → 管线第 ② 步 ask（无人值守 deny），allow 规则不能越过。识别按段进行：命令先按
+ * `&&`、`||`、`;`、`|`、`&`、换行切段（引号内不切），每段剥掉前导的环境赋值与
+ * `sudo / command / exec / nohup / time / env` 等前缀后看命令名；`sh -c '…'`、`eval …`、`xargs …`、`find -exec … ;` 里的
+ * 命令递归识别，嵌套超过 {@link MAX_NESTING} 层按危险处理。整条命令另外做跨段检查
+ * （`curl … | sh`、fork 炸弹）。每条规则都有正例与反例测试（dangerous.test.ts）。
+ */
+import { splitShellSegments } from "./rules.js";
+const WRAPPERS = new Set(["command", "exec", "nohup", "time", "env", "builtin", "nice"]);
+/**
+ * 分词：按未加引号的空白切；单引号内原样，双引号内反斜杠只转义 `\`、`"`、`$`、反引号，引号外反斜杠转义下一个字符；
+ * 相邻的引号段与普通字符拼成一个词（`'a'"b"c` → `abc`）。不做变量与通配展开。
+ */
+export function shellWords(segment) {
+    const words = [];
+    let cur = "";
+    let inWord = false;
+    for (let i = 0; i < segment.length; i++) {
+        const ch = segment[i];
+        if (/\s/.test(ch)) {
+            if (inWord)
+                words.push(cur);
+            cur = "";
+            inWord = false;
+            continue;
+        }
+        inWord = true;
+        if (ch === "'") {
+            const end = segment.indexOf("'", i + 1);
+            const stop = end === -1 ? segment.length : end;
+            cur += segment.slice(i + 1, stop);
+            i = stop;
+        }
+        else if (ch === '"') {
+            i++;
+            while (i < segment.length && segment[i] !== '"') {
+                const c = segment[i];
+                if (c === "\\" && i + 1 < segment.length && '\\"$`'.includes(segment[i + 1])) {
+                    cur += segment[i + 1];
+                    i += 2;
+                }
+                else {
+                    cur += c;
+                    i++;
+                }
+            }
+        }
+        else if (ch === "\\" && i + 1 < segment.length) {
+            cur += segment[++i];
+        }
+        else {
+            cur += ch;
+        }
+    }
+    if (inWord)
+        words.push(cur);
+    return words;
+}
+/** 剥前缀；`keepSudo` 为假时连 sudo 一并剥掉。 */
+export function commandWords(segment, keepSudo = false) {
+    const words = shellWords(segment.replace(/^[({\s]+/, ""));
+    let i = 0;
+    while (i < words.length) {
+        const w = words[i];
+        if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(w))
+            i++;
+        else if (WRAPPERS.has(w))
+            i++;
+        else if (!keepSudo && (w === "sudo" || w === "doas")) {
+            i++;
+            while (i < words.length && words[i].startsWith("-"))
+                i++;
+        }
+        else
+            break;
+    }
+    return words.slice(i);
+}
+function base(word) {
+    return (word ?? "").split("/").pop() ?? "";
+}
+function flags(argv) {
+    return argv
+        .filter((a) => /^-[A-Za-z]/.test(a))
+        .map((a) => a.slice(1))
+        .join("");
+}
+function hasFlag(argv, short, long) {
+    return argv.some((a) => (/^-[A-Za-z]+$/.test(a) && a.includes(short)) || (long !== undefined && a === long));
+}
+const RM_DANGEROUS_TARGETS = /^(\/|\/\*|~|~\/|~\/\*|\$HOME|\$HOME\/|\$HOME\/\*|\.|\.\/|\.\/\*|\*|\.\.|\.\.\/|\/\.\*)$/;
+/** git 的全局选项（出现在子命令之前）：取值的与不取值的。 */
+const GIT_VALUE_OPTIONS = new Set([
+    "-C",
+    "-c",
+    "--git-dir",
+    "--work-tree",
+    "--namespace",
+    "--exec-path",
+    "--config-env",
+]);
+const GIT_FLAG_OPTIONS = /^(-p|-P|--paginate|--no-pager|--bare|--no-replace-objects|--literal-pathspecs|--glob-pathspecs|--noglob-pathspecs|--icase-pathspecs|--no-optional-locks|--(git-dir|work-tree|namespace|exec-path|config-env)=.*|-[cC].+)$/;
+/**
+ * 去掉 git 子命令之前的全局选项：`git -C dir -c k=v reset --hard` → `git reset --hard`。
+ * 不是 git 时返回 undefined。不去掉的话 `git -C x reset --hard` 这类写法会漏判。
+ */
+function gitArgv(argv) {
+    if (base(argv[0]) !== "git")
+        return undefined;
+    let i = 1;
+    while (i < argv.length) {
+        const a = argv[i] ?? "";
+        if (GIT_VALUE_OPTIONS.has(a))
+            i += 2;
+        else if (GIT_FLAG_OPTIONS.test(a))
+            i += 1;
+        else
+            break;
+    }
+    return [argv[0] ?? "git", ...argv.slice(i)];
+}
+export const DANGEROUS_RULES = [
+    {
+        id: "rm-rf-root",
+        description: "rm -rf on /, ~, ., .. or *",
+        segment: (argv) => {
+            if (base(argv[0]) !== "rm")
+                return false;
+            const f = flags(argv);
+            const recursive = /[rR]/.test(f) || argv.includes("--recursive");
+            const force = f.includes("f") || argv.includes("--force");
+            return recursive && force && argv.slice(1).some((a) => RM_DANGEROUS_TARGETS.test(a));
+        },
+    },
+    {
+        id: "sudo",
+        description: "privilege escalation with sudo",
+        segment: (_argv, segment) => {
+            const words = commandWords(segment, true);
+            return base(words[0]) === "sudo" || base(words[0]) === "doas";
+        },
+    },
+    { id: "su", description: "switching user with su", segment: (argv) => base(argv[0]) === "su" },
+    {
+        id: "dd",
+        description: "raw disk copy with dd",
+        segment: (argv) => base(argv[0]) === "dd",
+    },
+    {
+        id: "mkfs",
+        description: "creating a filesystem (mkfs)",
+        segment: (argv) => /^mkfs(\.[a-z0-9]+)?$/.test(base(argv[0])),
+    },
+    {
+        id: "write-block-device",
+        description: "redirecting output to a block device",
+        whole: (cmd) => />\s*\/dev\/(sd[a-z]|hd[a-z]|nvme\d|disk\d|rdisk\d|mmcblk\d|xvd[a-z]|vd[a-z])/.test(cmd),
+    },
+    {
+        id: "git-push-force",
+        description: "git push --force",
+        segment: (raw) => {
+            const argv = gitArgv(raw) ?? [];
+            return (argv[1] === "push" &&
+                argv.some((a) => a === "--force" ||
+                    a.startsWith("--force-with-lease") ||
+                    a === "--force-if-includes" ||
+                    (/^-[A-Za-z]+$/.test(a) && a.includes("f")) ||
+                    /^\+/.test(a)));
+        },
+    },
+    {
+        id: "git-reset-hard",
+        description: "git reset --hard",
+        segment: (raw) => {
+            const argv = gitArgv(raw) ?? [];
+            return argv[1] === "reset" && argv.includes("--hard");
+        },
+    },
+    {
+        id: "git-clean-force",
+        description: "git clean -f (deletes untracked files)",
+        segment: (raw) => {
+            const argv = gitArgv(raw) ?? [];
+            return argv[1] === "clean" && (hasFlag(argv, "f") || argv.includes("--force"));
+        },
+    },
+    {
+        id: "git-branch-force-delete",
+        description: "git branch -D",
+        segment: (raw) => {
+            const argv = gitArgv(raw) ?? [];
+            return (argv[1] === "branch" &&
+                (argv.some((a) => /^-[A-Za-z]*D[A-Za-z]*$/.test(a)) ||
+                    (argv.includes("--delete") && argv.includes("--force"))));
+        },
+    },
+    {
+        id: "pipe-to-shell",
+        description: "piping a download (curl / wget) into a shell",
+        whole: (cmd) => /\b(curl|wget)\b[^|;&]*\|\s*(sudo\s+)?(env\s+)?(ba|z|da|k|fi)?sh\b/.test(cmd) ||
+            /\b(ba|z)?sh\s+(-c\s+)?["']?\$\(\s*(curl|wget)\b/.test(cmd) ||
+            /\b(ba|z)?sh\s+<\(\s*(curl|wget)\b/.test(cmd),
+    },
+    {
+        id: "chmod-777-recursive",
+        description: "chmod -R 777",
+        segment: (argv) => base(argv[0]) === "chmod" &&
+            (hasFlag(argv, "R") || argv.includes("--recursive")) &&
+            argv.some((a) => /^0?777$/.test(a) || a === "a+rwx"),
+    },
+    {
+        id: "kill-all",
+        description: "kill -9 -1 (kills every process you own)",
+        segment: (argv) => base(argv[0]) === "kill" && argv.slice(1).includes("-1"),
+    },
+    {
+        id: "fork-bomb",
+        description: "fork bomb",
+        whole: (cmd) => /:\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/.test(cmd),
+    },
+    {
+        id: "package-publish",
+        description: "publishing a package (npm / pnpm / yarn publish)",
+        segment: (argv) => ["npm", "pnpm", "yarn"].includes(base(argv[0])) && argv[1] === "publish",
+    },
+    {
+        id: "docker-system-prune-all",
+        description: "docker system prune -a",
+        segment: (argv) => base(argv[0]) === "docker" &&
+            argv[1] === "system" &&
+            argv[2] === "prune" &&
+            (hasFlag(argv, "a") || argv.includes("--all")),
+    },
+    {
+        id: "shutdown-reboot",
+        description: "shutting down or rebooting the machine",
+        segment: (argv) => ["shutdown", "reboot", "halt", "poweroff"].includes(base(argv[0])) ||
+            (base(argv[0]) === "systemctl" && ["poweroff", "reboot", "halt"].includes(argv[1] ?? "")) ||
+            (base(argv[0]) === "init" && (argv[1] === "0" || argv[1] === "6")),
+    },
+];
+const SHELLS = new Set(["sh", "bash", "zsh", "dash", "ksh"]);
+/** 嵌套层数上限：`sh -c` / `eval` 等每包一层计一层，超过按危险处理。 */
+export const MAX_NESTING = 3;
+const TOO_DEEP = {
+    id: "nested-too-deep",
+    description: `shell command nested more than ${MAX_NESTING} levels deep`,
+};
+/** `sh -c 'cmd'` 的 cmd：选项簇里有 `c` 时取第一个非选项参数；`-o` / `+o` 吃掉下一个词。 */
+function shellCommandString(argv) {
+    let hasC = false;
+    for (let i = 1; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--")
+            return hasC ? argv[i + 1] : undefined;
+        if (a.startsWith("--"))
+            continue;
+        if (/^[-+][A-Za-z]+$/.test(a)) {
+            if (a[0] === "-" && a.includes("c"))
+                hasC = true;
+            if (a.endsWith("o"))
+                i++;
+            continue;
+        }
+        return hasC ? a : undefined;
+    }
+    return undefined;
+}
+/** 把词重新拼回命令文本：含特殊字符的词加单引号。 */
+function joinWords(words) {
+    return words
+        .map((w) => (/^[A-Za-z0-9_@%+=:,./{}~-]+$/.test(w) ? w : `'${w.replace(/'/g, `'\\''`)}'`))
+        .join(" ");
+}
+/** xargs 中带独立参数的短选项。 */
+const XARGS_ARG_OPTS = new Set(["-I", "-L", "-n", "-P", "-s", "-E", "-d", "-a"]);
+/** `xargs [选项] cmd …` 的 cmd 部分；没有命令（缺省 echo）返回 undefined。 */
+function xargsCommand(argv) {
+    let i = 1;
+    while (i < argv.length) {
+        const a = argv[i];
+        if (a === "--") {
+            i++;
+            break;
+        }
+        if (!a.startsWith("-") || a === "-")
+            break;
+        i += XARGS_ARG_OPTS.has(a) ? 2 : 1;
+    }
+    return i < argv.length ? joinWords(argv.slice(i)) : undefined;
+}
+/** `find … -exec / -execdir / -ok / -okdir cmd … ;|+` 里的每条 cmd。 */
+function findExecCommands(argv) {
+    const out = [];
+    for (let i = 1; i < argv.length; i++) {
+        if (!["-exec", "-execdir", "-ok", "-okdir"].includes(argv[i]))
+            continue;
+        let end = i + 1;
+        while (end < argv.length && argv[end] !== ";" && argv[end] !== "+")
+            end++;
+        if (end > i + 1)
+            out.push(joinWords(argv.slice(i + 1, end)));
+        i = end;
+    }
+    return out;
+}
+/**
+ * 段内嵌套的命令文本（剥过前缀的 argv）：`sh / bash / zsh / dash / ksh -c '…'` 的字符串参数；
+ * `eval` 其余词以空格拼接；`xargs` 要执行的命令；`find -exec … ;` 里的命令。
+ */
+export function nestedCommands(argv) {
+    const name = base(argv[0]);
+    if (SHELLS.has(name)) {
+        const inner = shellCommandString(argv);
+        return inner === undefined ? [] : [inner];
+    }
+    if (name === "eval")
+        return argv.length > 1 ? [argv.slice(1).join(" ")] : [];
+    if (name === "xargs") {
+        const inner = xargsCommand(argv);
+        return inner === undefined ? [] : [inner];
+    }
+    if (name === "find")
+        return findExecCommands(argv);
+    return [];
+}
+/** 整条命令里所有嵌套的命令文本，供 allow / deny 规则与会话记忆逐层核对。 */
+export function collectNestedCommands(command) {
+    const out = { commands: [], tooDeep: false };
+    const walk = (text, depth) => {
+        for (const segment of splitShellSegments(text)) {
+            for (const inner of nestedCommands(commandWords(segment))) {
+                if (depth >= MAX_NESTING) {
+                    out.tooDeep = true;
+                    continue;
+                }
+                out.commands.push(inner);
+                walk(inner, depth + 1);
+            }
+        }
+    };
+    walk(command, 0);
+    return out;
+}
+/** 第一条命中的危险规则；无则 undefined。嵌套命令（{@link nestedCommands}）递归识别。 */
+export function matchDangerous(command, depth = 0) {
+    for (const rule of DANGEROUS_RULES) {
+        if (rule.whole?.(command))
+            return { id: rule.id, description: rule.description };
+    }
+    for (const segment of splitShellSegments(command)) {
+        const argv = commandWords(segment);
+        for (const rule of DANGEROUS_RULES) {
+            if (rule.segment?.(argv, segment))
+                return { id: rule.id, description: rule.description };
+        }
+        for (const inner of nestedCommands(argv)) {
+            if (depth >= MAX_NESTING)
+                return TOO_DEEP;
+            const hit = matchDangerous(inner, depth + 1);
+            if (hit)
+                return hit;
+        }
+    }
+    return undefined;
+}

package/dist/permissions/pipeline.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 权限管线（设计 §6.3 第 3 步、§7.1、D11）。[B3]
+ *
+ *   ① deny 规则 ∪ Hook deny                         → deny
+ *   ② 危险命令（仅 bash）                            → ask（无人值守 deny），之后各步不能放宽
+ *   ③ 模式：plan  read 允许，write / execute deny
+ *           default  read 允许，write / execute 问
+ *           auto-edit read / write 允许，execute 问
+ *           full-auto 全部允许
+ *   ④ allow 规则 ∪ Hook allow ∪ allow_session 记忆：把 ③ 的 ask 变 allow（不越过 ①②，不改 plan 的 deny）；
+ *      Hook ask：随后把 allow 变 ask——净效果是 Hook ask 总得到 ask（reason "hook"，对话框显示 Hook 的 reason）
+ *   无人值守：最终 ask → deny。
+ *
+ * allow_session 记忆（内存，不落盘）：bash 记命令的前两个词（`npm test`），之后以它开头的命令
+ * 命中；带 path 的工具记文件所在目录，之后该目录下的路径命中；其它工具只记工具名。
+ * 记忆只作用于第 ③ 步模式产生的 ask。
+ *
+ * 包装里的命令（`sh -c '…'`、`eval`、`xargs`、`find -exec`，见 dangerous.ts）逐层核对：deny 规则命中
+ * 任一层即 deny；allow 规则与会话记忆要求外层与每一层嵌套命令都被覆盖，嵌套超深时不放行。
+ */
+import type { Decision, PermissionCheckInput, PermissionMode, PermissionPipelineApi, PermissionVerdict, Rule } from "./types.js";
+import type { ToolPermission } from "../tools/types.js";
+/** 第 ③ 步的模式真值表。 */
+export declare function modeDecision(mode: PermissionMode, permission: ToolPermission): Decision;
+export declare const UNATTENDED_MESSAGE = "This tool call requires approval, but no one is available to approve it (unattended mode).";
+interface SessionGrant {
+    toolName: string;
+    kind: "command" | "dir" | "any";
+    prefix: string;
+}
+export declare function sessionGrantFor(toolName: string, input: unknown, cwd: string): SessionGrant;
+export interface PermissionPipelineOptions {
+    mode: PermissionMode;
+    rules: readonly Rule[];
+    cwd: string;
+}
+export declare class PermissionPipeline implements PermissionPipelineApi {
+    private currentMode;
+    private readonly ruleList;
+    private readonly grants;
+    readonly cwd: string;
+    constructor(options: PermissionPipelineOptions);
+    get mode(): PermissionMode;
+    setMode(mode: PermissionMode): void;
+    get rules(): readonly Rule[];
+    rememberForSession(toolName: string, input: unknown): void;
+    clearSessionGrants(): void;
+    check(input: PermissionCheckInput): PermissionVerdict;
+    private evaluate;
+}
+export {};

package/dist/permissions/pipeline.js

@@ -0,0 +1,181 @@
+/**
+ * 权限管线（设计 §6.3 第 3 步、§7.1、D11）。[B3]
+ *
+ *   ① deny 规则 ∪ Hook deny                         → deny
+ *   ② 危险命令（仅 bash）                            → ask（无人值守 deny），之后各步不能放宽
+ *   ③ 模式：plan  read 允许，write / execute deny
+ *           default  read 允许，write / execute 问
+ *           auto-edit read / write 允许，execute 问
+ *           full-auto 全部允许
+ *   ④ allow 规则 ∪ Hook allow ∪ allow_session 记忆：把 ③ 的 ask 变 allow（不越过 ①②，不改 plan 的 deny）；
+ *      Hook ask：随后把 allow 变 ask——净效果是 Hook ask 总得到 ask（reason "hook"，对话框显示 Hook 的 reason）
+ *   无人值守：最终 ask → deny。
+ *
+ * allow_session 记忆（内存，不落盘）：bash 记命令的前两个词（`npm test`），之后以它开头的命令
+ * 命中；带 path 的工具记文件所在目录，之后该目录下的路径命中；其它工具只记工具名。
+ * 记忆只作用于第 ③ 步模式产生的 ask。
+ *
+ * 包装里的命令（`sh -c '…'`、`eval`、`xargs`、`find -exec`，见 dangerous.ts）逐层核对：deny 规则命中
+ * 任一层即 deny；allow 规则与会话记忆要求外层与每一层嵌套命令都被覆盖，嵌套超深时不放行。
+ */
+import { dirname, sep } from "node:path";
+import { findAllowRule, findDenyRule, inputCommand, inputPath, normalizeCommand, splitShellSegments, } from "./rules.js";
+import { collectNestedCommands, matchDangerous } from "./dangerous.js";
+/** bash 调用拆成「外层 + 每层嵌套命令」各自的输入；嵌套超深时 tooDeep 为真。非 bash 原样返回。 */
+function layeredInputs(toolName, input) {
+    const command = toolName === "bash" ? inputCommand(input) : undefined;
+    if (command === undefined)
+        return { inputs: [input], tooDeep: false };
+    const nested = collectNestedCommands(command);
+    return {
+        inputs: [input, ...nested.commands.map((c) => ({ ...input, command: c }))],
+        tooDeep: nested.tooDeep,
+    };
+}
+/** 第 ③ 步的模式真值表。 */
+export function modeDecision(mode, permission) {
+    if (permission === "read" || mode === "full-auto")
+        return "allow";
+    if (mode === "plan")
+        return "deny";
+    if (mode === "auto-edit")
+        return permission === "write" ? "allow" : "ask";
+    return "ask";
+}
+export const UNATTENDED_MESSAGE = "This tool call requires approval, but no one is available to approve it (unattended mode).";
+export function sessionGrantFor(toolName, input, cwd) {
+    const command = inputCommand(input);
+    if (command !== undefined) {
+        const words = normalizeCommand(command).split(" ").slice(0, 2);
+        return { toolName, kind: "command", prefix: words.join(" ") };
+    }
+    const path = inputPath(toolName, input, cwd);
+    if (path !== undefined)
+        return { toolName, kind: "dir", prefix: dirname(path) };
+    return { toolName, kind: "any", prefix: "" };
+}
+function grantCovers(grant, toolName, input, cwd) {
+    if (grant.toolName !== toolName)
+        return false;
+    if (grant.kind === "any")
+        return true;
+    if (grant.kind === "command") {
+        const command = inputCommand(input);
+        if (command === undefined || /\$\(|`/.test(command))
+            return false;
+        const segments = splitShellSegments(command);
+        return (segments.length > 0 &&
+            segments.every((s) => s === grant.prefix || s.startsWith(`${grant.prefix} `)));
+    }
+    const path = inputPath(toolName, input, cwd);
+    return path !== undefined && (path === grant.prefix || path.startsWith(grant.prefix + sep));
+}
+export class PermissionPipeline {
+    currentMode;
+    ruleList;
+    grants = [];
+    cwd;
+    constructor(options) {
+        this.currentMode = options.mode;
+        this.ruleList = [...options.rules];
+        this.cwd = options.cwd;
+    }
+    get mode() {
+        return this.currentMode;
+    }
+    setMode(mode) {
+        this.currentMode = mode;
+    }
+    get rules() {
+        return this.ruleList;
+    }
+    rememberForSession(toolName, input) {
+        this.grants.push(sessionGrantFor(toolName, input, this.cwd));
+    }
+    clearSessionGrants() {
+        this.grants.length = 0;
+    }
+    check(input) {
+        const verdict = this.evaluate(input);
+        if (verdict.decision === "ask" && input.unattended) {
+            return { ...verdict, decision: "deny", message: UNATTENDED_MESSAGE };
+        }
+        return verdict;
+    }
+    evaluate(input) {
+        const { toolName, permission } = input;
+        // ① deny
+        const layers = layeredInputs(toolName, input.input);
+        let deny;
+        for (const layer of layers.inputs) {
+            deny = findDenyRule(this.ruleList, toolName, layer, this.cwd);
+            if (deny)
+                break;
+        }
+        if (deny) {
+            return {
+                decision: "deny",
+                step: "deny-rule",
+                rule: deny,
+                message: `Denied by permission rule ${deny.raw} (${deny.source})`,
+            };
+        }
+        if (input.hookDecision === "deny") {
+            return {
+                decision: "deny",
+                step: "hook-deny",
+                message: input.hookReason ?? "Denied by a PreToolUse hook",
+            };
+        }
+        // ② 危险命令
+        const command = toolName === "bash" ? inputCommand(input.input) : undefined;
+        const danger = command !== undefined ? matchDangerous(command) : undefined;
+        if (danger) {
+            return {
+                decision: "ask",
+                step: "dangerous",
+                approvalReason: "dangerous",
+                message: `Potentially dangerous command: ${danger.description}`,
+            };
+        }
+        // ③ 模式
+        const byMode = modeDecision(this.currentMode, permission);
+        if (byMode === "deny") {
+            return {
+                decision: "deny",
+                step: "mode",
+                message: `Permission mode "${this.currentMode}" allows only read-only tools`,
+            };
+        }
+        let verdict = byMode === "allow"
+            ? { decision: "allow", step: "mode" }
+            : { decision: "ask", step: "mode", approvalReason: "mode" };
+        // ④ allow 规则 / Hook allow / 会话记忆
+        if (verdict.decision === "ask") {
+            const allow = layers.tooDeep
+                ? undefined
+                : findAllowRule(this.ruleList, toolName, input.input, this.cwd);
+            const allowAll = allow !== undefined &&
+                layers.inputs.every((l) => findAllowRule(this.ruleList, toolName, l, this.cwd));
+            const granted = !layers.tooDeep &&
+                layers.inputs.every((l) => this.grants.some((g) => grantCovers(g, toolName, l, this.cwd)));
+            if (allowAll)
+                verdict = { decision: "allow", step: "allow-rule", rule: allow };
+            else if (input.hookDecision === "allow")
+                verdict = { decision: "allow", step: "hook" };
+            else if (granted) {
+                verdict = { decision: "allow", step: "session" };
+            }
+        }
+        if (input.hookDecision === "ask") {
+            const reason = "hook";
+            verdict = {
+                decision: "ask",
+                step: "hook",
+                approvalReason: reason,
+                ...(input.hookReason !== undefined ? { message: input.hookReason } : {}),
+            };
+        }
+        return verdict;
+    }
+}

package/dist/permissions/preview.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 执行前预览（第三波 §2.2）：审批时列出「这一步会碰到什么」。[W3-B9a-2]
+ *
+ * - 只读：只用 `statSync / lstatSync / readdirSync / readFileSync`，不起子进程、不写盘；
+ * - 有上限：目录递归计数每个目标最多 `maxEntries`（缺省 2000）项，整次预览共用一个时间预算
+ *   （缺省 200 ms，预算循环里逐项检查），超出只给提示；超时 / 超限不降低严重度；
+ * - bash：按段（含 `sh -c` / `eval` / `xargs` / `find -exec` 的嵌套命令）识别 `rm / rmdir / unlink`、
+ *   `mv`、`git clean`、`git checkout -- <路径>`、`git reset --hard` 与 `>` / `>>` 重定向目标；
+ *   通配符、变量与 `{}` 不展开，原样显示并提示范围可能更大；段首的 `cd <路径>` 改变后续段的基准；
+ * - write：目标是否存在、现有行数 / 大小 → 新内容；覆盖本会话未 read 过的文件标 warn；
+ * - edit：读原文用 `planEdits` 干跑，成功给每处 −n/+m 行与总变化，失败提前说明原因；
+ *   超过 2 MiB 的文件只报大小，不读内容；
+ * - 其它工具：一行参数摘要。
+ *
+ * `lines` 不含颜色；`affected[].path` 与行里的路径一样是显示路径（cwd 内相对、`/` 分隔）。
+ */
+import type { ActionPreview, ApprovalRequest } from "./types.js";
+export declare const PREVIEW_MAX_ENTRIES = 2000;
+export declare const PREVIEW_BUDGET_MS = 200;
+/** 超过它的文件不读内容，只报大小。 */
+export declare const PREVIEW_MAX_READ_BYTES: number;
+/** 一次预览最多列出的目标数。 */
+export declare const PREVIEW_MAX_TARGETS = 20;
+export interface PreviewOptions {
+    /** 相对路径的基准（会话 cwd）。 */
+    cwd: string;
+    maxEntries?: number;
+    budgetMs?: number;
+    now?: () => number;
+}
+export declare function formatBytes(bytes: number): string;
+/** 段里的 `>` / `>>` 重定向：返回目标与去掉重定向后的文本。 */
+export declare function splitRedirects(segment: string): {
+    rest: string;
+    targets: {
+        word: string;
+        append: boolean;
+    }[];
+};
+/** 审批请求的执行前预览；纯读，不抛错（内部错误返回空预览）。 */
+export declare function previewAction(request: ApprovalRequest, options: PreviewOptions): ActionPreview;
+/** 对话框 / 行式界面里显示的预览行（`other` 已由输入摘要覆盖，不重复显示）。 */
+export declare function previewDisplayLines(preview: ActionPreview | undefined, max?: number): string[];