pi-command-guardian 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+本文档遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 格式，版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [Unreleased]
+
+## [0.2.0] - 2026-07-26
+
+### Changed
+
+- 保护范围缩减为模型发起的显式破坏性 Bash 命令。
+- 工作区和系统临时目录严格子项的文件删除自动允许。
+- 工作区根、外部目标和显式删库在执行前阻止，并要求人工审阅操作和目标后自行决定是否手动删除。
+- 动态内容、标准输入、空缺目标或命令结构无法可靠确定的删除在执行前阻止，并要求先确定所有实际目标，再简化为语法完整、直接包含静态目标的 Bash 删除命令。
+- Git 命令保持 Pi 原有行为。
+- 文件系统根、用户目录根、系统关键目录、数据库数据目录、磁盘格式化、分区擦除和原始设备写入永久阻止模型调用。
+- Shell 解析继续支持组合命令、命令替换、静态 `bash -c`、`find -delete`、`find -exec` 和写入重定向。
+- `sudo`、`env` 和执行模式的 `command` 包装后继续判断实际删除命令，`find` 删除回调使用相同规则。
+- 未引用的波浪号和花括号展开按无法静态确定的删除目标阻止，引用后的相同字符保持普通文件名语义。
+
+### Removed
+
+- 删除 `git clean` 和 `git reset --hard` 特殊阻止规则。
+- 删除当前模型 Guardian 请求和 Pi AI 依赖。
+- 删除管理、用户和项目三层配置。
+- 删除会话拒绝关联、用户授权证据和已处理状态。
+- 删除通用安全命令白名单、全部模型工具保护和敏感文件读取保护。
+- 删除本机 JSONL 审查记录、分段和容量管理。
+- 删除 `minimatch` 与 TypeBox 依赖。
+
+### Security
+
+- 受控目录根本身不属于自动允许范围，`rm -rf .` 保持阻止。
+- 组合命令采用 `forbidden > block > allow` 的最严格判断。
+- 静态 Shell 嵌套最多分析八层，超过上限时阻止并要求简化命令。
+- 普通未知命令和间接脚本副作用保持 Pi 原有行为，保护边界限定为明确可识别的破坏操作。
+
+## [0.1.0] - 2026-07-24
+
+### Added
+
+- 增加 Pi package 与 Extension 入口。
+- 增加 Tree-sitter Bash 结构解析和初始通用 Guardian 实现。
+
+[Unreleased]: https://github.com/sunnyx11/pi-command-guardian/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/sunnyx11/pi-command-guardian/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/sunnyx11/pi-command-guardian/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sunnyx11
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# Pi Command Guardian
+
+Pi Command Guardian 是一个最小 Pi Extension，用于阻止模型 Bash 中常见的显式删库、系统删除和磁盘破坏操作，同时允许清理项目构建产物和系统临时文件。
+
+## 保护范围
+
+Extension 只处理模型发起的 `bash tool_call`：
+
+- 自动允许工作区和系统临时目录严格子项的文件删除。
+- `sudo`、`env` 和执行模式的 `command` 包装后继续判断实际删除命令。
+- 阻止工作区根和工作区外目标的删除，并要求人工审阅。
+- 变量、命令替换、未引用的波浪号或花括号展开等无法静态确定的目标，要求简化为语法完整、直接包含静态目标的 Bash 删除命令。
+- 阻止显式 `DROP DATABASE`、`DROP TABLE` 和 `TRUNCATE`。
+- 永久阻止文件系统根、用户目录根、系统关键目录、数据库数据目录和磁盘设备破坏。
+
+明确外部目标等普通阻止发生后，应先审阅被阻止的操作和目标，再自行决定是否手动删除。无法静态确定目标或 Shell 嵌套超过八层时，应先确定所有实际删除目标，再将命令简化为语法完整、直接包含静态目标的 Bash 删除命令后重新提交。Extension 不推荐绕过保护的具体执行方式。永久阻止只限制模型工具调用，同样不会接管用户 Bash。
+
+## 允许示例
+
+```bash
+rm -rf build
+rm -rf ./dist/*
+find ./coverage -type f -delete
+rm -f /tmp/pi-output.log
+```
+
+所有删除目标均位于工作区或系统临时目录内部，因此保持自动执行。
+
+## 阻止示例
+
+```bash
+rm -rf .
+rm -rf ../other-project
+rm -rf "$TARGET"
+rm -rf ~/
+rm -rf {build,../shared}
+sudo rm -rf /
+psql -c 'DROP DATABASE production'
+```
+
+外部目标和工作区根会被阻止并要求人工审阅。动态内容、`xargs` 输入、空缺目标、无法可靠解析或 Shell 嵌套超过八层等不确定删除会被阻止，并要求先确定所有实际删除目标，再简化为语法完整、直接包含静态目标的 Bash 删除命令。显式删库使用人工审阅提示，Git 命令保持 Pi 原有行为。
+
+## 永久阻止示例
+
+```bash
+rm -rf /
+rm -rf "$HOME"
+rm -rf /var/lib/postgresql
+mkfs.ext4 /dev/sda1
+dd if=/dev/zero of=/dev/sda
+parted /dev/sda mklabel gpt
+```
+
+## 明确限制
+
+以下间接副作用不做分析：
+
+```bash
+python cleanup.py
+npm run migrate
+./deploy.sh
+```
+
+Extension 也不处理 `read`、`write`、`edit`、自定义工具、`!command` 或 `!!command`。备份、数据库最小权限、磁盘快照和容器隔离仍由运行环境负责。
+
+## 实现结构
+
+```text
+src/
+├── index.ts             # Pi tool_call 接入
+├── command-parser.ts    # Tree-sitter Bash 解析
+└── deletion-guard.ts    # 显式破坏操作判断
+```
+
+运行时没有模型请求、配置文件、会话授权状态或审查记录。生产依赖只有 `@vscode/tree-sitter-wasm`。
+
+## 环境要求
+
+- Node.js `>=22.19.0`
+- Pi `0.81.1` 或兼容版本
+
+## 安装
+
+仓库安装：
+
+```bash
+npm install
+npm run build
+pi install .
+```
+
+临时加载：
+
+```bash
+pi -e .
+```
+
+npm 发布后安装：
+
+```bash
+pi install npm:pi-command-guardian@0.1.0
+```
+
+## 验证
+
+```bash
+npm test
+npm run typecheck
+npm run spec:check
+npm run pack:check
+```
+
+## 卸载
+
+```bash
+pi remove npm:pi-command-guardian
+```
+
+旧版本创建的配置和审查记录不会自动删除。
+
+## 许可证
+
+当前 package 标记为 `UNLICENSED`。

