@andares/pi-toolkits 0.7.2 → 0.8.0

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.3.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.2.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, 1.0.0 → 1.3.0; see AGENTS.md host-compat
  * discipline for the version matrix).
  *
  * Only extension commands can run this way. Built-in commands (/compact,