pi-safety-guards 0.1.0

package/README.md

@@ -0,0 +1,114 @@
+# pi-safety-guards
+
+Bash safety rules for Pi, with selectable presets, per-rule actions and custom matchers.
+
+[中文文档](./README.zh-CN.md)
+
+## Install
+
+```bash
+pi install npm:pi-safety-guards
+```
+
+Run `/reload` after installation or configuration changes.
+
+## Presets
+
+By default, `destructive-operations` asks for confirmation before these operations:
+
+| Preset | Rule ID | Match | Action |
+| --- | --- | --- | --- |
+| `destructive-operations` | `filesystem.delete` | Executed `rm` or `rmdir` | confirm |
+| `destructive-operations` | `filesystem.format` | Executed `mkfs` or `mkfs.*` | confirm |
+| `destructive-operations` | `filesystem.ownership` | Executed `chown` | confirm |
+| `destructive-operations` | `shell.fork-bomb` | Supported colon-function fork-bomb syntax | confirm |
+| `workspace-boundary` (opt-in) | `paths.workspace` | Explicit Bash paths outside `.` | block |
+
+Matching uses parsed commands, including supported wrappers, literal nested shells, substitutions and redirects. `echo 'rm file'` and `git rm` do not count as executing `rm`.
+
+## Configuration
+
+File: `<pi-agent-dir>/extensions/pi-safety-guards/config.json`. The agent directory respects `PI_CODING_AGENT_DIR`.
+
+```json
+{
+  "presets": ["destructive-operations"],
+  "rules": [
+    { "id": "filesystem.delete", "action": "block" },
+    { "id": "filesystem.ownership", "enabled": false },
+    { "id": "example.command", "action": "confirm", "match": { "commands": ["example-command"] } }
+  ]
+}
+```
+
+Replace `example-command` with the command to match. See also [config.example.json](./config.example.json) and [custom-rules.json](./examples/custom-rules.json).
+
+- `presets`: omitted selects the default preset; `[]` selects none.
+- `rules`: override selected preset rules by `id` or add new ones. IDs must be unique within this list.
+- Existing rules can override `action`, `match` and `message`, or use `enabled: false`.
+- New enabled rules require `id`, `action` and `match`.
+- `message`: optional non-empty text or an object containing `zh-CN` and `en-US`. If omitted, feedback shows the rule ID and action.
+- Empty presets and rules disable checking and report that no protection is active.
+
+Use `/config:safety-guards` to open the normal TUI preset menu, and use `reset` to restore the default preset. Run `/reload` after saving.
+
+### Actions
+
+| Action | Behavior |
+| --- | --- |
+| `warn` | Allow and append a warning to the corresponding tool result, including without a UI. |
+| `confirm` | Ask once for the matching rules. Block if prompting is unavailable or the user does not confirm. |
+| `block` | Reject without prompting. |
+
+When multiple rules match, priority is `block > confirm > warn`. Feedback includes all matching IDs.
+
+### Matchers
+
+Use exactly one matcher per rule:
+
+| `match` | Meaning |
+| --- | --- |
+| `{ "commands": ["example-command"] }` | Exact executed command basenames |
+| `{ "detector": "disk-format" }` | `mkfs` or `mkfs.*` |
+| `{ "detector": "fork-bomb" }` | Supported colon-function fork-bomb syntax |
+| `{ "detector": "in-place-edit" }` | `sed` in-place flags |
+| `{ "detector": "home-root" }` | An unquoted standalone `~` argument |
+| `{ "detector": "root-search" }` | A `find` argument equal to `/` |
+| `{ "outsideRoots": [".", "../shared"] }` | Explicit paths outside the configured roots |
+| `{ "module": "./rules/deploy.mjs" }` | A trusted local matcher module |
+
+### Directory rules
+
+Relative roots resolve against Pi's current working directory; absolute paths and `~/` are supported. Only listed roots are allowed. The preset uses `.` for the working directory. When `pi-add-dir` is installed, its active directory authorization is also honored; after `session_squash`, the guard restores the authorization from the squashed source branch. Add extra directories and device paths such as `/dev/null` when needed.
+
+Custom matchers can use the exported `findOutOfScopeBashPaths(command, cwd, roots)` helper to supply their own roots.
+
+### Custom modules
+
+Module paths resolve against the directory containing `config.json`. A JavaScript ES module must default-export a matcher:
+
+```js
+export default ({ commands }) => commands.some(
+  ({ name, args }) => name === "example-deploy" && args.includes("--production"),
+);
+```
+
+The matcher receives a frozen `{ command, cwd, commands: [{ name, args }] }` summary and returns a boolean or `Promise<boolean>`. `RuleContext` and `RuleMatcher` types are exported by the package.
+
+Only enabled modules are loaded. Loading failures, matcher errors, non-boolean results and asynchronous work exceeding five seconds block the operation. Use `/reload` after editing a module.
+
+Modules run with full process permissions. The timeout cannot interrupt synchronous loops or roll back side effects; load only trusted code.
+
+## Limits and errors
+
+The extension checks Pi's `bash` tool, not direct user shell commands, other tools or program-internal operations. It does not cover every dangerous command, simulate every working-directory change or resolve arbitrary variable-generated paths. Path checks handle statically identifiable references and symlinks, not OS-level access control.
+
+A missing config file uses the default preset. Invalid configuration, malformed Bash and enabled-rule failures block Bash until the relevant error is fixed. Configuration changes require `/reload`.
+
+Runtime messages are available in Chinese and English.
+
+## Development
+
+```bash
+npm run check
+```