package/dist/command-parser.d.ts

@@ -0,0 +1,43 @@
+import type * as TreeSitterTypes from "@vscode/tree-sitter-wasm";
+/** 与 Tree-sitter 生命周期解耦的 Bash 语法节点。 */
+export interface ShellSyntaxNode {
+    type: string;
+    named: boolean;
+    startByte: number;
+    endByte: number;
+    field?: string;
+    value?: string;
+    children: ShellSyntaxNode[];
+}
+/** Bash 语法错误或缺失节点的位置。 */
+export interface ShellSyntaxIssue {
+    type: string;
+    missing: boolean;
+    startByte: number;
+    endByte: number;
+}
+/** 成功解析的 Bash 命令。 */
+export interface ParsedShellCommand {
+    status: "parsed";
+    shell: "bash";
+    source: string;
+    root: ShellSyntaxNode;
+}
+/** 无法可靠解析的 Bash 命令。 */
+export interface UnparsedShellCommand {
+    status: "unparsed";
+    shell: "bash";
+    source: string;
+    reason: "empty_command" | "syntax_error" | "parser_unavailable" | "parse_failure";
+    issues: ShellSyntaxIssue[];
+}
+/** Bash 解析结果。 */
+export type ShellParseResult = ParsedShellCommand | UnparsedShellCommand;
+type ShellParser = Pick<TreeSitterTypes.Parser, "reset" | "parse">;
+/** Bash Parser 加载边界，只暴露当前解析流程需要的方法。 */
+export type ShellParserLoader = () => Promise<ShellParser>;
+/** 创建具有独立初始化缓存和串行队列的 Shell 命令解析函数。 */
+export declare function createShellCommandParser(loadParser: ShellParserLoader): (source: string) => Promise<ShellParseResult>;
+/** 使用进程内共享的 Tree-sitter Bash Parser 解析命令。 */
+export declare const parseShellCommand: (source: string) => Promise<ShellParseResult>;
+export {};

package/dist/command-parser.js

