@andares/pi-toolkits 0.8.0 → 0.9.0

package/README.md

@@ -12,9 +12,9 @@
 [![pi >= 1.0](https://img.shields.io/badge/pi-%3E%3D1.0.0%20%3C1.12.0-blueviolet)](https://github.com/earendil-works/pi)
 [![GitHub](https://img.shields.io/badge/github-andares%2Fpi--toolkits-181717?logo=github)](https://github.com/andares/pi-toolkits)
 
-In a nutshell: six ready-to-use capabilities — **read-only consult mode** `ask`, **model favorites** `favorites`, **prompt stash** `stash`, **third-party code review** `third-review`, **dedicated compaction model** `compact-model` and **session startup automation** `autostart` — with more to come.
+In a nutshell: seven ready-to-use capabilities — **read-only consult mode** `ask`, **session-scoped boundary permission** `ask-perm`, **model favorites** `favorites`, **prompt stash** `stash`, **third-party code review** `third-review`, **dedicated compaction model** `compact-model` and **session startup automation** `autostart` — with more to come.
 
-**Requirements**: pi `>=1.0.0 <1.12.0` — the four most recently released minor lines (1.0.x / 1.1.x / 1.2.x / 1.3.x) are supported best-effort, and the upper bound encodes the forward probe: on every host release we check up to **8 minor lines** beyond the newest one (now 1.4 … 1.11) and never claim past that cap. **Measured natural compatibility: 1.3.0** (the newest release at the time of writing — nothing newer exists to probe yet). A single command, `pnpm check:compat`, derives that version set from the registry and runs, per version, in a sandbox under the system temp dir with the whole `@earendil-works/*` family pinned to the version under test: install → `tsc --noEmit` → full test suite → keybinding audit → hash-compare of the host `dist` files this package patches or mirrors. Results over 1.0.0 → 1.3.0 (all 8 published versions): typecheck, 289 tests and the keybinding audit pass on every one; the tracked host files drift only in `core/agent-session.js` (1.3.0 changed the tool-restore path; `cycleModel` untouched), `core/keybindings.js` and `core/compaction/utils.js` (both changed in 1.2.0, table semantics for our keys unchanged), and `extensions/types.d.ts` (additive) — `ModelSelectorComponent`, `core/compaction/compaction.js` and `core/usage-totals.js` are byte-identical across the whole window. Smoke-loading on real pi 1.3.0 produces no warnings. Note: pi ≥ 0.99 hosts require `@earendil-works/pi-tui` to be declared in `peerDependencies` as `"*"` (provided by the host); this package declares it as required.
+**Requirements**: pi `>=1.0.0 <1.12.0` — the four most recently released minor lines (1.0.x / 1.1.x / 1.2.x / 1.3.x) are supported best-effort, and the upper bound encodes the forward probe: on every host release we check up to **8 minor lines** beyond the newest one (now 1.4 … 1.11) and never claim past that cap. **Measured natural compatibility: 1.3.0** (the newest release at the time of writing — nothing newer exists to probe yet). A single command, `pnpm check:compat`, derives that version set from the registry and runs, per version, in a sandbox under the system temp dir with the whole `@earendil-works/*` family pinned to the version under test: install → `tsc --noEmit` → full test suite → keybinding audit → hash-compare of the host `dist` files this package patches or mirrors. Results over 1.0.0 → 1.3.0 (all 8 published versions): typecheck, 397 tests and the keybinding audit pass on every one; the tracked host files drift only in `core/agent-session.js` (1.3.0 changed the tool-restore path; `cycleModel` untouched), `core/keybindings.js` and `core/compaction/utils.js` (both changed in 1.2.0, table semantics for our keys unchanged), and `extensions/types.d.ts` (additive) — `ModelSelectorComponent`, `core/compaction/compaction.js` and `core/usage-totals.js` are byte-identical across the whole window. Smoke-loading on real pi 1.3.0 produces no warnings. Note: pi ≥ 0.99 hosts require `@earendil-works/pi-tui` to be declared in `peerDependencies` as `"*"` (provided by the host); this package declares it as required.
 
 ---
 
@@ -48,6 +48,7 @@ After installing, verify in any pi session:
 - [Installation](#install)
 - [Features at a glance](#features)
   - [🛡️ ask — read-only consult mode](#ask)
+  - [🔐 permission — session-scoped boundary checks](#permission)
   - [⭐ favorites — model favorites](#favorites)
   - [📥 stash — prompt stash](#stash)
   - [🔎 review — third-party code review](#review)
@@ -66,6 +67,7 @@ After installing, verify in any pi session:
 | Feature | Entry point | One-line description |
 | --- | --- | --- |
 | 🛡️ **ask** read-only consult mode | `/ask` | enter read-only Q&A mode: `write`/`edit`/`powershell` hard-disabled, `bash` runs in a read-only sandbox, `grep`/`find`/`ls` activated |
+| 🔐 **permission** session-scoped boundary checks | `/ask-perm` | four in/out × read/write modes, off by default and never persisted; outside writes ask, credentials are denied, destructive commands always ask; composes with `/ask` |
 | ⭐ **favorites** model favorites | `ctrl+A` / `ctrl+J` inside `/model` | favorite the models you use most (marked in bold bright yellow), `ctrl+p` cycles only among favorites |
 | 📥 **stash** prompt stash | `ctrl+alt+y` | a stash slot for one prompt: press to swap, press twice to stash and clear the input box |
 | 🔎 **review** third-party code review | `/third-review` | summon the configured review model to check + fix the task just finished, focusing on "is this round's requirement implemented / is anything missing / is anything wrong" |
@@ -92,6 +94,55 @@ Enter with `/ask` (press it again to exit). Meant for the case where you only wa
 
 ---
 
+## 🔐 permission — session-scoped boundary checks
+
+<a name="permission"></a>
+
+`/ask-perm` turns on boundary checks for the **current session only**. Every piece of state — the on/off flag, the four modes, the session grants — lives in the extension's memory. Nothing is written to disk, the feature is off by default, and it leaves no status behind when disabled. Toggling it on can never silently follow you into the next session.
+
+**Enable**
+
+- `/ask-perm` — opens the mode panel. The first row applies on Enter; the four rows cycle with space. Cursor starts at the top, so `/ask-perm` + Enter enables the defaults.
+- `/ask-perm allow allow allow ask` — positional form (`in-read in-write out-read out-write`), enables immediately without a dialog. Missing arguments fall back to the defaults. This is the form autostart uses.
+- `/ask-perm` again — turns it off.
+
+**Defaults**: in-project read/write allowed, outside read allowed, outside write asks.
+
+| Scope | reads | writes / exec |
+| --- | --- | --- |
+| inside the project (working directory + `/add-dir` directories) | `in read` | `in write` |
+| outside the project | `out read` | `out write` |
+
+`exec` is folded into `write`: any command that changes state counts as a write.
+
+**What is inspected**
+
+- **bash** is decomposed into simple commands — `&&`, `||`, `;`, pipes, `$(…)`, backticks, `bash -c`, `eval`, the common indirection wrappers (`sudo`, `env`, `xargs`, `find -exec`, …), heredocs — and judged per command. `cd` folds into the commands after it; the strictest result wins, so `cd /tmp && rm x` cannot ride on the first segment.
+- **path-bearing tools** (`read` / `write` / `edit` / `grep` / `find` / `ls`) are judged by their own path; every other tool is judged by the working directory.
+- **unresolvable input** — a non-literal `cd` or `git -C`, an unknown shell variable in a path, an unterminated heredoc or substitution — is asked about regardless of mode (fail closed), never guessed.
+- **`git -C <dir>`** is resolved like a local `cd`: relative path arguments (and the repository) are judged against `<dir>`, not the working directory.
+
+**Answers**: `a` allow once · `s` allow this directory for the session · `d` deny · `f` deny this directory for the session. Session grants are kept in memory as `(read|write, directory)`, matched by containment, and cleared when the mode is turned off or the session ends. A session grant outranks the destructive table — once you have allowed an operation for the session, repeating it does not ask again. A command the parser cannot resolve is granted by its exact text instead, so repeating the same opaque command does not ask again.
+
+**Fixed safety tables** (independent of the four modes):
+
+- **credentials are denied in every mode** — `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.pi/agent/auth*.json`, `.env` files (templates excepted). Without this, `out read = allow` would hand out `~/.ssh/id_rsa`.
+- **destructive commands always ask** — `rm` of `/`, the home directory, or the working directory; `git reset --hard`; `git clean -f`; `git push --force`; package `publish`; `dd` to a raw device; `mkfs*`; shutdown/reboot; `chmod -R 777`; anything through `sudo`. Scope alone cannot express "destructive".
+
+**Composition with `/ask`**: the two features are independent gates on one bus. Each answers only its own question — ask: "does this mutate?", permission: "does this cross the boundary?" — and either can block. Ask mode still denies credential reads, and permission still applies while the read-only sandbox is active. Neither feature needs to know the other exists.
+
+**Enable it for every session** (the state itself is never persisted — this is the opt-in):
+
+```toml
+# <project>/.pi/autostart.toml, or <agent-dir>/autostart.toml for all projects
+[command]
+run = ["/ask-perm allow allow allow ask"]
+```
+
+> **Implementation notes**: state is reset on `session_start` and cleared on `session_shutdown`; the footer shows `perm i:A/A o:A/ask` while on (`A` allow, `a` ask, `D` deny). Subagent sessions start with their own state and do not inherit the parent's mode — when child sessions must be gated too, enable it through the project's autostart file. POSIX hosts (Linux / macOS / WSL) are the tested target; native Windows Git-Bash path spellings are approximated, not verified. bash decomposition uses `shell-quote`; unknown variables expand to a sentinel that makes the unit ask instead of silently becoming an empty path. Added directories are read from pi-add-dir's session entry (`add-dir:state`). Heuristic, not a sandbox: project-internal destructive commands are covered by the fixed table, not by a sandbox. One known blind spot: a *read* command's bare filename operand (`cat notes.txt`) is not collected as a target, so with `out read = ask` only absolute-path-shaped read operands are questioned — reads never write, so the four modes' write side is unaffected.
+
+---
+
 ## ⭐ favorites — model favorites
 
 <a name="favorites"></a>
@@ -247,6 +298,15 @@ run = [
 
 No file = feature disabled, zero overhead, silently skipped.
 
+**Two sources, executed in order, never merged**:
+
+| Source | Path | Trust gate |
+| --- | --- | --- |
+| global (operator defaults) | `<agent-dir>/autostart.toml` (default `~/.pi/agent/autostart.toml`) | none — the file belongs to the operator |
+| project | `<project root>/.pi/autostart.toml` | requires project trust |
+
+The global list runs first, so a project can override an earlier setting (for example a later `/ask-perm` with different arguments). Use the global file only when you want the same commands in every project; per-project files remain the recommended default.
+
 **When it runs**:
 
 | session_start reason | Replayed | Why |
@@ -288,6 +348,7 @@ pnpm check:compat        # verify the declared pi range: last 4 minor lines + 8-
 src/
 ├── index.ts              # entry point: aggregates feature modules
 ├── lib/                  # shared infrastructure (tool-set snapshot/restore,
+│                         # gate bus composing tool_call policies,
 │                         # model-key resolution shared by review & compact)
 └── features/             # feature modules — one directory per feature
     ├── ask/              # ask mode: command + state machine, bash sandbox,
@@ -299,6 +360,9 @@ src/
     │                     #           tests
     ├── favorites/        # model favorites: selector + cycle patches,
     │                     #           persisted store, tests
+    ├── permission/       # session-scoped boundary permission: modes, panel,
+    │                     #           bash units, policy, session grants, prompt,
+    │                     #           tests
     ├── review/           # third-party review: input/command triggers,
     │                     #           review-model config store, prompt, tests
     └── stash/            # prompt stash: hotkey state machine + tests

package/README.zh-CN.md

@@ -12,9 +12,9 @@
 [![pi >= 1.0](https://img.shields.io/badge/pi-%3E%3D1.0.0%20%3C1.12.0-blueviolet)](https://github.com/earendil-works/pi)
 [![GitHub](https://img.shields.io/badge/github-andares%2Fpi--toolkits-181717?logo=github)](https://github.com/andares/pi-toolkits)
 
-一句话介绍:目前包含六个开箱即用的功能——**只读咨询模式** `ask`、**模型收藏** `favorites`、**提示词暂存** `stash`、**第三方代码评审** `third-review`、**独立压缩模型** `compact-model`、**会话启动自动化** `autostart`,后续持续追加。
+一句话介绍:目前包含七个开箱即用的功能——**只读咨询模式** `ask`、**会话级边界权限** `ask-perm`、**模型收藏** `favorites`、**提示词暂存** `stash`、**第三方代码评审** `third-review`、**独立压缩模型** `compact-model`、**会话启动自动化** `autostart`,后续持续追加。
 
-**版本要求**:pi `>=1.0.0 <1.12.0` —— 最近 4 个中版本线(1.0.x / 1.1.x / 1.2.x / 1.3.x)尽力支持,上界编码「向后探针」的硬上限:宿主每发一版,我们最多向后查 **8 条中版本线**(当前 1.4 … 1.11),再晚不宣称。**实测自然兼容最高 1.3.0**(写此文时的最新版本,更新的还没发布、无物可探)。一条命令 `pnpm check:compat` 从 registry 推导目标集合,逐版本在系统临时目录沙箱中(把整个 `@earendil-works/*` 家族钉在待测版本)跑:安装 → `tsc --noEmit` → 全量测试 → 键位审计 → 对 patch/mirror 的宿主 `dist` 文件做哈希比对。1.0.0 → 1.3.0 全部 8 个已发布版本:typecheck、289 个测试、键位审计全绿;被跟踪的宿主文件仅在 `core/agent-session.js`(1.3.0 改了 tool-restore 路径,`cycleModel` 未动)、`core/keybindings.js` 与 `core/compaction/utils.js`(二者都是 1.2.0 变的,我们按键的解析结果不变)、`extensions/types.d.ts`(纯增量)上有差异 —— `ModelSelectorComponent`、`core/compaction/compaction.js` 与 `core/usage-totals.js` 在窗口内字节级不变。真实 pi 1.3.0 冒烟加载无警告。注:pi ≥ 0.99 的宿主要求 `@earendil-works/pi-tui` 声明为 peerDependencies `"*"`(由宿主提供),本包已按要求声明。
+**版本要求**:pi `>=1.0.0 <1.12.0` —— 最近 4 个中版本线(1.0.x / 1.1.x / 1.2.x / 1.3.x)尽力支持,上界编码「向后探针」的硬上限:宿主每发一版,我们最多向后查 **8 条中版本线**(当前 1.4 … 1.11),再晚不宣称。**实测自然兼容最高 1.3.0**(写此文时的最新版本,更新的还没发布、无物可探)。一条命令 `pnpm check:compat` 从 registry 推导目标集合,逐版本在系统临时目录沙箱中(把整个 `@earendil-works/*` 家族钉在待测版本)跑:安装 → `tsc --noEmit` → 全量测试 → 键位审计 → 对 patch/mirror 的宿主 `dist` 文件做哈希比对。1.0.0 → 1.3.0 全部 8 个已发布版本:typecheck、397 个测试、键位审计全绿;被跟踪的宿主文件仅在 `core/agent-session.js`(1.3.0 改了 tool-restore 路径,`cycleModel` 未动)、`core/keybindings.js` 与 `core/compaction/utils.js`(二者都是 1.2.0 变的,我们按键的解析结果不变)、`extensions/types.d.ts`(纯增量)上有差异 —— `ModelSelectorComponent`、`core/compaction/compaction.js` 与 `core/usage-totals.js` 在窗口内字节级不变。真实 pi 1.3.0 冒烟加载无警告。注:pi ≥ 0.99 的宿主要求 `@earendil-works/pi-tui` 声明为 peerDependencies `"*"`(由宿主提供),本包已按要求声明。
 
 ---
 
@@ -48,6 +48,7 @@ pi -e ./src/index.ts
 - [安装](#install)
 - [功能总览](#features)
   - [🛡️ ask — 只读咨询模式](#ask)
+  - [🔐 permission — 会话级边界权限](#permission)
   - [⭐ favorites — 模型收藏](#favorites)
   - [📥 stash — 提示词暂存](#stash)
   - [🔎 review — 第三方代码评审](#review)
@@ -66,6 +67,7 @@ pi -e ./src/index.ts
 | 功能 | 入口 | 一句话说明 |
 | --- | --- | --- |
 | 🛡️ **ask** 只读咨询模式 | `/ask` | 进入只读问答模式,`write`/`edit`/`powershell` 硬禁用,`bash` 只读沙箱,临时启用 `grep`/`find`/`ls` |
+| 🔐 **permission** 会话级边界权限 | `/ask-perm` | 项目内/外 × 读/写四格模式,默认关闭且从不落盘;项目外写询问、凭据路径硬拒、破坏性命令必问;与 `/ask` 并行组合 |
 | ⭐ **favorites** 模型收藏 | `/model` 内 `ctrl+A` / `ctrl+J` | 收藏常用模型(加粗亮黄标记),`ctrl+p` 仅在收藏间循环 |
 | 📥 **stash** 提示词暂存 | `ctrl+alt+y` | 一段提示词的暂存槽,按键交换 / 连按两次暂存并清空输入框 |
 | 🔎 **review** 第三方代码评审 | `/third-review` | 召唤配置的评审模型,对刚完成的任务做查+修,重点检查「本轮需求实现 / 是否有遗漏 / 是否有错误」 |
@@ -92,6 +94,55 @@ pi -e ./src/index.ts
 
 ---
 
+## 🔐 permission — 会话级边界权限
+
+<a name="permission"></a>
+
+`/ask-perm` 只在**当前会话**开启边界检查。开关状态、四项模式、会话授权全部只存在扩展内存里:不落盘、默认关闭、关闭后不留任何状态。开启一次不会悄悄跟到下一个会话。
+
+**开启**
+
+- `/ask-perm` —— 打开模式面板。顶行按回车即应用,四行用空格循环、↑↓ 移动;光标默认在最上面,所以「输入指令 + 回车」就是按默认值开启
+- `/ask-perm allow allow allow ask` —— 位置参数形式(`in-read in-write out-read out-write`),不弹窗直接开启;没给全的参数回落到默认值。这也是 autostart 使用的形式
+- 再输入一次 `/ask-perm` —— 关闭
+
+**默认值**:项目内读/写全放行,项目外读放行,项目外写询问。
+
+| 作用域 | 读 | 写 / 执行 |
+| --- | --- | --- |
+| 项目内(工作目录 + `/add-dir` 加入的目录) | `in read` | `in write` |
+| 项目外 | `out read` | `out write` |
+
+`exec` 折进 `write`:任何产生变更的执行都算写。
+
+**检查方式**
+
+- **bash** 先拆成简单命令 —— `&&`、`||`、`;`、管道、`$(…)`、反引号、`bash -c`、`eval`、常见间接包装(`sudo`、`env`、`xargs`、`find -exec`…)、heredoc —— 再逐条判定;`cd` 向前折叠,取最严格的结果,所以 `cd /tmp && rm x` 不会靠第一段蒙混过关
+- **带路径的工具**(`read` / `write` / `edit` / `grep` / `find` / `ls`)按自己的路径判定;其它工具按工作目录判定
+- **无法解析的输入** —— 非字面量 `cd` 或 `git -C`、路径里的未知 shell 变量、未闭合的 heredoc/命令替换 —— 一律询问,不看模式(fail closed),绝不猜测
+- **`git -C <dir>`** 按局部 `cd` 处理:相对路径参数(和仓库本身)按 `<dir>` 判定,而不是工作目录
+
+**回答**:`a` 本次允许 · `s` 本会话允许该目录 · `d` 拒绝 · `f` 本会话拒绝该目录。会话授权在内存中按 `(读|写, 目录)` 保存、按包含关系匹配,关闭模式或会话结束时清空;**会话授权优先于破坏性表**——你按了 `s` 之后,重复同一操作不会再弹;解析不了完整路径的命令则按**完整命令文本**授权,重复同一条命令不会再问。
+
+**固定安全表**(与四格模式无关):
+
+- **凭据路径任何模式都拒绝** —— `~/.ssh`、`~/.gnupg`、`~/.aws`、`~/.pi/agent/auth*.json`、`.env` 文件(模板除外)。没有这一条,默认的「项目外读放行」就等于把 `~/.ssh/id_rsa` 交出去
+- **破坏性命令永远询问** —— 对 `/`、家目录或工作目录的 `rm`;`git reset --hard`;`git clean -f`;`git push --force`;包 `publish`;`dd` 写裸设备;`mkfs*`;关机/重启;`chmod -R 777`;任何经 `sudo` 的命令。作用域本身表达不了「破坏性」
+
+**与 `/ask` 的组合**:两者是同一总线上的独立闸门,各自只回答自己的问题 —— ask 回答「会不会产生变更」,permission 回答「有没有越过边界」,任一拦截都生效。所以 ask 模式下凭据仍然读不到,permission 在只读沙箱下也照常工作;两个功能互不需要知道对方存在。
+
+**每个会话自动开启**(状态本身不落盘,这就是持久化的替身):
+
+```toml
+# <项目>/.pi/autostart.toml;想对所有项目生效则用 <agent-dir>/autostart.toml
+[command]
+run = ["/ask-perm allow allow allow ask"]
+```
+
+> **实现说明**:状态在 `session_start` 重置、`session_shutdown` 清空;开启时 footer 显示 `perm i:A/A o:A/ask`(`A` allow、`a` ask、`D` deny)。子代理会话有自己的状态、不继承父会话的模式;需要子会话也受控时,通过项目 autostart 再开启一次。实测目标是 POSIX 宿主(Linux/macOS/WSL);原生 Windows Git-Bash 的路径拼写只做了近似,未验证。bash 拆解使用 `shell-quote`;未知变量会展开成哨兵而不是空字符串,使该命令转为询问而不是被悄悄当成空路径。add-dir 目录从 pi-add-dir 的会话条目 `add-dir:state` 读取。启发式,不是沙箱:项目内的破坏性操作由固定表兜底,而不是靠沙箱。已知盲区一处:**读命令的裸文件名参数**(`cat notes.txt`)不被收集为目标,所以把 `out read` 调成 `ask` 时只有绝对路径形状的读目标会被问——读本身不会写,四格模式的写侧不受影响。
+
+---
+
 ## ⭐ favorites — 模型收藏
 
 <a name="favorites"></a>
@@ -247,6 +298,15 @@ run = [
 
 无文件 = 功能未启用,零开销、静默跳过。
 
+**两个来源,按序执行,不做合并**:
+
+| 来源 | 路径 | project trust |
+| --- | --- | --- |
+| 全局(操作者默认) | `<agent-dir>/autostart.toml`(默认 `~/.pi/agent/autostart.toml`) | 不需要 —— 文件属于操作者本人 |
+| 项目 | `<项目根>/.pi/autostart.toml` | 需要 |
+
+全局列表先执行,项目列表后执行,因此项目可以覆盖此前的设置(例如后面再执行一条不同参数的 `/ask-perm`)。只有希望所有项目都用同一套命令时才用全局文件;仍然建议以项目级配置为主。
+
 **执行时机**:
 
 | session_start reason | 是否重放 | 原因 |
@@ -288,6 +348,7 @@ pnpm check:compat        # 校验声明的 pi 区间:最近 4 条中版本线 +
 src/
 ├── index.ts              # 入口:聚合各功能模块
 ├── lib/                  # 共享基础设施(工具集快照/恢复、
+│                         # 组合 tool_call 策略的闸门总线、
 │                         # review 与 compact 共用的模型 key 解析)
 └── features/             # 功能模块 —— 一个功能一个目录
     ├── ask/              # ask 模式:命令 + 状态机、bash 沙箱、
@@ -298,6 +359,8 @@ src/
     │                     #           /compact-model、配置存储、prompt、测试
     ├── favorites/        # 模型收藏:选择器与循环 patch、
     │                     #           持久化存储、测试
+    ├── permission/       # 会话级边界权限:模式、面板、bash 拆解、
+    │                     #           策略、会话授权、确认对话框、测试
     ├── review/           # 第三方评审:输入/指令触发、
     │                     #           评审模型配置存储、提示词、测试
     └── stash/            # 提示词暂存:热键状态机 + 测试

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@andares/pi-toolkits",
-  "version": "0.8.0",
-  "description": "Integrated toolkit extension for pi — ask mode (read-only Q&A), model favorites, prompt stash, third-party code review, and a dedicated compaction model",
+  "version": "0.9.0",
+  "description": "Integrated toolkit extension for pi — ask mode (read-only Q&A), session-scoped permission checks, model favorites, prompt stash, third-party code review, session autostart, and a dedicated compaction model",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -25,7 +25,10 @@
     "compaction",
     "compact-model",
     "toolkit",
-    "autostart"
+    "autostart",
+    "permission",
+    "approval",
+    "boundary"
   ],
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=1.0.0 <1.12.0",
@@ -33,6 +36,7 @@
   },
   "dependencies": {
     "@dreki-gg/pi-command-sandbox": "^0.4.3",
+    "shell-quote": "^1.12.0",
     "smol-toml": "^1.9.0"
   },
   "devDependencies": {

package/src/features/ask/index.test.ts

@@ -0,0 +1,118 @@
+/**
+ * ask mode over the gate bus.
+ *
+ * The feature's command/state behaviour predates the bus; what this covers is
+ * the migration itself: while ask mode is on, its gate blocks the tools it
+ * confiscates and non-read-only bash, and it stops speaking once the mode is
+ * off.
+ */
+import { describe, expect, it } from "vitest";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	ToolCallEvent,
+} from "@earendil-works/pi-coding-agent";
+import type { GateHub, ToolGate } from "../../lib/gates.js";
+import { registerAsk } from "./index.js";
+
+function event(toolName: string, input: Record<string, unknown> = {}): ToolCallEvent {
+	return {
+		type: "tool_call",
+		toolCallId: "call-1",
+		toolName,
+		input,
+	} as unknown as ToolCallEvent;
+}
+
+function makeHarness() {
+	const captured: ToolGate[] = [];
+	const hub = {
+		register(gate: ToolGate) {
+			captured.push(gate);
+		},
+		handle: async () => undefined,
+		install: () => {},
+	} as unknown as GateHub;
+
+	let activeTools = ["read", "write", "edit", "bash"];
+	let commandHandler: ((args: string, ctx: ExtensionContext) => unknown) | undefined;
+	const pi = {
+		on: () => {},
+		registerCommand(
+			name: string,
+			options: { handler: (args: string, ctx: ExtensionContext) => unknown },
+		) {
+			if (name === "ask") commandHandler = options.handler;
+		},
+		getActiveTools: () => [...activeTools],
+		getAllTools: () => [
+			{ name: "grep" },
+			{ name: "find" },
+			{ name: "ls" },
+		],
+		setActiveTools: (names: string[]) => {
+			activeTools = [...names];
+		},
+	} as unknown as ExtensionAPI;
+
+	const statuses: Array<[string, string | undefined]> = [];
+	const notes: string[] = [];
+	const ctx = {
+		hasUI: true,
+		mode: "tui",
+		ui: {
+			notify: (message: string) => notes.push(message),
+			setStatus: (key: string, value: string | undefined) => statuses.push([key, value]),
+			theme: { fg: (_color: string, text: string) => text },
+		},
+	} as unknown as ExtensionContext;
+
+	registerAsk(pi, hub);
+	const gate = captured[0];
+	if (!gate || !commandHandler) throw new Error("ask did not register");
+
+	return {
+		gate,
+		ctx,
+		activeTools: () => activeTools,
+		toggle: async () => {
+			await commandHandler?.("", ctx);
+		},
+		evaluate: async (toolName: string, input: Record<string, unknown> = {}) =>
+			gate.evaluate(event(toolName, input), ctx),
+	};
+}
+
+describe("ask gate", () => {
+	it("has no opinion while ask mode is off", async () => {
+		const h = makeHarness();
+		expect(await h.evaluate("write", { path: "x" })).toBeUndefined();
+	});
+
+	it("blocks confiscated tools and non-read-only bash while on", async () => {
+		const h = makeHarness();
+		await h.toggle();
+		expect(await h.evaluate("write", { path: "x" })).toMatchObject({
+			kind: "block",
+		});
+		expect(await h.evaluate("bash", { command: "rm -rf x" })).toMatchObject({
+			kind: "block",
+		});
+		expect(await h.evaluate("bash", { command: "ls -la" })).toBeUndefined();
+	});
+
+	it("stops blocking after exiting", async () => {
+		const h = makeHarness();
+		await h.toggle();
+		await h.toggle();
+		expect(await h.evaluate("write", { path: "x" })).toBeUndefined();
+	});
+
+	it("restores the tool snapshot on exit", async () => {
+		const h = makeHarness();
+		await h.toggle();
+		expect(h.activeTools()).not.toContain("write");
+		await h.toggle();
+		expect(h.activeTools()).toEqual(["read", "write", "edit", "bash"]);
+	});
+});

package/src/features/ask/index.ts

@@ -8,7 +8,10 @@
  *  - Read-only helper tools (grep/find/ls) are activated for the duration so
  *    the model gets proper search tools; the entry snapshot restores exactly.
  *  - bash stays available but is gated by a read-only sandbox
- *    (see bash-sandbox.ts) via the tool_call hook.
+ *    (see bash-sandbox.ts) through the shared gate bus (lib/gates.ts), so
+ *    another feature's gate (`permission`) runs alongside it rather than
+ *    replacing it: each feature owns its own concern and the call is blocked
+ *    when either objects.
  *  - Mode banner appended to the system prompt via before_agent_start
  *    chained systemPrompt (see prompt.ts), listing blocked -> alternative.
  */
@@ -16,6 +19,7 @@ import type {
 	ExtensionAPI,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import type { GateHub } from "../../lib/gates.js";
 import {
 	restoreActiveTools,
 	snapshotActiveTools,
@@ -31,7 +35,7 @@ import { isReadOnlyCommand } from "./bash-sandbox.js";
 import { appendAskBanner } from "./prompt.js";
 import { blockedBashReason, blockedToolReason } from "./reasons.js";
 
-export function registerAsk(pi: ExtensionAPI): void {
+export function registerAsk(pi: ExtensionAPI, gates: GateHub): void {
 	let enabled = false;
 	/** Active tools before ask mode was entered (for exact restore on exit). */
 	let snapshot: string[] = [];
@@ -102,20 +106,34 @@ export function registerAsk(pi: ExtensionAPI): void {
 	//  - bash is kept available but only read-only commands pass the sandbox.
 	// The rejection `reason` reaches the model as the tool result, so it names
 	// the nearest allowed alternative (see reasons.ts).
-	pi.on("tool_call", (event) => {
-		if (!enabled) return;
+	//
+	// Registered through the gate bus so the permission gate composes with it:
+	// ask answers "does this mutate?", permission answers "does this cross the
+	// project boundary?". A denied outside read still applies in ask mode, and
+	// a blocked write never reaches permission's dialog because a block
+	// short-circuits the bus.
+	gates.register({
+		name: "ask",
+		order: 10,
+		evaluate(event) {
+			if (!enabled) return undefined;
 
-		if (ASK_BLOCKED_TOOLS.has(event.toolName)) {
-			return { block: true, reason: blockedToolReason(event.toolName) };
-		}
+			if (ASK_BLOCKED_TOOLS.has(event.toolName)) {
+				return {
+					kind: "block",
+					reason: blockedToolReason(event.toolName),
+				};
+			}
 
-		if (event.toolName === "bash") {
-			const command =
-				typeof event.input.command === "string" ? event.input.command : "";
-			if (!isReadOnlyCommand(command)) {
-				return { block: true, reason: blockedBashReason(command) };
+			if (event.toolName === "bash") {
+				const command =
+					typeof event.input.command === "string" ? event.input.command : "";
+				if (!isReadOnlyCommand(command)) {
+					return { kind: "block", reason: blockedBashReason(command) };
+				}
 			}
-		}
+			return undefined;
+		},
 	});
 
 	// Mode banner: chained append to the current system prompt while enabled.

package/src/features/autostart/autostart.test.ts

@@ -16,6 +16,7 @@ import {
 	AUTOSTART_CONFIG_PATH,
 	AutostartParseError,
 	commandNameOf,
+	GLOBAL_AUTOSTART_FILENAME,
 	parseAutostartConfig,
 	RUNNABLE_REASONS,
 } from "./autostart.js";
@@ -138,8 +139,16 @@ interface Harness {
 async function makeHarness(
 	config: string | null,
 	configAsDir = false,
+	globalConfig: string | null = null,
 ): Promise<Harness> {
 	const cwd = await mkdtemp(join(tmpdir(), "pi-autostart-test-"));
+	// The agent dir lives inside the temp project so cleanup covers it; passing
+	// it explicitly keeps the real ~/.pi/agent out of the test.
+	const agentDir = join(cwd, "agent");
+	await mkdir(agentDir, { recursive: true });
+	if (globalConfig !== null) {
+		await writeFile(join(agentDir, GLOBAL_AUTOSTART_FILENAME), globalConfig, "utf8");
+	}
 	if (configAsDir) {
 		// EISDIR setup: the config path exists but is a directory.
 		await mkdir(join(cwd, ".pi"), { recursive: true });
@@ -172,7 +181,7 @@ async function makeHarness(
 			}
 		},
 	} as unknown as ExtensionAPI;
-	registerAutostart(pi);
+	registerAutostart(pi, { agentDir });
 	return {
 		handler,
 		sent,
@@ -209,8 +218,9 @@ afterEach(async () => {
 async function harness(
 	config: string | null,
 	configAsDir = false,
+	globalConfig: string | null = null,
 ): Promise<Harness> {
-	const h = await makeHarness(config, configAsDir);
+	const h = await makeHarness(config, configAsDir, globalConfig);
 	current = h;
 	return h;
 }
@@ -312,4 +322,37 @@ describe("registerAutostart", () => {
 		expect(h.notifications).toHaveLength(1);
 		expect(h.notifications[0]?.type).toBe("error");
 	});
+
+	it("runs the global config before the project config", async () => {
+		const h = await harness(
+			'[command]\nrun = ["/add-dir ../project"]',
+			false,
+			'[command]\nrun = ["/ask on"]',
+		);
+		await h.start("startup");
+		expect(h.sent.map((entry) => entry.command)).toEqual([
+			"/ask on",
+			"/add-dir ../project",
+		]);
+		expect(h.notifications).toEqual([]);
+	});
+
+	it("runs the global config in an untrusted project but skips the project one", async () => {
+		const h = await harness(
+			'[command]\nrun = ["/add-dir ../project"]',
+			false,
+			'[command]\nrun = ["/ask on"]',
+		);
+		h.setTrusted(false);
+		await h.start("startup");
+		expect(h.sent.map((entry) => entry.command)).toEqual(["/ask on"]);
+		expect(h.notifications).toHaveLength(1);
+		expect(h.notifications[0]?.type).toBe("warning");
+	});
+
+	it("keeps running the project config when the global one is absent", async () => {
+		const h = await harness('[command]\nrun = ["/ask on"]', false, null);
+		await h.start("startup");
+		expect(h.sent.map((entry) => entry.command)).toEqual(["/ask on"]);
+	});
 });

package/src/features/autostart/autostart.ts

@@ -18,10 +18,12 @@
  */
 import { parse as parseToml } from "smol-toml";
 
-/** Project-relative location of the autostart config (`.pi/` is pi's
- *  project-config convention, precedent: `.pi/mcp.json`). */
+/** Project-relative location of the project autostart config. */
 export const AUTOSTART_CONFIG_PATH = ".pi/autostart.toml";
 
+/** File name of the operator's global autostart config, inside the agent dir. */
+export const GLOBAL_AUTOSTART_FILENAME = "autostart.toml";
+
 /**
  * session_start reasons that replay autostart commands:
  *  - startup / new: fresh session in the project — replay