package/README.zh-CN.md

@@ -0,0 +1,114 @@
+# pi-safety-guards
+
+Pi 的 Bash 安全规则插件，支持选择预设、设置规则动作和扩展匹配器。
+
+[English](./README.md)
+
+## 安装
+
+```bash
+pi install npm:pi-safety-guards
+```
+
+安装或修改配置后执行 `/reload`。
+
+## 预设
+
+默认启用 `destructive-operations`，执行下列操作前要求确认：
+
+| 预设 | 规则 ID | 匹配范围 | 动作 |
+| --- | --- | --- | --- |
+| `destructive-operations` | `filesystem.delete` | 实际执行的 rm/rmdir | confirm |
+| `destructive-operations` | `filesystem.format` | 实际执行的 mkfs/mkfs.* | confirm |
+| `destructive-operations` | `filesystem.ownership` | 实际执行的 chown | confirm |
+| `destructive-operations` | `shell.fork-bomb` | 支持的冒号函数 fork bomb 形式 | confirm |
+| `workspace-boundary`（可选） | `paths.workspace` | Bash 显式路径超出 `.` | block |
+
+匹配基于解析后的命令，覆盖支持的 wrapper、字面量嵌套 shell、命令替换和重定向。`echo 'rm file'` 和 `git rm` 不视为实际执行 rm。
+
+## 配置
+
+文件：`<pi-agent-dir>/extensions/pi-safety-guards/config.json`。agent 目录遵守 `PI_CODING_AGENT_DIR`。
+
+```json
+{
+  "presets": ["destructive-operations"],
+  "rules": [
+    { "id": "filesystem.delete", "action": "block" },
+    { "id": "filesystem.ownership", "enabled": false },
+    { "id": "example.command", "action": "confirm", "match": { "commands": ["example-command"] } }
+  ]
+}
+```
+
+将 `example-command` 替换为需要匹配的命令。另见 [config.example.json](./config.example.json) 和 [custom-rules.json](./examples/custom-rules.json)。
+
+- `presets`：缺省使用默认预设，`[]` 表示不选择预设。
+- `rules`：按 ID 覆盖所选预设中的规则，或添加新规则；列表内 ID 不能重复。
+- 已有规则可覆盖 `action`、`match`、`message`，或设置 `enabled: false`。
+- 新启用规则必须提供 `id`、`action` 和 `match`。
+- `message`：可选的非空文本，或包含 `zh-CN`、`en-US` 的对象。不填写时反馈规则 ID 和动作。
+- 预设和规则都为空时关闭检查，并提示当前没有启用保护。
+
+使用 `/config:safety-guards` 打开常规 TUI 预设菜单，输入 `reset` 恢复默认预设；保存后执行 `/reload`。
+
+### 动作
+
+| 动作 | 行为 |
+| --- | --- |
+| `warn` | 放行，将提醒附加到对应工具结果，无 UI 模式也可见。 |
+| `confirm` | 合并命中的规则后询问一次；无法交互或用户未确认时阻断。 |
+| `block` | 不询问，直接拒绝。 |
+
+多条规则命中时，优先级为 `block > confirm > warn`，反馈包含所有命中的规则 ID。
+
+### 匹配器
+
+每条规则选择一种匹配方式：
+
+| `match` | 含义 |
+| --- | --- |
+| `{ "commands": ["example-command"] }` | 实际执行程序的 basename 精确匹配 |
+| `{ "detector": "disk-format" }` | mkfs 或 mkfs.* |
+| `{ "detector": "fork-bomb" }` | 支持的冒号函数 fork bomb 形式 |
+| `{ "detector": "in-place-edit" }` | sed 原地编辑选项 |
+| `{ "detector": "home-root" }` | 未加引号的独立 `~` 参数 |
+| `{ "detector": "root-search" }` | find 参数为 `/` |
+| `{ "outsideRoots": [".", "../shared"] }` | 显式路径超出配置的允许根 |
+| `{ "module": "./rules/deploy.mjs" }` | 可信的本地匹配器模块 |
+
+### 目录规则
+
+相对根路径以 Pi 当前工作目录为基准，也支持绝对路径和 `~/`。只有列出的根才被允许，预设中的 `.` 表示工作目录。安装 `pi-add-dir` 时会同时尊重其当前会话目录授权；`session_squash` 后会从被压缩的源分支恢复这份授权。需要时添加额外目录或 `/dev/null` 等设备路径。
+
+自定义匹配器可使用导出的 `findOutOfScopeBashPaths(command, cwd, roots)`，提供自行计算的目录列表。
+
+### 自定义模块
+
+模块路径以配置文件所在目录为基准。JavaScript ES 模块必须默认导出匹配函数：
+
+```js
+export default ({ commands }) => commands.some(
+  ({ name, args }) => name === "example-deploy" && args.includes("--production"),
+);
+```
+
+函数接收冻结的 `{ command, cwd, commands: [{ name, args }] }` 摘要，返回布尔值或 `Promise<boolean>`。包内导出了 `RuleContext` 和 `RuleMatcher` 类型。
+
+只加载启用的模块。加载失败、匹配异常、非布尔返回或异步工作超过 5 秒，均会阻断操作。修改模块后执行 `/reload`。
+
+模块拥有进程权限，超时无法中断同步死循环或撤销副作用，因此只能加载可信代码。
+
+## 限制与错误
+
+本包检查 Pi 的 `bash` 工具，不覆盖用户直接执行的 shell、其他工具或程序内部操作。不保证检测所有危险命令，不模拟所有工作目录变化，也不解析任意变量计算的路径。目录检查处理可静态识别的引用和符号链接，不是操作系统访问控制。
+
+缺少配置文件时使用默认预设。配置损坏、Bash 解析失败或启用规则异常时阻断 Bash，修复相应错误后恢复；修改配置需要 `/reload`。
+
+运行时文案支持中英文。
+
+## 开发
+
+```bash
+npm run check
+```