@@ -0,0 +1,109 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const TreeSitter = require("@vscode/tree-sitter-wasm");
+const runtimePath = require.resolve("@vscode/tree-sitter-wasm/wasm/tree-sitter.wasm");
+const bashGrammarPath = require.resolve("@vscode/tree-sitter-wasm/wasm/tree-sitter-bash.wasm");
+async function loadBashParser() {
+    await TreeSitter.Parser.init({ locateFile: () => runtimePath });
+    const language = await TreeSitter.Language.load(bashGrammarPath);
+    return new TreeSitter.Parser().setLanguage(language);
+}
+function unparsed(source, reason, issues = []) {
+    return { status: "unparsed", shell: "bash", source, reason, issues };
+}
+function copySyntaxNode(node, field) {
+    const children = [];
+    for (let index = 0; index < node.childCount; index += 1) {
+        const child = node.child(index);
+        if (child === null) {
+            continue;
+        }
+        const childField = node.fieldNameForChild(index) ?? undefined;
+        children.push(copySyntaxNode(child, childField));
+    }
+    const copied = {
+        type: node.type,
+        named: node.isNamed,
+        startByte: node.startIndex,
+        endByte: node.endIndex,
+        children,
+    };
+    if (field !== undefined) {
+        copied.field = field;
+    }
+    if (children.length === 0) {
+        copied.value = node.text;
+    }
+    return copied;
+}
+function collectSyntaxIssues(node, issues) {
+    if (node.isError || node.isMissing) {
+        issues.push({
+            type: node.isError ? "ERROR" : node.type,
+            missing: node.isMissing,
+            startByte: node.startIndex,
+            endByte: node.endIndex,
+        });
+    }
+    for (const child of node.children) {
+        if (child !== null) {
+            collectSyntaxIssues(child, issues);
+        }
+    }
+}
+async function parseWith(source, getParser) {
+    let parser;
+    try {
+        parser = await getParser();
+    }
+    catch {
+        return unparsed(source, "parser_unavailable");
+    }
+    let tree;
+    try {
+        parser.reset();
+        tree = parser.parse(source);
+    }
+    catch {
+        return unparsed(source, "parse_failure");
+    }
+    if (tree === null) {
+        return unparsed(source, "parse_failure");
+    }
+    try {
+        const root = tree.rootNode;
+        if (root.hasError) {
+            const issues = [];
+            collectSyntaxIssues(root, issues);
+            return unparsed(source, "syntax_error", issues);
+        }
+        return {
+            status: "parsed",
+            shell: "bash",
+            source,
+            root: copySyntaxNode(root),
+        };
+    }
+    finally {
+        tree.delete();
+    }
+}
+/** 创建具有独立初始化缓存和串行队列的 Shell 命令解析函数。 */
+export function createShellCommandParser(loadParser) {
+    let parserPromise;
+    let parseQueue = Promise.resolve();
+    const getParser = () => {
+        parserPromise ??= loadParser();
+        return parserPromise;
+    };
+    return (source) => {
+        if (typeof source !== "string" || source.trim().length === 0) {
+            return Promise.resolve(unparsed(source, "empty_command"));
+        }
+        const result = parseQueue.then(() => parseWith(source, getParser));
+        parseQueue = result.then(() => undefined, () => undefined);
+        return result;
+    };
+}
+/** 使用进程内共享的 Tree-sitter Bash Parser 解析命令。 */
+export const parseShellCommand = createShellCommandParser(loadBashParser);

package/dist/deletion-guard.d.ts

@@ -0,0 +1,16 @@
+import type { ShellParseResult } from "./command-parser.js";
+/** 显式删除命令的本地判断。 */
+export type DeletionDecision = {
+    decision: "allow";
+} | {
+    decision: "block";
+    reason: string;
+    guidance: "static-target" | "manual-review";
+} | {
+    decision: "forbidden";
+    reason: string;
+};
+/** 判断已解析命令中的显式文件、数据库和磁盘破坏操作。 */
+export declare function assessDeletionCommand(parsed: Extract<ShellParseResult, {
+    status: "parsed";
+}>, cwd: string, tempDirectory: string): Promise<DeletionDecision>;

package/dist/deletion-guard.js

