@andares/pi-toolkits 0.7.2 → 0.7.3

package/README.md

@@ -9,12 +9,12 @@
 [![npm version](https://img.shields.io/npm/v/@andares/pi-toolkits?label=npm&logo=npm)](https://www.npmjs.com/package/@andares/pi-toolkits)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Package Manager](https://img.shields.io/badge/package%20manager-pnpm-orange?logo=pnpm)](https://pnpm.io)
-[![pi >= 0.87](https://img.shields.io/badge/pi-%3E%3D0.87.0%20%3C2.0.0-blueviolet)](https://github.com/earendil-works/pi)
+[![pi >= 0.99](https://img.shields.io/badge/pi-%3E%3D0.99.0%20%3C2.0.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.
 
-**Requirements**: pi `>=0.87.0 <2.0.0` (covering the four most recently released minor lines — 0.87.x / 0.99.x / 1.0.x / 1.1.x; 0.88–0.98 were never released). Every one of the 11 published versions inside that range (0.87.0 → 1.1.0) was compared against the host `dist`: the extension APIs we use carry no breaking differences (1.0.4 → 1.1.0 only adds fields), and the two runtime patch targets used by favorites — `ModelSelectorComponent` / `AgentSession.cycleModel` — are byte-identical. `typecheck` plus the full test suite pass on each of 0.87.0, 0.87.1, 0.99.0, 0.99.2, 1.0.0, 1.0.4 and 1.1.0, and smoke-loading on real pi 1.1.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 `>=0.99.0 <2.0.0` (covering the four most recently released minor lines — 0.99.x / 1.0.x / 1.1.x / 1.2.x; 0.88–0.98 were never released). Every one of the 10 published versions inside that range (0.99.0 → 1.2.0) was compared against the host `dist`: the extension APIs we use carry no breaking differences (1.2.0 turns `before_agent_start` into a discriminated union and adds `reachesTools`; the fields we read are unchanged), and both runtime patch targets used by favorites — `ModelSelectorComponent` / `AgentSession.cycleModel` — are byte-identical, as are the `core/compaction/compaction.js` and `core/usage-totals.js` sources compact-model mirrors. `typecheck` plus the full test suite pass on each of 0.99.0, 0.99.1, 0.99.2, 1.0.0, 1.0.1, 1.0.2, 1.0.3, 1.0.4, 1.1.0 and 1.2.0, and smoke-loading on real pi 1.2.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.
 
 ---
 
@@ -65,7 +65,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` hard-disabled, `bash` runs in a read-only sandbox |
+| 🛡️ **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 |
 | ⭐ **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" |
@@ -82,12 +82,13 @@ Enter with `/ask` (press it again to exit). Meant for the case where you only wa
 
 **While active**:
 
-- **`write` / `edit` hard-disabled** — removed from the active tool set; pi rejects calls to inactive tools outright ("Tool not found"), so file modification becomes mechanically impossible
-- **`bash` kept, but sandboxed to read-only** — based on shell tokenization plus write-intent detection (blocks `curl -o/-O`, `wget -O`, `dd of=`, `tee`, redirections, and the like). Heuristic, not a security boundary
-- **System prompt appendix** — a mode description is appended so the model behaves along the read-only constraint
+- **`write` / `edit` / `powershell` hard-disabled** — removed from the active tool set; pi rejects calls to inactive tools outright ("Tool not found"), so file modification becomes mechanically impossible
+- **Read-only helper tools activated** — `grep` / `find` / `ls` (registered by pi but inactive by default) are switched on for the duration, so the model gets proper search tools instead of bash-only search; the entry snapshot is restored exactly on exit
+- **`bash` kept, but sandboxed to read-only** — shell tokenization, per-segment validation plus write-intent detection. Allowed beyond the obvious readers: git archaeology (`blame`, `grep`, `rev-parse`, `describe`, `shortlog`, `reflog show`, `stash list`, `tag -l`, `cat-file`, ...), package metadata queries (`pnpm view`, `pip show/list`, `python -m json.tool`) and network reads through `curl -s <url>` / `wget -O - <url>`. Still blocked: redirections, `tee`, `dd`, `sed -i`, installs/builds, git mutations, command substitution, command runners (`find -exec`, `git grep -O`, `rg --pre`), and every write target (`curl -o`, `wget -O file`, `git diff --output=`, `tree -o`). Heuristic, not a security boundary
+- **System prompt appendix names the alternatives** — the appended mode description states what is blocked *and what to use instead* (`read` for file contents, `curl -s` for URLs, `/ask` to exit). Rejected tool calls come back with a classified reason that points at the nearest allowed alternative, so the model does not retry blind variants
 - **Grey `ask` footer status** — a permanent reminder that read-only mode is on
 
-**Exit**: press `/ask` again; the tool-set snapshot taken on entry is fully restored.
+**Exit**: press `/ask` again; the tool-set snapshot taken on entry is fully restored (read-only helpers included).
 
 ---
 
@@ -195,7 +196,7 @@ pi's `/compact` and auto-compact summarize the context **with the current sessio
 | auto-compact threshold reached | summarized by the compaction model |
 | context overflow recovery | summarized by the compaction model, retry behavior unchanged |
 
-**Parts that are identical to pi's built-in behavior after takeover** (the built-in implementation is mirrored verbatim — byte-identical since 0.87.1, verified up to 1.1.0; 0.87.0 shipped an earlier split-turn prompt, and the mirror carries the 0.87.1 fix for every host — and only the executing model changes):
+**Parts that are identical to pi's built-in behavior after takeover** (the built-in implementation is mirrored verbatim — copied from 0.87.1, byte-identical across every published version of the supported window, 0.99.0 → 1.2.0 — and only the executing model changes; the conversation serializer itself is imported from the host, so it follows whatever the running host does, e.g. 1.2.0 stops feeding assistant thinking back into the summarization request):
 
 - **Summary format** — the structured Goal / Progress / Key Decisions checkpoint; when a summary already exists, the iterative-update prompt is used so information carries over instead of being lost
 - **Split behavior** — the `keepRecentTokens` retention policy, and `firstKeptEntryId` / `tokensBefore` passed back unchanged
@@ -262,7 +263,7 @@ No file = feature disabled, zero overhead, silently skipped.
 
 **Key constraint: extension commands only**. Commands registered via `registerCommand` such as `/add-dir` (pi-add-dir) and `/cd` (pi-cd) work; built-in commands (`/compact`, `/reload`, `/resume`, …) are dispatched in the TUI layer and cannot be triggered from the extension layer; skill commands (`/skill:name`) are an expansion mechanism rather than an execution mechanism. The target extension you depend on (e.g. pi-add-dir) must be installed first.
 
-> **Implementation notes**: execution uses `sendUserMessage(cmd, { expandPromptTemplates: true })` — that option routes `/cmd args` into command dispatch instead of the model prompt path (the wrapper defaults to `false`; verified against pi 0.87.0–1.1.0 sources, see the host-compatibility discipline in AGENTS.md). Pre-validation uses `pi.getCommands()` (accepting only `source: "extension"`). Depends on `smol-toml` (zero-dependency, ~10KB, TOML 1.0).
+> **Implementation notes**: execution uses `sendUserMessage(cmd, { expandPromptTemplates: true })` — that option routes `/cmd args` into command dispatch instead of the model prompt path (the wrapper defaults to `false`; `sendUserMessage` and `_tryExecuteExtensionCommand` are byte-identical across 0.99.0–1.2.0, see the host-compatibility discipline in AGENTS.md). Pre-validation uses `pi.getCommands()` (accepting only `source: "extension"`). Depends on `smol-toml` (zero-dependency, ~10KB, TOML 1.0).
 
 ---
 

package/README.zh-CN.md

@@ -9,12 +9,12 @@
 [![npm version](https://img.shields.io/npm/v/@andares/pi-toolkits?label=npm&logo=npm)](https://www.npmjs.com/package/@andares/pi-toolkits)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Package Manager](https://img.shields.io/badge/package%20manager-pnpm-orange?logo=pnpm)](https://pnpm.io)
-[![pi >= 0.87](https://img.shields.io/badge/pi-%3E%3D0.87.0%20%3C2.0.0-blueviolet)](https://github.com/earendil-works/pi)
+[![pi >= 0.99](https://img.shields.io/badge/pi-%3E%3D0.99.0%20%3C2.0.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`,后续持续追加。
 
-**版本要求**:pi `>=0.87.0 <2.0.0`(覆盖最近 4 个中版本线 0.87.x / 0.99.x / 1.0.x / 1.1.x —— 0.88–0.98 从未发布。区间内全部 11 个已发布版本(0.87.0 → 1.1.0)逐版本比对宿主 dist:用到的扩展 API 无破坏性差异(1.0.4 → 1.1.0 仅新增字段),favorites 两处运行时 patch 目标 `ModelSelectorComponent` / `AgentSession.cycleModel` 字节级一致;并在 0.87.0、0.87.1、0.99.0、0.99.2、1.0.0、1.0.4、1.1.0 上逐一通过 typecheck + 全量测试,在真实 pi 1.1.0 上冒烟加载无警告)。注:pi ≥ 0.99 的宿主要求 `@earendil-works/pi-tui` 声明为 peerDependencies `"*"`(由宿主提供),本包已按要求声明。
+**版本要求**:pi `>=0.99.0 <2.0.0`(覆盖最近 4 个中版本线 0.99.x / 1.0.x / 1.1.x / 1.2.x —— 0.88–0.98 从未发布。区间内全部 10 个已发布版本(0.99.0 → 1.2.0)逐版本比对宿主 dist:用到的扩展 API 无破坏性差异(1.2.0 把 `before_agent_start` 改为判别联合类型、新增 `reachesTools`,我们读取的字段未变),favorites 两处运行时 patch 目标 `ModelSelectorComponent` / `AgentSession.cycleModel` 字节级一致,compact-model 镜像所依据的 `core/compaction/compaction.js` 与 `core/usage-totals.js` 同样字节级一致;并在 0.99.0、0.99.1、0.99.2、1.0.0、1.0.1、1.0.2、1.0.3、1.0.4、1.1.0、1.2.0 上逐一通过 typecheck + 全量测试,在真实 pi 1.2.0 上冒烟加载无警告)。注:pi ≥ 0.99 的宿主要求 `@earendil-works/pi-tui` 声明为 peerDependencies `"*"`(由宿主提供),本包已按要求声明。
 
 ---
 
@@ -65,7 +65,7 @@ pi -e ./src/index.ts
 
 | 功能 | 入口 | 一句话说明 |
 | --- | --- | --- |
-| 🛡️ **ask** 只读咨询模式 | `/ask` | 进入只读问答模式,`write`/`edit` 硬禁用,`bash` 只读沙箱 |
+| 🛡️ **ask** 只读咨询模式 | `/ask` | 进入只读问答模式,`write`/`edit`/`powershell` 硬禁用,`bash` 只读沙箱,临时启用 `grep`/`find`/`ls` |
 | ⭐ **favorites** 模型收藏 | `/model` 内 `ctrl+A` / `ctrl+J` | 收藏常用模型(加粗亮黄标记),`ctrl+p` 仅在收藏间循环 |
 | 📥 **stash** 提示词暂存 | `ctrl+alt+y` | 一段提示词的暂存槽,按键交换 / 连按两次暂存并清空输入框 |
 | 🔎 **review** 第三方代码评审 | `/third-review` | 召唤配置的评审模型,对刚完成的任务做查+修,重点检查「本轮需求实现 / 是否有遗漏 / 是否有错误」 |
@@ -82,12 +82,13 @@ pi -e ./src/index.ts
 
 **进入后**:
 
-- **`write` / `edit` 硬禁用** —— 从活跃工具集中移除,pi 运行时对未激活工具的调用直接拒绝("Tool not found"),文件修改在机制上不可能发生
-- **`bash` 保留但只读沙箱** —— 基于 shell 分词 + 写盘意图检测(`curl -o/-O`、`wget -O`、`dd of=`、`tee`、重定向等一律拦截)。启发式,非安全边界
-- **系统提示词追加** —— 追加一段模式说明,模型会遵守只读约束行事
+- **`write` / `edit` / `powershell` 硬禁用** —— 从活跃工具集中移除,pi 运行时对未激活工具的调用直接拒绝("Tool not found"),文件修改在机制上不可能发生
+- **临时启用只读检索工具** —— `grep` / `find` / `ls`(宿主已注册但默认不激活)在 ask 期间打开,让模型有正规搜索工具而不是只能走 bash;退出时按进入前快照完整恢复
+- **`bash` 保留但只读沙箱** —— shell 分词 + 逐段校验 + 写盘意图检测。除常见读取命令外,放行 git 考古族(`blame`、`grep`、`rev-parse`、`describe`、`shortlog`、`reflog show`、`stash list`、`tag -l`、`cat-file` 等)、包元数据查询(`pnpm view`、`pip show/list`、`python -m json.tool`),以及网络读取 `curl -s <url>` / `wget -O - <url>`。仍拦截:重定向、`tee`、`dd`、`sed -i`、安装/构建、git 变更类命令、命令替换、会启动其它程序的选项(`find -exec`、`git grep -O`、`rg --pre`),以及一切写盘目标(`curl -o`、`wget -O file`、`git diff --output=`、`tree -o`)。启发式,非安全边界
+- **系统提示词给出替代方案** —— 追加的模式说明不仅列限制,还写明被拦后用什么替代(读文件用 `read`、取网页用 `curl -s`、要改动则 `/ask` 退出);被拒的工具调用返回分类原因,直接指向最近的可用替代,模型不会盲目重试
 - **灰色 `ask` footer 状态** —— 常驻提示当前处于只读模式
 
-**退出**:再按 `/ask`,完整恢复进入前的工具集快照。
+**退出**:再按 `/ask`,完整恢复进入前的工具集快照(含临时启用的只读工具)。
 
 ---
 
@@ -195,7 +196,7 @@ pi 的 `/compact` 与 auto-compact 默认**用当前会话模型**做上下文
 | auto-compact 阈值触发 | 压缩模型总结 |
 | context overflow 恢复 | 压缩模型总结,重试行为不变 |
 
-**接管后与 pi 内建行为完全一致的部分**(逐字同步 pi 内建实现,0.87.1 起字节级不变、已核对至 1.1.0,只换执行模型;0.87.0 的分割轮次前缀 prompt 与 0.87.1 不同,本镜像对所有宿主采用 0.87.1 的修复文本):
+**接管后与 pi 内建行为完全一致的部分**(逐字同步 pi 内建实现,复制自 0.87.1、在支持区间内全部已发布版本(0.99.0 → 1.2.0)字节级不变,只换执行模型;对话序列化函数(`serializeConversation`)是直接从宿主导入的,因此跟随宿主行为 —— 例如 1.2.0 起不再把 assistant thinking 回填进摘要请求):
 
 - **摘要格式** —— Goal / Progress / Key Decisions 结构化 checkpoint;已有摘要时用迭代更新版 prompt,信息延续不丢
 - **切分行为** —— 保留最近 `keepRecentTokens` 的策略、`firstKeptEntryId` / `tokensBefore` 原样回传,不动
@@ -262,7 +263,7 @@ run = [
 
 **关键约束:只支持扩展命令**。`/add-dir`(pi-add-dir)、`/cd`(pi-cd)等 `registerCommand` 注册的命令可以;内置命令(`/compact`、`/reload`、`/resume`…)在 TUI 层分发,扩展层触发不了;skill 命令(`/skill:name`)是展开机制而非执行机制。依赖的目标扩展(如 pi-add-dir)需要先安装。
 
-> **实现说明**:执行用 `sendUserMessage(cmd, { expandPromptTemplates: true })` —— 该选项把 `/cmd args` 路由到命令分发而不是模型 prompt 路径(包装层默认 `false`,已对照 pi 0.87.0–1.1.0 源码核实,见 AGENTS.md 宿主兼容纪律)。预校验用 `pi.getCommands()`(只认 `source: "extension"`)。依赖 `smol-toml`(零依赖、~10KB、TOML 1.0)。
+> **实现说明**:执行用 `sendUserMessage(cmd, { expandPromptTemplates: true })` —— 该选项把 `/cmd args` 路由到命令分发而不是模型 prompt 路径(包装层默认 `false`,`sendUserMessage` 与 `_tryExecuteExtensionCommand` 在 0.99.0–1.2.0 全区间字节级一致,见 AGENTS.md 宿主兼容纪律)。预校验用 `pi.getCommands()`(只认 `source: "extension"`)。依赖 `smol-toml`(零依赖、~10KB、TOML 1.0)。
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andares/pi-toolkits",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "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",
   "type": "module",
   "license": "MIT",
@@ -28,7 +28,7 @@
     "autostart"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.87.0 <2.0.0",
+    "@earendil-works/pi-coding-agent": ">=0.99.0 <2.0.0",
     "@earendil-works/pi-tui": "*"
   },
   "dependencies": {
@@ -36,9 +36,9 @@
     "smol-toml": "^1.9.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^1.1.0",
-    "@earendil-works/pi-coding-agent": "^1.1.0",
-    "@earendil-works/pi-tui": "^1.1.0",
+    "@earendil-works/pi-ai": "^1.2.0",
+    "@earendil-works/pi-coding-agent": "^1.2.0",
+    "@earendil-works/pi-tui": "^1.2.0",
     "@types/node": "^26.6.2",
     "typescript": "^5.6.0",
     "vitest": "^4.1.10"

package/src/features/ask/bash-sandbox.test.ts

@@ -2,7 +2,7 @@
  * Boundary tests for the ask-mode read-only bash sandbox.
  */
 import { describe, expect, it } from "vitest";
-import { isReadOnlyCommand } from "./bash-sandbox.js";
+import { classifyBlockedCommand, isReadOnlyCommand } from "./bash-sandbox.js";
 
 describe("isReadOnlyCommand — allowed (read-only)", () => {
 	const allowed = [
@@ -14,6 +14,10 @@ describe("isReadOnlyCommand — allowed (read-only)", () => {
 		"git status",
 		"git log --oneline -5",
 		"git diff --stat",
+		"git show HEAD",
+		"git branch -a",
+		"git remote -v",
+		"git show HEAD 2>/dev/null",
 		"grep -r foo src",
 		"find . -name '*.ts'",
 		"cd src && ls",
@@ -21,7 +25,12 @@ describe("isReadOnlyCommand — allowed (read-only)", () => {
 		"npm list --depth=0",
 		"curl -s https://example.com",
 		"curl -o - https://example.com", // stdout, allowed
+		"curl --output - https://example.com", // stdout, allowed
+		"curl --output=- https://example.com", // stdout, allowed
 		"wget -O - https://example.com", // stdout, allowed
+		"wget -qO- https://example.com", // stdout, allowed
+		"wget -O - --quiet https://example.com", // stdout, allowed
+		"wget --output-document=- https://example.com", // stdout, allowed
 		"echo 'hello && world'", // quoted operator is data, not control
 	];
 
@@ -30,6 +39,61 @@ describe("isReadOnlyCommand — allowed (read-only)", () => {
 	});
 });
 
+describe("isReadOnlyCommand — allowed (relaxed read-only families)", () => {
+	const allowed = [
+		// git archaeology
+		"git blame -L 10,20 src/index.ts",
+		"git grep -n registerAsk -- src",
+		"git rev-parse HEAD",
+		"git rev-list --count HEAD",
+		"git describe --tags --abbrev=0",
+		"git shortlog -sn",
+		"git reflog show",
+		"git reflog",
+		"git stash list",
+		"git stash show -p",
+		"git worktree list",
+		"git tag -l",
+		"git tag --list 'v*'",
+		"git cat-file -p HEAD",
+		"git merge-base HEAD~5 HEAD",
+		"git check-ignore -v node_modules",
+		"git config --list",
+		// destructive-substring false positives in arguments
+		"git log --grep=rm --oneline",
+		"git blame src/rm-utils.ts",
+		"git log --grep=rm --oneline && ls src",
+		// search arguments that merely *mention* a guarded flag are data
+		"grep -rn 'find -exec' src",
+		"git grep -n 'find -exec' -- .",
+		"git log --grep='curl -so x' --oneline",
+		"rg 'sed -i' .",
+		// package metadata
+		"pnpm view vite version",
+		"pnpm info react",
+		"pnpm search eslint",
+		"pip show requests",
+		"pip list",
+		"pip3 freeze",
+		"uv pip list",
+		"python3 -m json.tool package.json",
+		// guards must not over-block plain readers
+		"fd -e ts",
+		"sort package.json",
+		"curl -so- https://example.com", // clustered short form, stdout
+		"git grep --textconv -n foo", // read path, not the -O pager
+		"env", // bare env prints the environment
+		"env -i",
+		"env FOO=bar", // assignment-only form, no command
+		"file README.md",
+		"sed -n '1p' README.md",
+	];
+
+	it.each(allowed)("allows: %s", (command) => {
+		expect(isReadOnlyCommand(command)).toBe(true);
+	});
+});
+
 describe("isReadOnlyCommand — blocked (mutating/destructive)", () => {
 	const blocked = [
 		"rm -rf /",
@@ -40,19 +104,67 @@ describe("isReadOnlyCommand — blocked (mutating/destructive)", () => {
 		"touch foo",
 		"npm install",
 		"npm run build",
+		"pnpm install",
+		"pnpm add left-pad",
+		"pip install requests",
 		"git commit -m x",
 		"git push",
 		"git checkout main",
+		"git reset --hard",
+		"git stash drop",
+		"git stash pop",
+		"git worktree remove x",
+		"git reflog expire --all",
+		"git tag v1",
+		"git tag -d v1",
+		"git branch new-branch",
+		"git branch -m old new",
+		"git branch -D old",
+		"git remote add origin git@example.com:x/y.git",
+		"git remote remove origin",
 		"cat x > out.txt",
 		"echo hi >> log",
 		"echo $(rm -rf /)", // command substitution
+		"git log --grep=$(rm -rf /)", // substitution hidden in an allowed verb
 		"ls | rm -rf /", // pipeline with destructive command
+		"git log --grep=rm --oneline && rm -rf /", // second segment is a write
+		"find . -name x -exec rm {} \\;", // find stays out of the read-only bypass
+		"find . -delete", // -delete is a write
+		"ls | find . -delete", // ... and the pre-check sees pipelines too
+		"find . -name '*.ts' -exec sh -c 'echo x > /tmp/y' \\;", // -exec runs commands
+		"ls | find . -name x -exec echo {} \\;", // exec intent outside the first segment
+		"fd . -x rm", // fd -x runs commands: never on the bypass list
+		"fd . -x touch y",
+		"fd --exec rm {}",
+		"sort -o out.txt file", // sort's output flag is a write
+		"sort file --output=out.txt",
+		"curl -so /tmp/x https://example.com", // clustered short form writes
+		"curl -o/tmp/x https://example.com", // attached short form writes
+		"curl -sLo /tmp/x https://example.com",
+		"curl --remote-name https://example.com",
+		"sed -n -i 's/a/b/' f", // -i sneaks past the `sed -n` allowlist
+		"tree -o /tmp/x",
+		"tree --output=/tmp/x",
+		"file -C -m magic",
+		"git grep -O 'rm -rf /' pattern", // -O runs a pager command
+		"git grep --open-files-in-pager=less pattern",
+		"git log --ext-diff -p", // external diff driver
+		"env curl -o out.txt https://example.com", // env forwards to a write
+		"env -i curl -o out.txt https://example.com",
+		"env FOO=1 curl -o out.txt https://example.com",
+		"ls && env curl -o out.txt https://example.com",
+		"env -S 'sh -c x'",
+		"env find . -delete",
+		"env sed -i 's/a/b/' f",
 		"curl -o file https://example.com",
 		"curl -O https://example.com/x",
 		"curl --output file https://example.com",
 		"wget -O file https://example.com",
 		"wget --output-document file https://example.com",
-		"wget -qO- https://example.com", // sandbox rejects (only wget -O - is safe); fine, be strict
+		"wget https://example.com",
+		"git diff --output=out.txt", // real write path on a read-only verb
+		"git log --output out.txt",
+		"git show -o out.txt",
 		"dd if=/dev/zero of=/tmp/x bs=1 count=1",
 		"echo x | tee file",
 		"vim README.md",
@@ -64,3 +176,22 @@ describe("isReadOnlyCommand — blocked (mutating/destructive)", () => {
 		expect(isReadOnlyCommand(command)).toBe(false);
 	});
 });
+
+describe("classifyBlockedCommand", () => {
+	it.each([
+		["echo $(id)", "substitution"],
+		["cat a > b", "redirect"],
+		["git grep -O x", "exec"],
+		["env curl -o out.txt https://example.com", "exec"],
+		["find . -exec echo {} ;", "exec"],
+		["rm -rf /", "write"],
+		["find . -delete", "write"],
+		["curl -O https://example.com", "write"],
+		["wget https://example.com", "download"],
+		["git commit -m x", "git"],
+		["pnpm install", "install"],
+		["vim README.md", "unlisted"],
+	] as const)("classifies %s as %s", (command, kind) => {
+		expect(classifyBlockedCommand(command)).toBe(kind);
+	});
+});

package/src/features/ask/bash-sandbox.ts

@@ -5,35 +5,239 @@
  * per-segment validation (&& | ; etc.), command-substitution rejection and
  * deny-by-default for unmodeled operators.
  *
- * On top of that, this wrapper adds write-intent detection for known blind
- * spots: allowlisted commands whose arguments can write files (curl -o/-O,
- * wget -O, dd of=, tee). Heuristic only — not a security boundary.
+ * This wrapper adds four things on top:
+ *  1. write-intent detection for known blind spots — allowlisted commands
+ *     whose arguments can still write files (curl/wget output targets, dd of=,
+ *     tee, sed -i, sort -o, tree -o, find -delete, the git diff family's
+ *     --output).
+ *  2. exec-intent detection — read-by-name commands whose options run another
+ *     program (git grep -O, git --ext-diff, find -exec/-ok, fd -x, rg --pre).
+ *  3. `extraSafe` patterns for read-only commands the upstream allowlist does
+ *     not model: git archaeology verbs, package metadata queries,
+ *     `python -m json.tool`, wget's stdout form.
+ *  4. a per-segment read-only bypass for DESTRUCTIVE_PATTERNS that match only
+ *     a command's *arguments* (`git log --grep=rm`, `git blame src/rm-utils.ts`)
+ *     — see READ_ONLY_COMMAND_PATTERNS.
+ *
+ * Heuristic only — not a security boundary.
  */
-import { isSafeCommand } from "@dreki-gg/pi-command-sandbox";
+import {
+	hasCommandSubstitution,
+	isSafeCommand,
+	parseCommandSegments,
+} from "@dreki-gg/pi-command-sandbox";
+
+/* -------------------------------------------------------------------------- */
+/* Write intent                                                               */
+/* -------------------------------------------------------------------------- */
 
+/**
+ * Commands that are safe by name but whose arguments can write files.
+ * Patterns are anchored at the command position and checked per shell segment,
+ * so grep/rg *search arguments* mentioning a flag (`grep -rn "curl -so"`) are
+ * data, not intent. Stdout forms stay explicitly allowed: `-o -` / `-O -` /
+ * `-qO-` / `--output -` / `--output=-` / `--output-document=-`.
+ */
 const WRITE_INTENT_PATTERNS: RegExp[] = [
-	// curl --output FILE
-	/\bcurl\b[^|;&]*\s--output\b/i,
-	// curl -o FILE (curl -o - / -o- = stdout, allowed)
-	/\bcurl\b[^|;&]*\s-o\s+(?!-)\S+/,
-	// curl -O (uppercase: save to disk under remote name)
-	/\bcurl\b[^|;&]*\s-O\b/,
-	// wget --output-document FILE
-	/\bwget\b[^|;&]*\s--output-document\b/i,
+	// curl --output FILE (curl --output - / --output=- = stdout, allowed)
+	/^\s*curl\b[^|;&]*\s--output(?:=|\s+)(?!-)\S+/i,
+	// curl -o FILE / -oFILE / -so FILE: short form, attached or clustered
+	// (`-o -` / `-o-` / `-so-` are stdout and stay allowed)
+	/^\s*curl\b[^|;&]*\s-[a-zA-Z]*o(?:\s+(?!-)\S+|(?!-)\S+)/,
+	// curl -O / -sO / --remote-name: always saves to disk
+	/^\s*curl\b[^|;&]*\s-[a-zA-Z]*O\b/,
+	/^\s*curl\b[^|;&]*\s--remote-name\b/i,
+	// wget --output-document FILE (--output-document - = stdout, allowed)
+	/^\s*wget\b[^|;&]*\s--output-document(?:=|\s+)(?!-)\S+/i,
 	// wget -O FILE (wget -O - / -qO- = stdout, allowed)
-	/\bwget\b[^|;&]*\s-O\s+(?!-)\S+/,
+	/^\s*wget\b[^|;&]*\s-O\s+(?!-)\S+/,
 	// dd of=FILE
-	/\bdd\b[^|;&]*\sof=/i,
+	/^\s*dd\b[^|;&]*\sof=/i,
 	// tee FILE (writes to stdout AND file)
-	/\btee\b/i,
+	/^\s*tee\b/i,
+	// sed -i / -ni: in-place edits; only `sed -n` is otherwise allowlisted
+	/^\s*sed\b[^|;&]*\s-[a-zA-Z]*i(?:\s|$)/i,
+	/^\s*sed\b[^|;&]*\s--in-place\b/i,
+	// sort -o FILE / --output FILE
+	/^\s*sort\b[^|;&]*\s(?:-o\s|--output(?:=|\s+))/i,
+	// tree -o FILE / --output FILE (short form may be clustered: -ao FILE)
+	/^\s*tree\b[^|;&]*\s(?:-[a-zA-Z]*o(?:\s|$)|--output(?:=|\s+))/i,
+	// file -C / --compile writes the compiled magic database
+	/^\s*file\b[^|;&]*\s(?:-[a-zA-Z]*C(?:\s|$)|--compile\b)/i,
+	// find -delete (its -exec/-ok forms are exec intent below)
+	/^\s*find\b[^|;&]*\s-delete\b/i,
+	// git diff family --output FILE: a real write path on commands that are
+	// otherwise read-only (`git diff --output=out.txt` creates the file).
+	// `-o` is not a valid short option for these verbs; guarding it is free.
+	/^\s*git\s+(?:log|diff|show|diff-tree|whatchanged)\b[^|;&]*(?:\s--output(?:=|\s+)|\s-o\s)\S+/i,
 ];
 
+/** True when a segment is a write-intent invocation. */
 function hasWriteIntent(command: string): boolean {
-	return WRITE_INTENT_PATTERNS.some((pattern) => pattern.test(command));
+	return parseCommandSegments(command).some((segment) =>
+		WRITE_INTENT_PATTERNS.some((pattern) => pattern.test(segment.command)),
+	);
+}
+
+/* -------------------------------------------------------------------------- */
+/* Exec intent                                                                */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Read-by-name commands whose options start another program. Same per-segment,
+ * command-position anchoring as the write intent above, so an allowed verb
+ * cannot smuggle execution in and search arguments stay data.
+ */
+const EXEC_INTENT_PATTERNS: RegExp[] = [
+	// git grep -O[pager] / --open-files-in-pager: runs a pager on matched files
+	/^\s*git\s+grep\b[^|;&]*\s(?:-O|--open-files-in-pager\b)/i,
+	// external diff drivers (from config/gitattributes)
+	/^\s*git\s+\S+\b[^|;&]*\s--ext-diff\b/i,
+	// env forwards to another command (`env [-i] [-u NAME] [NAME=VALUE] CMD …`);
+	// bare env, flag-only and assignment-only forms print the environment and
+	// stay allowed (the lookahead keeps NAME=VALUE from posing as CMD)
+	/^\s*env\b(?:\s+(?:-\S+|[A-Za-z_][A-Za-z0-9_]*=\S+))*\s+(?![A-Za-z_][A-Za-z0-9_]*=)[^-\s]\S*/,
+	// find/fd command runners
+	/^\s*find\b[^|;&]*\s-(?:exec|execdir|ok|okdir)\b/i,
+	/^\s*fd\b[^|;&]*\s(?:-x|--exec(?:-batch)?)\b/i,
+	// ripgrep preprocessor
+	/^\s*rg\b[^|;&]*\s--pre(?:=|\s)/i,
+];
+
+/** True when a segment is an exec-intent invocation. */
+function hasExecIntent(command: string): boolean {
+	return parseCommandSegments(command).some((segment) =>
+		EXEC_INTENT_PATTERNS.some((pattern) => pattern.test(segment.command)),
+	);
+}
+
+/* -------------------------------------------------------------------------- */
+/* Read-only allowlist extensions                                             */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Read-only commands the upstream allowlist lacks, plus the read-only forms of
+ * git verbs that also have mutating siblings.
+ *
+ * Every pattern is anchored and pinned to stdout-only shapes:
+ *  - no `find -exec`/`-delete`, no `fd -x`, no `sort -o`, no `sed -i`;
+ *  - `git stash` is pinned to list/show (`drop`/`pop`/`apply` stay blocked);
+ *  - `git tag` is pinned to -l/--list (create/delete stay blocked);
+ *  - `git reflog` is pinned to bare/`show` (delete/expire stay blocked);
+ *  - `git config` is pinned to get/list forms (set/unset stay blocked).
+ */
+const READ_ONLY_COMMAND_PATTERNS: RegExp[] = [
+	// git: read-only archaeology verbs upstream never modeled
+	/^\s*git\s+(?:blame|grep|rev-parse|rev-list|describe|shortlog|cat-file|show-ref|for-each-ref|name-rev|diff-tree|whatchanged|merge-base|cherry|check-ignore|check-attr|count-objects)\b/i,
+	// git: upstream read verbs whose arguments may hold destructive words
+	/^\s*git\s+(?:log|diff|show|status|ls-files|ls-tree)\b/i,
+	// git: read-only forms of verbs that also mutate
+	/^\s*git\s+reflog(?:\s+show\b[^|;&]*)?\s*$/i,
+	/^\s*git\s+stash\s+(?:list|show)\b/i,
+	/^\s*git\s+worktree\s+list\b/i,
+	/^\s*git\s+tag\s+(?:-l|--list)\b/i,
+	/^\s*git\s+config\s+(?:--get\b|--get-all\b|--get-regexp\b|-l\b|--list\b)/i,
+	// harmless navigation/readers commonly chained before a search
+	/^\s*cd\b/i,
+	/^\s*(?:head|tail|cat|tac|wc|uniq|jq|column)\b/i,
+	/^\s*(?:ls|file|stat|tree|du|df|bat|eza)\b/i,
+	/^\s*(?:grep|rg)\b/i,
+	/^\s*sed\s+-n\b/i,
+	// package metadata (network/library reads, never installs)
+	/^\s*pnpm\s+(?:view|info|search|licenses)\b/i,
+	/^\s*pip3?\s+(?:show|list|freeze)\b/i,
+	/^\s*uv\s+(?:pip\s+(?:list|show|freeze)|tree)\b/i,
+	/^\s*python3?\s+-m\s+json\.tool\b/i,
+	// network reads: wget to stdout only (file targets stay blocked)
+	/^\s*wget\b[^|;&]*\s(?:-O\s*-|-O-|-qO-|--output-document(?:=|\s+)-)/i,
+];
+
+/**
+ * Gaps in the upstream DESTRUCTIVE_PATTERNS closed here: git commands that can
+ * write but are not modeled as destructive — `git branch <name>` creates a ref,
+ * `git branch -m/-M/-c/-C` moves/copies, `git remote add/remove/set-url/...`
+ * edits .git/config. File-write and command-runner options are handled by the
+ * write/exec intent checks above (which run on the raw command, so pipelines
+ * are covered too).
+ */
+const EXTRA_DESTRUCTIVE_PATTERNS: RegExp[] = [
+	// positional argument after `branch` = create branch (flags stay read-only)
+	/^\s*git\s+branch\s+(?=[^-\s])/i,
+	/^\s*git\s+branch\s+-(?:[mMcC]\b|move\b|copy\b|edit-description\b)/i,
+	// remote subcommands other than the read-only ones
+	/^\s*git\s+remote\s+(?!-)(?!(?:show|get-url)(?=\s|$))/i,
+];
+
+/**
+ * True when every parsed segment is a curated read-only shape: no redirect, no
+ * unmodeled operator, each segment matching one of the patterns above.
+ *
+ * Used as `allowCommand`, which runs *before* the package's destructive check —
+ * that is what lets `git log --grep=rm` through while `git log && rm -rf x`
+ * still fails (the second segment matches nothing here).
+ */
+function allSegmentsReadOnly(command: string): boolean {
+	const segments = parseCommandSegments(command);
+	if (segments.length === 0) return false;
+	return segments.every(
+		(segment) =>
+			!segment.hasRedirect &&
+			segment.unsafeOperator === undefined &&
+			READ_ONLY_COMMAND_PATTERNS.some((pattern) =>
+				pattern.test(segment.command),
+			),
+	);
 }
 
 /** True when `command` is considered read-only by the sandbox. */
 export function isReadOnlyCommand(command: string): boolean {
 	if (hasWriteIntent(command)) return false;
-	return isSafeCommand(command);
+	if (hasExecIntent(command)) return false;
+	// The read-only-segment bypass below runs before the package's own
+	// substitution check, so reject command substitution here first.
+	if (hasCommandSubstitution(command)) return false;
+	return isSafeCommand(command, {
+		extraSafe: READ_ONLY_COMMAND_PATTERNS,
+		extraDestructive: EXTRA_DESTRUCTIVE_PATTERNS,
+		allowCommand: allSegmentsReadOnly,
+	});
+}
+
+/* -------------------------------------------------------------------------- */
+/* Block classification (for actionable rejection messages)                   */
+/* -------------------------------------------------------------------------- */
+
+/** Why a bash command was rejected; drives the message shown to the model. */
+export type BashBlockKind =
+	| "substitution"
+	| "redirect"
+	| "exec"
+	| "write"
+	| "download"
+	| "git"
+	| "install"
+	| "unlisted";
+
+const INSTALL_INTENT: RegExp[] = [
+	/\b(?:npm|pnpm|yarn|bun)\s+(?:i|install|add|remove|rm|update|up|ci|link|publish|dlx|exec|create)\b/i,
+	/\bpip3?\s+(?:install|uninstall)\b/i,
+	/\b(?:apt|apt-get|brew|cargo|go)\s+(?:install|add|get)\b/i,
+];
+
+/** Classic file writers, for classifying a rejection as a write attempt. */
+const WRITER_INTENT =
+	/\b(?:rm|rmdir|mv|cp|mkdir|touch|chmod|chown|chgrp|ln|truncate|shred|dd|sed\s+-i|sort\s+-o|yq\s+-i)\b/i;
+
+/** Classify a rejected command so the block reason can point at alternatives. */
+export function classifyBlockedCommand(command: string): BashBlockKind {
+	if (hasCommandSubstitution(command)) return "substitution";
+	if (parseCommandSegments(command).some((segment) => segment.hasRedirect)) {
+		return "redirect";
+	}
+	if (hasExecIntent(command)) return "exec";
+	if (hasWriteIntent(command) || WRITER_INTENT.test(command)) return "write";
+	if (/\b(?:wget|curl)\b/i.test(command)) return "download";
+	if (/^\s*git\b/i.test(command)) return "git";
+	if (INSTALL_INTENT.some((pattern) => pattern.test(command))) return "install";
+	return "unlisted";
 }

package/src/features/ask/constants.ts

@@ -2,12 +2,27 @@
  * ask feature — constants (tool names, UI keys, labels).
  */
 
-/** Tools hard-removed from the active set while ask mode is on. */
+/**
+ * Tools hard-removed from the active set while ask mode is on.
+ *
+ * `write`/`edit` are the obvious ones. `powershell` is a shell too: pi
+ * registers it on every platform (inactive by default, enabled by settings),
+ * and it would otherwise hand ask mode a full write channel.
+ */
 export const ASK_BLOCKED_TOOLS: ReadonlySet<string> = new Set([
 	"write",
 	"edit",
+	"powershell",
 ]);
 
+/**
+ * Read-only helper tools activated for the duration of ask mode (when the host
+ * has them registered). pi registers `grep`/`find`/`ls` but leaves them
+ * inactive by default; ask mode is a reading mode, so the model gets proper
+ * search tools instead of bash-only search. Restored exactly on exit.
+ */
+export const ASK_READ_ONLY_HELPERS: readonly string[] = ["grep", "find", "ls"];
+
 /** Footer status key (extension-scoped) and label. */
 export const ASK_STATUS_KEY = "ask-mode";
 export const ASK_STATUS_LABEL = "ask";

package/src/features/ask/index.ts

@@ -2,13 +2,15 @@
  * ask feature — read-only Q&A mode.
  *
  * Design notes (see PLAN.md):
- *  - Hard guarantee: write/edit are removed from the active tool set via
- *    pi.setActiveTools(); pi's runtime rejects calls to non-active tools
+ *  - Hard guarantee: write/edit/powershell are removed from the active tool set
+ *    via pi.setActiveTools(); pi's runtime rejects calls to non-active tools
  *    ("Tool not found") so nothing executes.
+ *  - 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.
  *  - Mode banner appended to the system prompt via before_agent_start
- *    chained systemPrompt (see prompt.ts).
+ *    chained systemPrompt (see prompt.ts), listing blocked -> alternative.
  */
 import type {
 	ExtensionAPI,
@@ -21,11 +23,13 @@ import {
 } from "../../lib/tools.js";
 import {
 	ASK_BLOCKED_TOOLS,
+	ASK_READ_ONLY_HELPERS,
 	ASK_STATUS_KEY,
 	ASK_STATUS_LABEL,
 } from "./constants.js";
 import { isReadOnlyCommand } from "./bash-sandbox.js";
 import { appendAskBanner } from "./prompt.js";
+import { blockedBashReason, blockedToolReason } from "./reasons.js";
 
 export function registerAsk(pi: ExtensionAPI): void {
 	let enabled = false;
@@ -40,14 +44,30 @@ export function registerAsk(pi: ExtensionAPI): void {
 		);
 	}
 
+	/** Read-only helpers currently active (drives the banner's search hint). */
+	function activeHelperTools(): string[] {
+		const active = new Set(pi.getActiveTools());
+		return ASK_READ_ONLY_HELPERS.filter((name) => active.has(name));
+	}
+
 	function enter(ctx: ExtensionContext): void {
 		if (enabled) return;
 		enabled = true;
 		snapshot = snapshotActiveTools(pi);
-		pi.setActiveTools(withoutTools(snapshot, ASK_BLOCKED_TOOLS));
+		// Activate grep/find/ls when the host has them registered and they were
+		// not already active. Names must be registered; unknown names are ignored
+		// by setActiveTools, but filtering here keeps the intent explicit.
+		const registered = new Set(pi.getAllTools().map((tool) => tool.name));
+		const helpers = ASK_READ_ONLY_HELPERS.filter(
+			(name) => registered.has(name) && !snapshot.includes(name),
+		);
+		pi.setActiveTools([
+			...withoutTools(snapshot, ASK_BLOCKED_TOOLS),
+			...helpers,
+		]);
 		updateStatus(ctx);
 		ctx.ui.notify(
-			"Ask mode ON — read-only (write/edit disabled). /ask to exit.",
+			"Ask mode ON — read-only (write/edit/powershell disabled, bash sandboxed). /ask to exit.",
 			"info",
 		);
 	}
@@ -77,27 +97,23 @@ export function registerAsk(pi: ExtensionAPI): void {
 	});
 
 	// Defense-in-depth gate while ask mode is active:
-	//  - write/edit are already removed from the active set (runtime rejects
-	//    them), this blocks them again in case anything re-enables them.
+	//  - write/edit/powershell are already removed from the active set (runtime
+	//    rejects them); this blocks them again in case anything re-enables them.
 	//  - 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;
 
-		if (event.toolName === "write" || event.toolName === "edit") {
-			return {
-				block: true,
-				reason:
-					"Ask mode: write/edit are disabled. Use /ask to exit ask mode first.",
-			};
+		if (ASK_BLOCKED_TOOLS.has(event.toolName)) {
+			return { block: true, reason: blockedToolReason(event.toolName) };
 		}
 
 		if (event.toolName === "bash") {
-			const command = event.input.command as string;
+			const command =
+				typeof event.input.command === "string" ? event.input.command : "";
 			if (!isReadOnlyCommand(command)) {
-				return {
-					block: true,
-					reason: `Ask mode: only read-only bash commands are allowed.\nCommand: ${command}\nUse /ask to exit ask mode first.`,
-				};
+				return { block: true, reason: blockedBashReason(command) };
 			}
 		}
 	});
@@ -107,6 +123,10 @@ export function registerAsk(pi: ExtensionAPI): void {
 		if (!enabled) return;
 		// event.systemPrompt is the current (possibly already modified by other
 		// extensions) system prompt — append, don't replace.
-		return { systemPrompt: appendAskBanner(event.systemPrompt) };
+		return {
+			systemPrompt: appendAskBanner(event.systemPrompt, {
+				helperTools: activeHelperTools(),
+			}),
+		};
 	});
 }

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

@@ -0,0 +1,45 @@
+/**
+ * Tests for the ask-mode banner: current state + blocked -> alternative hints.
+ */
+import { describe, expect, it } from "vitest";
+import { appendAskBanner, buildAskBanner } from "./prompt.js";
+
+describe("buildAskBanner", () => {
+	it("states the hard-blocked tools and the exit path", () => {
+		const banner = buildAskBanner();
+		expect(banner).toContain("[ASK MODE — read-only]");
+		expect(banner).toContain("write, edit, powershell");
+		expect(banner).toContain("/ask");
+	});
+
+	it("names the alternatives for blocked commands", () => {
+		const banner = buildAskBanner();
+		expect(banner).toContain("`read` tool");
+		expect(banner).toContain("`curl -s <url>`");
+		expect(banner).toContain("cat/sed tricks");
+	});
+
+	it("lists the read-only git families", () => {
+		const banner = buildAskBanner();
+		expect(banner).toContain("blame");
+		expect(banner).toContain("reflog show");
+		expect(banner).toContain("stash list");
+	});
+
+	it("adds the helper-tool hint only when helpers are active", () => {
+		const withHelpers = buildAskBanner({ helperTools: ["grep", "find", "ls"] });
+		expect(withHelpers).toContain("`grep`/`find`/`ls` tools");
+
+		const withoutHelpers = buildAskBanner();
+		expect(withoutHelpers).not.toContain("active during ask mode");
+	});
+});
+
+describe("appendAskBanner", () => {
+	it("appends instead of replacing the existing system prompt", () => {
+		const original = "You are a helpful coding agent.";
+		const combined = appendAskBanner(original, { helperTools: ["grep"] });
+		expect(combined.startsWith(original)).toBe(true);
+		expect(combined).toContain("[ASK MODE — read-only]");
+	});
+});

package/src/features/ask/prompt.ts

@@ -1,22 +1,61 @@
 /**
  * ask feature — system prompt banner.
  *
- * Appended to the system prompt (chained append, not replacement) while
- * ask mode is active so the model knows the current mode and its
- * restrictions. Do NOT use the removed `systemPromptAppend` field or
- * wholesale systemPrompt replacement (see PLAN.md).
+ * Appended to the system prompt (chained append, not replacement) while ask
+ * mode is active so the model knows the current mode, what it may still use,
+ * and — for everything blocked — what to use instead. Do NOT use the removed
+ * `systemPromptAppend` field or wholesale systemPrompt replacement (see
+ * PLAN.md).
  */
 
-export const ASK_BANNER = `[ASK MODE]
-You are in ask mode — a read-only Q&A mode. You may read, search, and analyze the codebase, but you MUST NOT modify anything.
+export interface AskBannerOptions {
+	/** Read-only helper tools active in this session (subset of grep/find/ls). */
+	readonly helperTools?: readonly string[];
+}
+
+const BANNER_HEADER = `[ASK MODE — read-only]
+You are in ask mode: answer questions and read code; nothing may be modified.
+
+Hard-blocked (calls fail — no workaround): write, edit, powershell.
+If fulfilling a request needs a change, say exactly what to change and tell the
+user to exit ask mode with /ask first.
+
+bash runs under a read-only allowlist. Working examples:
+- files:    ls, cat, head, tail, sed -n, wc, file, stat, diff, tree
+- search:   grep, rg, fd, find (without -exec), jq
+- git:      status, log, diff, show, branch, remote, blame, grep, rev-parse,
+            describe, shortlog, reflog show, stash list, tag -l, cat-file
+- network:  curl -s <url>, wget -O - <url>
+- packages: npm view, pnpm view, pip show/list, python3 -m json.tool
 
-Restrictions:
-- write and edit are disabled (hard-blocked; calls will fail)
-- bash is restricted to read-only commands (ls, cat, grep, git status/log/diff, etc.)
+Blocked without exception: redirection (> >>), tee, dd, rm/mv/cp/mkdir, sed -i,
+installs/builds, git mutations (add/commit/checkout/reset/stash drop/...), and
+command substitution $(...) / backticks.`;
 
-Answer the user's question directly. If a question requires changing files, say so and suggest exiting ask mode with /ask.`;
+const BANNER_FOOTER = `Never write a file, not even a temporary one.`;
+
+/** Build the banner, adapting the search hint to the active helper tools. */
+export function buildAskBanner(options: AskBannerOptions = {}): string {
+	const helpers = options.helperTools ?? [];
+	const helperLabel = helpers.map((name) => `\`${name}\``).join("/");
+	const helperLine =
+		helpers.length > 0
+			? `\n- search with the ${helperLabel} tools (active during ask mode)`
+			: "";
+	return `${BANNER_HEADER}
+
+If a bash command is rejected, do not retry variants or invent workarounds:
+- read file contents with the \`read\` tool instead of cat/sed tricks${helperLine}
+- fetch a URL with \`curl -s <url>\` instead of wget
+- otherwise tell the user which command is blocked and why
+
+${BANNER_FOOTER}`;
+}
 
 /** Append the ask-mode banner to an existing system prompt. */
-export function appendAskBanner(systemPrompt: string): string {
-	return `${systemPrompt}\n\n${ASK_BANNER}`;
+export function appendAskBanner(
+	systemPrompt: string,
+	options: AskBannerOptions = {},
+): string {
+	return `${systemPrompt}\n\n${buildAskBanner(options)}`;
 }

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

@@ -0,0 +1,35 @@
+/**
+ * Tests for ask-mode rejection messages: each one must point at a next step.
+ */
+import { describe, expect, it } from "vitest";
+import { blockedBashReason, blockedToolReason } from "./reasons.js";
+
+describe("blockedToolReason", () => {
+	it.each(["write", "edit", "powershell"])(
+		"names the exit path for %s",
+		(tool) => {
+			const reason = blockedToolReason(tool);
+			expect(reason).toContain(tool);
+			expect(reason).toContain("/ask");
+		},
+	);
+});
+
+describe("blockedBashReason", () => {
+	it.each([
+		["rm -rf /", "writes to disk"],
+		["cat a > b", "redirection"],
+		["echo $(id)", "command substitution"],
+		["wget https://example.com", "curl -s"],
+		["git commit -m x", "read-only git"],
+		["git grep -O x", "run another program"],
+		["pnpm install", "install/build"],
+		["vim README.md", "allowlist"],
+	] as const)("for %s mentions: %s", (command, needle) => {
+		expect(blockedBashReason(command)).toContain(needle);
+	});
+
+	it("always echoes the blocked command", () => {
+		expect(blockedBashReason("git push")).toContain("Command: git push");
+	});
+});

package/src/features/ask/reasons.ts

@@ -0,0 +1,68 @@
+/**
+ * ask feature — actionable rejection messages.
+ *
+ * The `tool_call` hook's `reason` is delivered to the model as the tool result
+ * (verified against pi 1.2.0: `extensions/runner.js` returns the `{block,
+ * reason}` result unchanged and pi-agent-core's `agent-loop.js` turns it into
+ * `createErrorToolResult(reason)`; both paths are byte-identical to 1.1.0), so it
+ * is the best place to name the nearest allowed alternative and stop the model
+ * from retrying variants of a blocked command.
+ */
+import { classifyBlockedCommand } from "./bash-sandbox.js";
+
+/** Reason for a hard-blocked tool call (write / edit / powershell). */
+export function blockedToolReason(toolName: string): string {
+	if (toolName === "powershell") {
+		return "Ask mode: powershell is disabled — ask mode is read-only. " +
+			"Inspect files with the read/grep/find/ls tools or the read-only bash " +
+			"allowlist; if a command must change something, tell the user and ask " +
+			"them to exit ask mode with /ask.";
+	}
+	return `Ask mode: ${toolName} is disabled — ask mode is read-only. ` +
+		"If a change is needed, explain what to change and ask the user to exit " +
+		"ask mode with /ask.";
+}
+
+/** Reason for a rejected bash command, classified by intent. */
+export function blockedBashReason(command: string): string {
+	const suffix = `\nCommand: ${command}`;
+	switch (classifyBlockedCommand(command)) {
+		case "substitution":
+			return "Ask mode: command substitution — $(...) and backticks — is " +
+				"blocked because it can run arbitrary commands. Run the inner " +
+				"command directly instead." + suffix;
+		case "redirect":
+			return "Ask mode: output redirection is blocked — ask mode cannot " +
+				"write files, not even temporary ones. Use the read/grep/find/ls " +
+				"tools to inspect files instead." + suffix;
+		case "exec":
+			return "Ask mode: this command can run another program (git grep -O, " +
+				"git --ext-diff, find -exec/-ok, fd -x, rg --pre, env CMD). Only " +
+				"read-only operations are allowed; run the underlying read-only " +
+				"command directly instead." + suffix;
+		case "write":
+			return "Ask mode: this command writes to disk (curl -o/-O, wget -O, " +
+				"dd of=, tee, sed -i, git --output, ...). Nothing can be written in " +
+				"ask mode. To read a URL without saving it use `curl -s <url>`; to " +
+				"read files use the `read` tool." + suffix;
+		case "download":
+			return "Ask mode: downloads to disk are blocked. Use `curl -s <url>` " +
+				"or `wget -O - <url>` to read a URL to stdout instead." + suffix;
+		case "git":
+			return "Ask mode: only read-only git commands are allowed (status, " +
+				"log, diff, show, blame, grep, rev-parse, describe, shortlog, " +
+				"reflog show, stash list, tag -l, cat-file). To change the " +
+				"repository, ask the user to exit ask mode with /ask." + suffix;
+		case "install":
+			return "Ask mode: install/build commands are blocked. Read-only " +
+				"package queries (npm view, pnpm view, pip show/list) are allowed; " +
+				"to actually install or build, ask the user to exit ask mode with " +
+				"/ask." + suffix;
+		default:
+			return "Ask mode: this command is not on the read-only allowlist " +
+				"(or is classified as destructive), so it was not executed — it may " +
+				"itself be read-only. Do not retry variants: use the " +
+				"read/grep/find/ls tools, a recognised read-only bash command, or " +
+				"tell the user the command is blocked." + suffix;
+	}
+}

package/src/features/autostart/index.ts

@@ -16,7 +16,8 @@
  * Dispatch uses `sendUserMessage(cmd, { expandPromptTemplates: true })` —
  * that flag is what routes "/cmd args" through _tryExecuteExtensionCommand
  * instead of the model prompt path. The wrapper defaults it to false
- * (verified against pi 1.1.0 agent-session.js; see AGENTS.md host-compat
+ * (each byte-identical across every published version of the supported
+ * window, 0.99.0 → 1.2.0; see AGENTS.md host-compat
  * discipline for the version matrix).
  *
  * Only extension commands can run this way. Built-in commands (/compact,

package/src/features/compact/index.ts

@@ -11,8 +11,11 @@
  *    before running its own compaction
  *  - prompts, message assembly, split-turn handling, output budgets, and the
  *    summary file-list tail are verbatim pi built-in behavior (copied from
- *    0.87.1, verified unchanged through 1.1.0) — only the executing model
- *    differs
+ *    0.87.1, byte-identical across every published version of the supported
+ *    window, 0.99.0 → 1.2.0) — only the executing model differs. The one
+ *    exception is `serializeConversation`, which is imported from the host
+ *    instead of mirrored, so it tracks whatever the running host does
+ *    (1.2.0 stopped feeding assistant thinking into the request).
  *  - lossless fallback: unset config, unavailable model, empty/failed
  *    summary, or user abort → return undefined and pi's default compaction
  *    (session model) runs untouched. The extension can never make
@@ -116,7 +119,7 @@ async function completeSummary(
 }
 
 /**
- * pi's output-budget formula (compaction.js, 0.87.1 → 1.1.0 unchanged): a
+ * pi's output-budget formula (compaction.js, 0.87.1 → 1.2.0 unchanged): a
  * fraction of reserveTokens clamped by the model's own output cap.
  */
 function summarizationBudget(
@@ -132,7 +135,8 @@ function summarizationBudget(
 
 /**
  * Run the full compaction summarization with the configured model,
- * replicating pi's compact() (0.87.1, verified unchanged through 1.1.0):
+ * replicating pi's compact() (0.87.1, byte-identical across the supported
+ * 0.99.0 → 1.2.0 window):
  * history summary (first-connection or iterative-update prompt, custom
  * focus appended), plus a separate turn-prefix checkpoint when the cut point
  * splits a turn, merged into one summary with the file-list tail. Returns

package/src/features/compact/prompt.ts

@@ -5,11 +5,15 @@
  * compaction (dist/core/compaction/compaction.js and utils.js) so that
  * summaries produced by the configured compact model are formatted exactly
  * like pi's own compaction output. Only the executing model differs.
- * Verified byte-identical against pi 1.1.0 (0.88–0.98 were never published;
- * the only 0.87.1→1.1.0 change there is a combineUsage refactor into a
- * shared core/usage-totals.js, no prompt or budget change). 0.87.0 shipped a
- * different split-turn prefix prompt; the text mirrored here is 0.87.1+'s
- * fix, which is also what 0.87.0 hosts get — intentional.
+ * Verified byte-identical against every published version of the supported
+ * window (0.99.0 → 1.2.0): dist/core/compaction/compaction.js and
+ * core/usage-totals.js are unchanged files across that span, and the only
+ * utils.js change (1.2.0 dropping assistant thinking from
+ * serializeConversation) does not touch the strings mirrored here — that
+ * serializer is imported from the host, not mirrored. 0.87.0 shipped a
+ * different split-turn prefix prompt; the text mirrored here is 0.87.1's
+ * fix, and the mirror is the only variant any supported host gets —
+ * intentional.
  *
  * Update these strings whenever pi changes its built-in prompts (diff
  * dist/core/compaction/compaction.js between versions).
@@ -198,7 +202,8 @@ export function formatFileOperations(
 
 /**
  * Combine two provider usage records field-wise (pi 0.87.1 compaction.js
- * combineUsage, moved verbatim to core/usage-totals.js in 0.99.0): used when
+ * combineUsage, moved verbatim to core/usage-totals.js in 0.99.0 and
+ * unchanged through 1.2.0): used when
  * a split turn produces two summarization calls.
  */
 export function combineUsage<T extends UsageLike>(first: T, second: T): T {

package/src/features/favorites/constants.ts

@@ -8,7 +8,8 @@
  * bindings — only the cycle semantics change (patch-cycle.ts), so no
  * keybinding conflicts arise.
  *
- * Verified against pi 0.87.0 / 0.99.0 / 1.0.4 / 1.1.0 keybinding
+ * Verified against every published version of the supported window
+ * (0.99.0 → 1.2.0) keybinding
  * tables + pi-tui input dispatch on WSL2 + Windows Terminal; re-run
  * `pnpm check:keybindings` after every host upgrade before trusting this.
  */
@@ -29,11 +30,11 @@ export const FAVORITES_FILE = "pi-toolkits-favorites.json";
  * Windows/WSL `tui.altScreen.search` resolves to ctrl+f, and
  * `TuiAltScreen.handleViewportInput()` checks it before
  * `shouldDeferViewportInputToOverlay()`, so the keystroke opens transcript
- * search and the selector never sees it (verified in pi-tui 1.1.0
+ * search and the selector never sees it (verified in pi-tui 1.2.0
  * `dist/tui-alt-screen.js`: the search check is the first key branch and
  * returns `{ consume: true }` unconditionally).
  *
- * Why ctrl+alt+f was discarded: clean at the pi layer across 0.87–1.1 (only
+ * Why ctrl+alt+f was discarded: clean at the pi layer across 0.99–1.2 (only
  * ctrl+alt+] is taken from that family) and byte-distinguishable without
  * kitty — but grabbed at the OS/app layer on the author's machine by a
  * Windows screenshot tool, so it never reached the terminal. Lesson: a key

package/src/features/favorites/patch-cycle.ts

@@ -14,7 +14,8 @@
  *  - with exactly one favorite, already on it → undefined (stock "only one
  *    model available" feedback); otherwise jump to it
  *  - the apply logic mirrors pi's _cycleScopedModel/_cycleAvailableModel
- *    (byte-identical across every published version in 0.87.0 → 1.1.0:
+ *    (byte-identical across every published version in the supported window
+ *    0.99.0 → 1.2.0:
  *    state swap, session persistence, default-model persistence only when
  *    `options.persist` is set, thinking-level re-clamp, model_select emit
  *    with source "cycle")
@@ -30,9 +31,9 @@ import { getFavoritesStore, modelKey } from "./store.js";
 
 /**
  * pi's `Model<any>` — the exact type of `ModelCycleResult.model`
- * (pi-coding-agent 0.87–1.1; the field is unchanged across that span).
+ * (pi-coding-agent 0.99–1.2; the field is unchanged across that span).
  * Derived here instead of importing `Model` from @earendil-works/pi-ai,
- * whose index.d.ts (0.87 through 1.1.0 alike) re-exports it via an
+ * whose index.d.ts (0.99 through 1.2.0 alike) re-exports it via an
  * extensioned `"./types.ts"` specifier that not every TS resolver substitutes
  * to `types.d.ts` (tsc 5.9 bundler does; other tsserver builds don't).
  */
@@ -56,7 +57,7 @@ interface CycleSessionInternals {
 		setDefaultModelAndProvider(provider: string, id: string): void;
 	};
 	/**
-	 * pi 0.87: keeps a persisted default usable when cycling inside a
+	 * pi 0.99–1.2: keeps a persisted default usable when cycling inside a
 	 * non-empty --models scope.
 	 */
 	_addPersistedDefaultToNonEmptyScope(model: unknown): void;
@@ -97,7 +98,7 @@ function nextCycleIndex(
 		: (currentIndex - 1 + len) % len;
 }
 
-/** Options accepted by pi 0.87's cycleModel (persist gates default-model persistence). */
+/** Options accepted by pi's cycleModel (persist gates default-model persistence). */
 interface CycleOptions {
 	persist?: boolean;
 }
@@ -139,7 +140,7 @@ export function applyCyclePatch(): boolean {
 			return original.call(this, direction, options);
 		}
 
-		// Same source and availability filtering as pi 0.87's stock cycling.
+		// Same source and availability filtering as pi's stock cycling (0.99–1.2).
 		const scoped = this._scopedModels.length > 0;
 		let candidates: CycleCandidate[];
 		if (scoped) {
@@ -184,7 +185,7 @@ export function applyCyclePatch(): boolean {
 				: this._getThinkingLevelForModelSwitch();
 		this.agent.state.model = next.model;
 		this.sessionManager.appendModelChange(next.model.provider, next.model.id);
-		// pi 0.87: only persist the default model when the caller asked for it.
+		// pi 0.99–1.2: only persist the default model when the caller asked for it.
 		if (options.persist) {
 			this.settingsManager.setDefaultModelAndProvider(
 				next.model.provider,

package/src/features/favorites/patch-selector.ts

@@ -22,7 +22,7 @@
  * keeps loading and ctrl+p falls back to stock behavior. The prototype
  * shape touched here (handleInput/updateList/filterModels and the instance
  * fields below) is byte-identical across every published version in
- * pi 0.87.0 → 1.1.0.
+ * pi 0.99.0 → 1.2.0 (and 0.87.0 → 1.1.0 before the floor moved).
  */
 import {
 	ModelSelectorComponent,
@@ -61,7 +61,7 @@ interface SelectorPatchTarget {
 	handleInput(keyData: string): void;
 	updateList(): void;
 	filterModels(query: string): void;
-	/** pi 0.87: default-model badge source. */
+	/** pi 0.99–1.2: default-model badge source. */
 	isDefaultModel(model: ModelRef): boolean;
 	listContainer: ListContainerLike;
 	searchInput: SearchInputLike;
@@ -116,7 +116,7 @@ let patched = false;
 export function applyModelSelectorPatches(): boolean {
 	if (patched) return true;
 	// SAFETY: ModelSelectorComponent's members are TS-private (compile-time
-	// only); the structural view matches pi 0.87–1.1's prototype shape
+	// only); the structural view matches pi 0.99–1.2's prototype shape
 	// (byte-identical across that span) and every touched method is
 	// existence-checked below before any patching happens.
 	const proto =
@@ -155,7 +155,7 @@ export function applyModelSelectorPatches(): boolean {
 	};
 
 	// ── 2. List rendering: hint row + bold bright yellow favorites ────────
-	// Replicates the built-in updateList layout (pi 0.87–1.1: fixed-width cursor
+	// Replicates the built-in updateList layout (pi 0.99–1.2: fixed-width cursor
 	// and ✓ current-marker columns, provider badge, `· default` badge, scroll
 	// indicator, empty/error states, refresh status, Model Name footer) with
 	// one change: favorited model ids render in the favorite style.

package/src/features/stash/stash.ts

@@ -21,7 +21,7 @@ import type { KeyId } from "@earendil-works/pi-tui";
 /**
  * Stash hotkey.
  *
- * Compatibility rationale (verified against pi 0.87.0–1.1.0 keybindings, live
+ * Compatibility rationale (verified against pi 0.99.0–1.2.0 keybindings, live
  * matchesKey probes and terminal/OS behavior):
  *  - pi: no default binding for ctrl+alt+<letter> (only ctrl+alt+] is taken);
  *    extension shortcuts dispatch first while the editor is focused

package/src/lib/model-config.ts

@@ -4,8 +4,8 @@
  * (review, compact-model — favorites keeps its own store-local key logic).
  *
  * Types are derived from pi-coding-agent's own exports (ModelRegistry)
- * rather than imported from @earendil-works/pi-ai: pi-ai's index.d.ts (0.87
- * through 1.1.0 alike) re-exports `Model`/`Api` via extensioned
+ * rather than imported from @earendil-works/pi-ai: pi-ai's index.d.ts (0.99
+ * through 1.2.0 alike) re-exports `Model`/`Api` via extensioned
  * `./types.ts` specifiers, which tsc 5.9 bundler resolution substitutes to
  * `.d.ts` but some tsserver builds do not. Deriving from ModelRegistry keeps
  * every resolver in agreement with the exact type

package/src/lib/model-picker.ts

@@ -9,7 +9,7 @@
  *
  * The component is driven through a small ModelRuntime facade backed by
  * ctx.modelRegistry (pi's extension-facing wrapper). SAFETY: verified
- * against pi 0.87.0–1.1.0 dist (modes/interactive/components/model-selector.js +
+ * against pi 0.99.0–1.2.0 dist (modes/interactive/components/model-selector.js +
  * model-catalog-refresh.js — byte-identical across that span) — the
  * component only calls getAvailableSnapshot, getModel, getError and refresh
  * on modelRuntime, and ModelRegistry provides exactly those
@@ -42,7 +42,7 @@ function modelRuntimeFacade(ctx: ExtensionContext): ModelRuntime {
 		refresh: (options?: { signal?: AbortSignal }) =>
 			ctx.modelRegistry.refresh(options),
 	};
-	// SAFETY: the selector only touches the four members above (pi 0.87–1.1
+	// SAFETY: the selector only touches the four members above (pi 0.99–1.2
 	// model-selector.js); everything else on ModelRuntime is never reached
 	// from this component.
 	return facade as unknown as ModelRuntime;

package/src/lib/tools.ts

@@ -8,9 +8,11 @@ export function snapshotActiveTools(pi: ExtensionAPI): string[] {
 	return [...pi.getActiveTools()];
 }
 
-/** Restore a previously snapshotted tool set. No-op when the snapshot is empty. */
-export function restoreActiveTools(pi: ExtensionAPI, snapshot: string[]): void {
-	if (snapshot.length === 0) return;
+/** Restore a previously snapshotted tool set (an empty snapshot = no tools). */
+export function restoreActiveTools(
+	pi: ExtensionAPI,
+	snapshot: readonly string[],
+): void {
 	pi.setActiveTools([...snapshot]);
 }