package/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: configure-pi-safety-guards
+description: "配置安全预设、规则动作和自定义匹配器。Use when configuring safety presets, rule actions or custom matchers."
+---
+
+# 配置安全规则 / Configure safety rules
+
+## 配置位置 / Location
+
+`<pi-agent-dir>/extensions/pi-safety-guards/config.json`
+
+遵守 `PI_CODING_AGENT_DIR`，可以使用 `/config:safety-guards` 打开 TUI 预设菜单，输入 `reset` 恢复默认预设，保存后执行 `/reload`。
+Respect `PI_CODING_AGENT_DIR`; use `/config:safety-guards` to open the TUI preset menu, use `reset` for the default preset, and reload after saving.
+
+## 选择规则 / Select rules
+
+默认 `destructive-operations` 对支持的删除、格式化、所有权修改和 fork bomb 操作要求确认。需要限制目录时选择 `workspace-boundary`。
+
+The default `destructive-operations` preset asks for confirmation for supported deletion, formatting, ownership and fork-bomb operations. Select `workspace-boundary` for directory restrictions.
+
+- `presets`：选择预设；`[]` 不选择预设。Select presets; `[]` selects none.
+- `rules`：按 ID 覆盖或添加；`enabled: false` 禁用已有规则。Override or add by ID; use `enabled: false` to disable a rule.
+- `action`：`warn`、`confirm`、`block`，优先级递增。Actions in increasing priority.
+- `match`：`commands`、`detector`、`outsideRoots`、`module`，选择一种。Choose one matcher.
+- `message`：可选说明，支持文本或中英文对象。Optional text or bilingual message object.
+
+字段说明和示例见 [README](./README.zh-CN.md) 与 [配置示例](./config.example.json)。
+See the [English README](./README.md) and [configuration example](./config.example.json) for details.
+
+## 自定义模块 / Custom modules
+
+使用显式指定的可信本地 ES 模块，默认导出函数并返回布尔值。模块接收冻结的命令摘要；加载和异步匹配 5 秒超时。同进程代码不是沙箱，不能通过超时中止同步死循环。
+
+Use a trusted local ES module that default-exports a boolean matcher over the frozen command summary. Loading and asynchronous matching have a five-second deadline. Same-process modules are not sandboxed; the deadline cannot stop synchronous loops.
+
+## 验证与排错 / Verify and troubleshoot
+
+- 配置后检查预设和规则 ID、动作及目录根是否符合预期。Check selected presets, IDs, actions and directory roots.
+- 无 UI 时 confirm 会阻断；warn 附加到对应工具结果。Without a UI, confirm blocks; warn appears in the corresponding tool result.
+- 配置、解析或规则失败时查看错误原因，修复后重试；修改配置或模块后 reload。Inspect failures, fix the cause and retry; reload after configuration or module changes.
+- 运行 `npm run check` 验证代码；单元测试不替代真实 Pi 交互确认。Run code checks; unit tests do not replace interactive Pi verification.