@@ -0,0 +1,414 @@
+import { homedir } from "node:os";
+import { basename, isAbsolute, parse, relative, resolve, sep } from "node:path";
+import { parseShellCommand } from "./command-parser.js";
+const ALLOW = { decision: "allow" };
+const BLOCK_EXTERNAL = {
+    decision: "block",
+    reason: "删除目标位于工作区和系统临时目录之外或是受控目录根",
+    guidance: "manual-review",
+};
+const BLOCK_DYNAMIC = {
+    decision: "block",
+    reason: "删除目标包含动态内容，无法静态确定",
+    guidance: "static-target",
+};
+const BLOCK_INDETERMINATE = {
+    decision: "block",
+    reason: "删除目标为空、缺失或无法静态确定",
+    guidance: "static-target",
+};
+const BLOCK_NESTED_DEPTH = {
+    decision: "block",
+    reason: "嵌套 Shell 层级超过静态分析上限",
+    guidance: "static-target",
+};
+const FORBIDDEN_SYSTEM = {
+    decision: "forbidden",
+    reason: "操作会删除系统关键目录、用户目录或数据库数据目录",
+};
+const FORBIDDEN_DISK = {
+    decision: "forbidden",
+    reason: "操作会格式化、擦除或覆盖磁盘设备",
+};
+const BLOCK_DATABASE = {
+    decision: "block",
+    reason: "操作包含显式数据库删除",
+    guidance: "manual-review",
+};
+const BLOCK_XARGS = {
+    decision: "block",
+    reason: "删除目标来自 xargs 输入，无法静态确定",
+    guidance: "static-target",
+};
+const BLOCK_POWERSHELL = {
+    decision: "block",
+    reason: "PowerShell 删除目标无法由 Bash 解析器静态确定",
+    guidance: "static-target",
+};
+const ENV_OPTIONS_WITH_VALUES = new Set([
+    "-a", "--argv0", "-C", "--chdir", "-S", "--split-string", "-u", "--unset",
+]);
+const SUDO_OPTIONS_WITH_VALUES = new Set([
+    "-a", "--auth-type", "-C", "--close-from", "-D", "--chdir", "-g", "--group",
+    "-h", "--host", "-p", "--prompt", "-R", "--chroot", "-r", "--role", "-t", "--type",
+    "-T", "--command-timeout", "-u", "--user",
+]);
+function normalizeExecutable(value) {
+    return basename(value.replaceAll("\\", "/")).replace(/\.exe$/i, "").toLowerCase();
+}
+function containsBraceExpansion(value) {
+    return /\{[^{}]*(?:,|\.\.)[^{}]*\}/.test(value);
+}
+function staticText(node) {
+    if (["simple_expansion", "expansion", "command_substitution", "process_substitution"].includes(node.type)) {
+        return { value: "", dynamic: true };
+    }
+    if (node.children.length === 0) {
+        const value = node.value ?? "";
+        if (node.type === "raw_string" && value.length >= 2) {
+            return { value: value.slice(1, -1), dynamic: false };
+        }
+        if ((node.type === "\"" || node.type === "'") && (value === "\"" || value === "'")) {
+            return { value: "", dynamic: false };
+        }
+        return { value, dynamic: node.type === "word" && value.startsWith("~") };
+    }
+    let value = "";
+    let dynamic = false;
+    for (const child of node.children) {
+        const part = staticText(child);
+        value += part.value;
+        dynamic ||= part.dynamic;
+    }
+    if (node.type === "concatenation" && containsBraceExpansion(value)) {
+        dynamic = true;
+    }
+    return { value, dynamic };
+}
+function commandFromArguments(args) {
+    const [executable, ...commandArgs] = args;
+    if (executable === undefined || executable.dynamic || executable.value.length === 0) {
+        return undefined;
+    }
+    return {
+        executable: normalizeExecutable(executable.value),
+        args: commandArgs,
+    };
+}
+function unwrapCommandBuiltin(command) {
+    let index = 0;
+    while (index < command.args.length) {
+        const argument = command.args[index];
+        if (argument === undefined)
+            break;
+        if (argument.dynamic)
+            return undefined;
+        if (argument.value === "--") {
+            index += 1;
+            break;
+        }
+        if (/^-[^-]*[vV]/.test(argument.value))
+            return undefined;
+        if (argument.value === "-p") {
+            index += 1;
+            continue;
+        }
+        if (argument.value.startsWith("-"))
+            return undefined;
+        break;
+    }
+    return commandFromArguments(command.args.slice(index));
+}
+function unwrapEnv(command) {
+    let index = 0;
+    while (index < command.args.length) {
+        const argument = command.args[index];
+        if (argument === undefined)
+            break;
+        if (argument.dynamic)
+            return undefined;
+        const value = argument.value;
+        if (value === "--") {
+            index += 1;
+            break;
+        }
+        if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(value)) {
+            index += 1;
+            continue;
+        }
+        if (ENV_OPTIONS_WITH_VALUES.has(value)) {
+            index += 2;
+            continue;
+        }
+        if (/^(?:--(?:argv0|chdir|split-string|unset)=|-[aCSu].+)/.test(value) || ["-0", "--debug", "-i", "--ignore-environment", "--null"].includes(value)) {
+            index += 1;
+            continue;
+        }
+        if (value.startsWith("-"))
+            return undefined;
+        break;
+    }
+    return commandFromArguments(command.args.slice(index));
+}
+function unwrapSudo(command) {
+    let index = 0;
+    while (index < command.args.length) {
+        const argument = command.args[index];
+        if (argument === undefined)
+            break;
+        if (argument.dynamic)
+            return undefined;
+        const value = argument.value;
+        if (value === "--") {
+            index += 1;
+            break;
+        }
+        if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(value)) {
+            index += 1;
+            continue;
+        }
+        if (SUDO_OPTIONS_WITH_VALUES.has(value)) {
+            index += 2;
+            continue;
+        }
+        if (/^--[^=]+=/.test(value) || /^-[aCDghpRrtTu].+/.test(value)) {
+            index += 1;
+            continue;
+        }
+        if (value.startsWith("-")) {
+            index += 1;
+            continue;
+        }
+        break;
+    }
+    return commandFromArguments(command.args.slice(index));
+}
+function unwrapTransparentCommand(command) {
+    let current = command;
+    while (true) {
+        let unwrapped;
+        switch (current.executable) {
+            case "command":
+                unwrapped = unwrapCommandBuiltin(current);
+                break;
+            case "env":
+                unwrapped = unwrapEnv(current);
+                break;
+            case "sudo":
+                unwrapped = unwrapSudo(current);
+                break;
+            default:
+                return current;
+        }
+        if (unwrapped === undefined)
+            return current;
+        current = unwrapped;
+    }
+}
+function extractCommands(root) {
+    const commands = [];
+    const visit = (node) => {
+        if (node.type === "command") {
+            const nameNode = node.children.find((child) => child.field === "name");
+            if (nameNode !== undefined) {
+                const name = staticText(nameNode);
+                if (name.value.length > 0) {
+                    commands.push({
+                        executable: normalizeExecutable(name.value),
+                        args: node.children
+                            .filter((child) => child.field === "argument")
+                            .map(staticText),
+                    });
+                }
+            }
+        }
+        node.children.forEach(visit);
+    };
+    visit(root);
+    return commands;
+}
+function strictDescendant(root, target) {
+    const child = relative(resolve(root), resolve(target));
+    return child.length > 0 && child !== ".." && !child.startsWith(`..${sep}`) && !isAbsolute(child);
+}
+function sameOrDescendant(root, target) {
+    return resolve(root) === resolve(target) || strictDescendant(root, target);
+}
+function systemRoots() {
+    const roots = [homedir()];
+    if (process.platform === "win32") {
+        for (const value of [process.env.SystemRoot, process.env.ProgramFiles, process.env.ProgramData]) {
+            if (value !== undefined && value.length > 0)
+                roots.push(value);
+        }
+    }
+    else {
+        roots.push("/etc", "/usr", "/var", "/boot", "/bin", "/sbin", "/lib", "/lib64");
+    }
+    return roots;
+}
+function isDatabaseDataTarget(rawTarget, target) {
+    const normalized = rawTarget.replaceAll("\\", "/").toLowerCase();
+    if (/^\/(?:var\/lib\/(?:postgresql|mysql|mongodb)|var\/opt\/mssql)(?:\/|$)/.test(normalized)) {
+        return true;
+    }
+    return process.platform === "win32" && /\/(?:postgresql|mysql|mongodb|mssql)(?:\/|$)/i.test(target.replaceAll("\\", "/"));
+}
+function classifyTarget(rawTarget, cwd, tempDirectory) {
+    if (rawTarget.dynamic)
+        return BLOCK_DYNAMIC;
+    if (rawTarget.value.length === 0)
+        return BLOCK_INDETERMINATE;
+    const target = resolve(cwd, rawTarget.value);
+    if (target === parse(target).root)
+        return FORBIDDEN_SYSTEM;
+    if (isDatabaseDataTarget(rawTarget.value, target))
+        return FORBIDDEN_SYSTEM;
+    if (strictDescendant(cwd, target) || strictDescendant(tempDirectory, target))
+        return ALLOW;
+    if (systemRoots().some((root) => sameOrDescendant(root, target)))
+        return FORBIDDEN_SYSTEM;
+    return BLOCK_EXTERNAL;
+}
+function deletionOperands(args) {
+    const operands = [];
+    let optionsEnded = false;
+    for (const argument of args) {
+        if (!optionsEnded && argument.value === "--") {
+            optionsEnded = true;
+        }
+        else if (optionsEnded || !argument.value.startsWith("-")) {
+            operands.push(argument);
+        }
+    }
+    return operands;
+}
+function combine(decisions) {
+    return decisions.find((item) => item.decision === "forbidden")
+        ?? decisions.find((item) => item.decision === "block" && item.guidance === "manual-review")
+        ?? decisions.find((item) => item.decision === "block")
+        ?? ALLOW;
+}
+function assessFileDeletion(command, cwd, tempDirectory) {
+    if (!["rm", "rmdir", "unlink", "del", "erase", "rd"].includes(command.executable))
+        return undefined;
+    const targets = deletionOperands(command.args);
+    if (targets.length === 0)
+        return BLOCK_INDETERMINATE;
+    return combine(targets.map((target) => classifyTarget(target, cwd, tempDirectory)));
+}
+function findDeletionRoots(command) {
+    const deletesMatches = command.args.some((argument) => argument.value === "-delete");
+    const callbackIndex = command.args.findIndex((argument) => ["-exec", "-execdir", "-ok", "-okdir"].includes(argument.value));
+    const callback = callbackIndex < 0
+        ? undefined
+        : commandFromArguments(command.args.slice(callbackIndex + 1));
+    const callbackExecutable = callback === undefined
+        ? undefined
+        : unwrapTransparentCommand(callback).executable;
+    const deletesThroughCallback = callbackExecutable !== undefined &&
+        ["rm", "rmdir", "unlink"].includes(callbackExecutable);
+    if (!deletesMatches && !deletesThroughCallback)
+        return undefined;
+    const expressionIndex = command.args.findIndex((argument) => argument.value.startsWith("-") || ["!", "("].includes(argument.value));
+    const roots = command.args.slice(0, expressionIndex < 0 ? command.args.length : expressionIndex);
+    return roots.length === 0 ? [{ value: ".", dynamic: false }] : roots;
+}
+function assessFindDeletion(command, cwd, tempDirectory) {
+    if (command.executable !== "find")
+        return undefined;
+    const roots = findDeletionRoots(command);
+    return roots === undefined
+        ? undefined
+        : combine(roots.map((target) => classifyTarget(target, cwd, tempDirectory)));
+}
+function rawDevice(value) {
+    return /^\/dev\/(?:sd[a-z]|hd[a-z]|vd[a-z]|xvd[a-z]|nvme\d+n\d+|mmcblk\d+|disk\d+|rdisk\d+)(?:p?\d+)?$/i.test(value) ||
+        /^\\\\\.\\PhysicalDrive\d+$/i.test(value);
+}
+function assessRawDeviceRedirects(root) {
+    let destructive = false;
+    const visit = (node) => {
+        if (node.type === "file_redirect") {
+            const operator = node.children.find((child) => child.field === undefined)?.value ?? "";
+            const targets = node.children
+                .filter((child) => child.field === "destination")
+                .map(staticText);
+            if (/^(?:>|>>|>\||&>|&>>)$/.test(operator) && targets.some((target) => !target.dynamic && rawDevice(target.value))) {
+                destructive = true;
+            }
+        }
+        node.children.forEach(visit);
+    };
+    visit(root);
+    return destructive ? FORBIDDEN_DISK : undefined;
+}
+function assessFixedDestructiveCommand(command) {
+    const joined = command.args.map((argument) => argument.value).join(" ");
+    if (/^mkfs(?:\.|$)/.test(command.executable))
+        return FORBIDDEN_DISK;
+    if (command.executable === "wipefs" && /(?:^|\s)(?:-a|--all)(?:\s|$)/.test(joined))
+        return FORBIDDEN_DISK;
+    if (command.executable === "dd" && command.args.some((argument) => {
+        const output = argument.value.match(/^of=(.+)$/i)?.[1];
+        return output !== undefined && rawDevice(output);
+    })) {
+        return FORBIDDEN_DISK;
+    }
+    if (command.executable === "parted" && /(?:^|\s)(?:mklabel|mkpart|rm|resizepart)(?:\s|$)/i.test(joined))
+        return FORBIDDEN_DISK;
+    if (["fdisk", "sfdisk", "cfdisk"].includes(command.executable) && /(?:^|\s)(?:--delete|-d)(?:\s|$)/i.test(joined))
+        return FORBIDDEN_DISK;
+    if (command.executable === "diskpart" && /(?:^|\s)clean(?:\s|$)/i.test(joined))
+        return FORBIDDEN_DISK;
+    if (command.executable === "format" && command.args.some((argument) => /^[A-Za-z]:$/.test(argument.value)))
+        return FORBIDDEN_DISK;
+    if (["psql", "mysql", "mariadb", "sqlcmd"].includes(command.executable) && /\b(?:DROP\s+(?:DATABASE|TABLE)|TRUNCATE(?:\s+TABLE)?)\b/i.test(joined)) {
+        return BLOCK_DATABASE;
+    }
+    if (command.executable === "xargs" && command.args.some((argument) => ["rm", "rmdir", "unlink"].includes(normalizeExecutable(argument.value)))) {
+        return BLOCK_XARGS;
+    }
+    if (["powershell", "pwsh"].includes(command.executable) && /\bRemove-Item\b/i.test(joined))
+        return BLOCK_POWERSHELL;
+    return undefined;
+}
+async function assessNestedShell(command, cwd, tempDirectory, depth) {
+    if (!["bash", "sh", "dash", "zsh"].includes(command.executable))
+        return undefined;
+    const codeIndex = command.args.findIndex((argument) => argument.value === "-c");
+    const code = codeIndex < 0 ? undefined : command.args[codeIndex + 1];
+    if (code === undefined)
+        return undefined;
+    if (code.dynamic)
+        return BLOCK_DYNAMIC;
+    if (code.value.length === 0)
+        return BLOCK_INDETERMINATE;
+    if (depth >= 8)
+        return BLOCK_NESTED_DEPTH;
+    const nested = await parseShellCommand(code.value);
+    if (nested.status !== "parsed")
+        return BLOCK_INDETERMINATE;
+    return assessParsed(nested, cwd, tempDirectory, depth + 1);
+}
+async function assessParsed(parsed, cwd, tempDirectory, depth) {
+    const decisions = [];
+    const redirectDecision = assessRawDeviceRedirects(parsed.root);
+    if (redirectDecision !== undefined)
+        decisions.push(redirectDecision);
+    for (const extractedCommand of extractCommands(parsed.root)) {
+        const command = unwrapTransparentCommand(extractedCommand);
+        const nested = await assessNestedShell(command, cwd, tempDirectory, depth);
+        const decision = nested
+            ?? assessFileDeletion(command, cwd, tempDirectory)
+            ?? assessFindDeletion(command, cwd, tempDirectory)
+            ?? assessFixedDestructiveCommand(command);
+        if (decision !== undefined)
+            decisions.push(decision);
+    }
+    return combine(decisions);
+}
+/** 判断已解析命令中的显式文件、数据库和磁盘破坏操作。 */
+export function assessDeletionCommand(parsed, cwd, tempDirectory) {
+    return assessParsed(parsed, cwd, tempDirectory, 0);
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ShellParseResult } from "./command-parser.js";
+/** Extension 入口的可替换副作用。 */
+export interface CommandGuardianDependencies {
+    parseCommand?: (command: string) => Promise<ShellParseResult>;
+    tempDirectory?: string;
+}
+/** 创建只审查显式破坏性 Bash 命令的 Pi Extension。 */
+export declare function createCommandGuardianExtension(dependencies?: CommandGuardianDependencies): (pi: ExtensionAPI) => void;
+/** Pi package 加载入口。 */
+declare const _default: (pi: ExtensionAPI) => void;
+export default _default;

package/dist/index.js

@@ -0,0 +1,56 @@
+import { tmpdir } from "node:os";
+import { parseShellCommand } from "./command-parser.js";
+import { assessDeletionCommand } from "./deletion-guard.js";
+const EXPLICIT_DELETION_PATTERN = /\b(?:rm|rmdir|unlink|del|erase|Remove-Item|mkfs(?:\.[A-Za-z0-9_-]+)?|wipefs|diskpart|DROP\s+(?:DATABASE|TABLE)|TRUNCATE)\b|\bdd\b[^\r\n]*\bof=(?:\/dev\/|\\\\\.\\PhysicalDrive)/i;
+const MANUAL_REVIEW_GUIDANCE = "请审阅操作和目标后，自行决定是否手动删除。";
+const STATIC_TARGET_GUIDANCE = "请先确定所有实际删除目标，再将命令简化为语法完整、直接包含静态目标的 Bash 删除命令后重新提交。";
+function invalidInputReason(code) {
+    return `Command Guardian 阻止了本次操作，操作尚未执行：${code}`;
+}
+/** 创建只审查显式破坏性 Bash 命令的 Pi Extension。 */
+export function createCommandGuardianExtension(dependencies = {}) {
+    const parseCommand = dependencies.parseCommand ?? parseShellCommand;
+    const tempDirectory = dependencies.tempDirectory ?? tmpdir();
+    return (pi) => {
+        pi.on("tool_call", async (event, ctx) => {
+            if (event.toolName !== "bash")
+                return undefined;
+            const input = event.input;
+            if (typeof input.command !== "string" || input.command.trim().length === 0) {
+                return { block: true, reason: invalidInputReason("PCG_INVALID_BASH_INPUT") };
+            }
+            try {
+                const parsed = await parseCommand(input.command);
+                if (parsed.status !== "parsed") {
+                    return EXPLICIT_DELETION_PATTERN.test(input.command)
+                        ? {
+                            block: true,
+                            reason: `Command Guardian 阻止了本次删除操作，操作尚未执行：命令结构无法可靠确定。${STATIC_TARGET_GUIDANCE}`,
+                        }
+                        : undefined;
+                }
+                const result = await assessDeletionCommand(parsed, ctx.cwd, tempDirectory);
+                if (result.decision === "allow")
+                    return undefined;
+                if (result.decision === "forbidden") {
+                    return {
+                        block: true,
+                        reason: `Command Guardian 永久阻止了本次操作，操作尚未执行：${result.reason}。该判断无法由模型重试覆盖。`,
+                    };
+                }
+                const guidance = result.guidance === "static-target"
+                    ? STATIC_TARGET_GUIDANCE
+                    : MANUAL_REVIEW_GUIDANCE;
+                return {
+                    block: true,
+                    reason: `Command Guardian 阻止了本次删除操作，操作尚未执行：${result.reason}。${guidance}`,
+                };
+            }
+            catch {
+                return { block: true, reason: invalidInputReason("PCG_INTERNAL_ERROR") };
+            }
+        });
+    };
+}
+/** Pi package 加载入口。 */
+export default createCommandGuardianExtension();

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "pi-command-guardian",
+  "version": "0.2.0",
+  "description": "Deterministic explicit deletion guard for Pi",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "security",
+    "command-guardian"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sunnyx11/pi-command-guardian.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sunnyx11/pi-command-guardian/issues"
+  },
+  "homepage": "https://github.com/sunnyx11/pi-command-guardian#readme",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test",
+    "pack:check": "npm pack --dry-run",
+    "spec:check": "node .agents/skills/spec-coding/scripts/check-spec-docs.mjs --root . --specs-dir docs --domain command-guarding --all-changes && node .agents/skills/spec-coding/scripts/check-change-summary.mjs --root . --specs-dir docs && node .agents/skills/spec-coding/scripts/check-changes-index.mjs --root . --specs-dir docs && node .agents/skills/spec-coding/scripts/check-requirements-format.mjs --root . --specs-dir docs --domain command-guarding --all-changes && node .agents/skills/spec-coding/scripts/build-specs-index.mjs --root . --specs-dir docs --dry-run",
+    "prepublishOnly": "npm test && npm run typecheck && npm run spec:check && npm run pack:check"
+  },
+  "dependencies": {
+    "@vscode/tree-sitter-wasm": "0.3.1"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.81.1",
+    "@types/node": "22.19.0",
+    "typescript": "5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}