package/config.example.json

@@ -0,0 +1,6 @@
+{
+  "presets": [
+    "destructive-operations"
+  ],
+  "rules": []
+}

package/examples/custom-rules.json

@@ -0,0 +1,18 @@
+{
+  "presets": ["destructive-operations"],
+  "rules": [
+    {
+      "id": "filesystem.delete",
+      "action": "warn"
+    },
+    {
+      "id": "filesystem.ownership",
+      "enabled": false
+    },
+    {
+      "id": "example.command",
+      "action": "block",
+      "match": { "commands": ["example-command"] }
+    }
+  ]
+}

package/index.ts

@@ -0,0 +1,167 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import { dirname } from "node:path";
+import { configPath, loadConfig, loadConfigDocument, saveConfigDocument } from "./src/config.ts";
+import { DEFAULT_PRESETS, PRESETS } from "./src/presets.ts";
+import { compileRules, evaluateRules, type ModuleLoader } from "./src/engine.ts";
+import { addedDirectoryPathsFromSession } from "./src/bash-directory-scope-utils.ts";
+import { i18n } from "./src/i18n.ts";
+import type { SafetyConfig, SafetyRule } from "./src/types.ts";
+
+const BASH_TOOL = "bash";
+const ERROR_LEVEL = "error";
+const INFO_LEVEL = "info";
+const WARN_LEVEL = "warning";
+const BLOCK_ACTION = "block";
+const CONFIRM_ACTION = "confirm";
+const WARN_ACTION = "warn";
+const CONFIG_COMMAND_ALIASES = ["config:safety-guards", "safety-guards-config", "pi-safety-guards-config"] as const;
+const CONFIG_RESET_COMMAND = "reset";
+const CONFIG_PRESET_NAMES = Object.keys(PRESETS);
+
+/** 注册配置命令，通过 TUI 菜单选择安全预设并保留自定义规则。 */
+function registerConfigCommand(pi: ExtensionAPI): void {
+  const command = {
+    description: i18n.t("configCommandDescription"),
+    getArgumentCompletions: () => [{ value: CONFIG_RESET_COMMAND, label: CONFIG_RESET_COMMAND }],
+    /** Handles preset selection and persists each change immediately. */
+    handler: async (args: string, ctx: ExtensionCommandContext): Promise<void> => {
+      const argument = args.trim();
+      if (argument && argument !== CONFIG_RESET_COMMAND) {
+        ctx.ui.notify(i18n.t("configCommandUsage"), WARN_LEVEL);
+        return;
+      }
+      if (argument === CONFIG_RESET_COMMAND) {
+        try {
+          const path = saveConfigDocument({ presets: [...DEFAULT_PRESETS], rules: [] });
+          ctx.ui.notify(i18n.t("configCommandSaved", { path }), INFO_LEVEL);
+        } catch (error) {
+          ctx.ui.notify(i18n.t("configCommandInvalid", {
+            error: error instanceof Error ? error.message : String(error),
+          }), ERROR_LEVEL);
+        }
+        return;
+      }
+      if (!ctx.hasUI) {
+        ctx.ui.notify(i18n.t("configCommandInteractiveOnly"), WARN_LEVEL);
+        return;
+      }
+
+      let document: { presets: string[]; rules: unknown[] };
+      try {
+        document = loadConfigDocument();
+      } catch (error) {
+        ctx.ui.notify(i18n.t("configCommandInvalid", {
+          error: error instanceof Error ? error.message : String(error),
+        }), ERROR_LEVEL);
+        return;
+      }
+      while (true) {
+        const choices = CONFIG_PRESET_NAMES.map((name) => i18n.t("configPreset", {
+          name,
+          value: document.presets.includes(name) ? i18n.t("configOn") : i18n.t("configOff"),
+        }));
+        choices.push(i18n.t("configCustomRules", { count: document.rules.length }), i18n.t("configDone"));
+        const selected = await ctx.ui.select(i18n.t("configMenuTitle"), choices);
+        if (selected === undefined || selected === choices[choices.length - 1]) return;
+        const selectedIndex = choices.indexOf(selected);
+        if (selectedIndex === CONFIG_PRESET_NAMES.length) {
+          ctx.ui.notify(i18n.t("configCustomRulesHint"), INFO_LEVEL);
+          continue;
+        }
+        const preset = CONFIG_PRESET_NAMES[selectedIndex];
+        if (!preset) continue;
+        const presets = document.presets.includes(preset)
+          ? document.presets.filter((name) => name !== preset)
+          : [...document.presets, preset];
+        try {
+          const path = saveConfigDocument({ presets, rules: document.rules });
+          document = { ...document, presets };
+          ctx.ui.notify(i18n.t("configCommandSaved", { path }), INFO_LEVEL);
+        } catch (error) {
+          ctx.ui.notify(i18n.t("configCommandInvalid", {
+            error: error instanceof Error ? error.message : String(error),
+          }), ERROR_LEVEL);
+        }
+      }
+    },
+  };
+  for (const name of CONFIG_COMMAND_ALIASES) pi.registerCommand(name, command);
+}
+
+/** 将规则 ID 和用户选择的说明一起展示，不自动执行替代命令。 */
+function describeRule(rule: SafetyRule): string {
+  const message = typeof rule.message === "string" ? rule.message : rule.message?.[i18n.locale()];
+  return message ? `[${rule.id}] ${message}` : i18n.t("ruleMatched", { id: rule.id });
+}
+
+/** 先加载规则再注册统一执行入口，禁用规则不会执行模块。 */
+export async function registerSafetyGuards(
+  pi: ExtensionAPI,
+  config: SafetyConfig,
+  options: { configDirectory?: string; loader?: ModuleLoader } = {},
+): Promise<void> {
+  const rules = await compileRules(config, options.configDirectory ?? dirname(configPath()), options.loader);
+  if (rules.length === 0) {
+    pi.on("session_start", (_event, ctx) => ctx.ui.notify(i18n.t("noRules"), INFO_LEVEL));
+    return;
+  }
+  const warnings = new Map<string, string>();
+  pi.on("session_shutdown", () => warnings.clear());
+  pi.on("turn_end", () => warnings.clear());
+  pi.on("tool_call", async (event, ctx) => {
+    if (event.toolName !== BASH_TOOL) return;
+    const command = String(event.input.command ?? "");
+    try {
+      const additionalRoots = addedDirectoryPathsFromSession(
+        ctx.sessionManager.getEntries(),
+        ctx.sessionManager.getBranch(),
+      );
+      const decision = await evaluateRules(rules, command, ctx.cwd, additionalRoots);
+      if (!decision) return;
+      const details = decision.matches.map(describeRule).join("\n");
+      if (decision.action === BLOCK_ACTION) return { block: true, reason: i18n.t("blocked", { details }) };
+      if (decision.action === CONFIRM_ACTION) {
+        if (!ctx.hasUI) return { block: true, reason: i18n.t("confirmationUnavailable", { details }) };
+        const accepted = await ctx.ui.confirm(i18n.t("confirmTitle"), i18n.t("confirmBody", { details, command }));
+        if (!accepted) return { block: true, reason: i18n.t("confirmationRejected", { details }) };
+      }
+      const warned = decision.matches.filter((rule) => rule.action === WARN_ACTION);
+      if (warned.length) {
+        warnings.set(event.toolCallId, i18n.t("warning", { details: warned.map(describeRule).join("\n") }));
+      }
+    } catch (error) {
+      return { block: true, reason: error instanceof Error ? error.message : String(error) };
+    }
+  });
+  // warn 必须对没有 UI 的调用者同样可见，且只附加到对应工具结果。
+  pi.on("tool_result", (event) => {
+    const warning = warnings.get(event.toolCallId);
+    warnings.delete(event.toolCallId);
+    if (!warning) return;
+    return { content: [...event.content, { type: "text", text: warning }] };
+  });
+}
+
+/** 配置或启用规则加载失败时阻断 Bash，避免把失败当作关闭保护。 */
+export default async function piSafetyGuards(pi: ExtensionAPI): Promise<void> {
+  registerConfigCommand(pi);
+  try {
+    await registerSafetyGuards(pi, loadConfig());
+  } catch (error) {
+    const reason = i18n.t("configLoadFailed", { error: error instanceof Error ? error.message : String(error) });
+    pi.on("session_start", (_event, ctx) => ctx.ui.notify(reason, ERROR_LEVEL));
+    pi.on("tool_call", (event) => {
+      if (event.toolName === BASH_TOOL) return { block: true, reason };
+    });
+  }
+}
+
+export { configPath, loadConfig, parseConfig, saveConfig } from "./src/config.ts";
+export type { RuleContext, RuleMatcher } from "./src/types.ts";
+export {
+  addedDirectoryPathsFromSession,
+  findOutOfScopeBashPaths,
+} from "./src/bash-directory-scope-utils.ts";

package/locales/i18n.json

@@ -0,0 +1,110 @@
+{
+  "configInvalidField": {
+    "zh-CN": "安全规则配置字段无效：{field}",
+    "en-US": "Invalid safety rule configuration field: {field}"
+  },
+  "configLoadFailed": {
+    "zh-CN": "安全规则加载失败，Bash 已阻断。请修复配置并 /reload：{error}",
+    "en-US": "Safety rules failed to load; Bash is blocked. Fix the configuration and /reload: {error}"
+  },
+  "noRules": {
+    "zh-CN": "尚未启用任何安全规则，本插件不会阻断操作。",
+    "en-US": "No safety rules are enabled; this extension will not block operations."
+  },
+  "ruleMatched": {
+    "zh-CN": "命中规则 [{id}]",
+    "en-US": "Matched rule [{id}]"
+  },
+  "blocked": {
+    "zh-CN": "安全规则已阻断操作：\n{details}",
+    "en-US": "Safety rules blocked the operation:\n{details}"
+  },
+  "confirmTitle": {
+    "zh-CN": "确认执行命中的危险操作？",
+    "en-US": "Confirm the matched dangerous operation?"
+  },
+  "confirmBody": {
+    "zh-CN": "{details}\n\n命令：\n{command}",
+    "en-US": "{details}\n\nCommand:\n{command}"
+  },
+  "confirmationUnavailable": {
+    "zh-CN": "此操作需要用户确认，但当前模式无法交互，已阻断：\n{details}",
+    "en-US": "User confirmation is required but this mode cannot prompt; operation blocked:\n{details}"
+  },
+  "confirmationRejected": {
+    "zh-CN": "用户未确认，操作已阻断：\n{details}",
+    "en-US": "The user did not confirm; operation blocked:\n{details}"
+  },
+  "warning": {
+    "zh-CN": "安全规则提醒（本规则不阻断操作）：\n{details}",
+    "en-US": "Safety rule warning (operation was not blocked by this rule):\n{details}"
+  },
+  "shellParseBlocked": {
+    "zh-CN": "无法完整解析 Bash 命令，已阻止执行。",
+    "en-US": "The Bash command could not be parsed completely and was blocked."
+  },
+  "ruleFailed": {
+    "zh-CN": "安全规则 [{id}] 执行失败，已阻止操作：{error}",
+    "en-US": "Safety rule [{id}] failed; operation blocked: {error}"
+  },
+  "moduleMustExportMatcher": {
+    "zh-CN": "规则模块必须默认导出匹配函数。",
+    "en-US": "A rule module must default-export a matcher function."
+  },
+  "matcherMustReturnBoolean": {
+    "zh-CN": "规则匹配函数必须返回布尔值。",
+    "en-US": "A rule matcher must return a boolean."
+  },
+  "moduleTimeout": {
+    "zh-CN": "规则模块加载或匹配超时。",
+    "en-US": "Rule module loading or matching timed out."
+  },
+  "configCommandDescription": {
+    "zh-CN": "配置安全规则",
+    "en-US": "Configure safety rules"
+  },
+  "configCommandUsage": {
+    "zh-CN": "用法：/config:safety-guards（打开配置菜单）或 /config:safety-guards reset（恢复默认预设）",
+    "en-US": "Usage: /config:safety-guards (open settings) or /config:safety-guards reset (restore defaults)"
+  },
+  "configMenuTitle": {
+    "zh-CN": "安全规则配置",
+    "en-US": "Safety rule settings"
+  },
+  "configPreset": {
+    "zh-CN": "预设 {name}：{value}",
+    "en-US": "Preset {name}: {value}"
+  },
+  "configCustomRules": {
+    "zh-CN": "自定义规则：{count} 条",
+    "en-US": "Custom rules: {count}"
+  },
+  "configCustomRulesHint": {
+    "zh-CN": "自定义规则仍保留在配置文件中；当前 TUI 可以切换内置预设。",
+    "en-US": "Custom rules remain in the configuration file; the TUI currently manages built-in presets."
+  },
+  "configOn": {
+    "zh-CN": "开",
+    "en-US": "on"
+  },
+  "configOff": {
+    "zh-CN": "关",
+    "en-US": "off"
+  },
+  "configDone": {
+    "zh-CN": "完成",
+    "en-US": "Done"
+  },
+  "configCommandInteractiveOnly": {
+    "zh-CN": "安全规则配置需要在 TUI 中修改；请在交互式 Pi 会话中执行命令。",
+    "en-US": "Safety configuration requires the TUI; run this command in an interactive Pi session."
+  },
+  "configCommandSaved": {
+    "zh-CN": "安全规则配置已保存：{path}。请执行 /reload 使配置生效。",
+    "en-US": "Safety configuration saved to {path}. Run /reload to apply it."
+  },
+  "configCommandInvalid": {
+    "zh-CN": "安全规则配置无效：{error}",
+    "en-US": "Invalid safety configuration: {error}"
+  }
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "pi-safety-guards",
+  "version": "0.1.0",
+  "description": "Configurable Bash safety rules with selectable presets and custom matchers for Pi",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "locales",
+    "config.example.json",
+    "README.md",
+    "README.zh-CN.md",
+    "SKILL.md",
+    "tsconfig.json",
+    "examples"
+  ],
+  "scripts": {
+    "test": "tsx --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit --pretty false",
+    "build": "npm run typecheck",
+    "check": "npm run typecheck && npm test && npm pack --dry-run --json > /dev/null"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts",
+      "../pi-extensions-i18n/index.ts"
+    ],
+    "skills": [
+      "./SKILL.md"
+    ]
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "author": "maplezzk",
+  "homepage": "https://github.com/maplezzk/pi-extensions/tree/main/packages/pi-safety-guards",
+  "bugs": "https://github.com/maplezzk/pi-extensions/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maplezzk/pi-extensions.git",
+    "directory": "packages/pi-safety-guards"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "coding-agent",
+    "safety",
+    "bash",
+    "presets",
+    "rules"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.80.0 <0.81.0"
+  },
+  "dependencies": {
+    "pi-extensions-i18n": "^0.4.0",
+    "unbash": "^4.0.10"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.80.10",
+    "@types/node": "24.12.4",
+    "tsx": "4.23.1",
+    "typescript": "5.9.3"
+  }
+}