@sassywares/pi-extensions 0.3.18 → 0.3.20

package/README.md

@@ -15,6 +15,7 @@ The package is `@sassywares/pi-extensions`; the repo is `sassy-pi-extensions`.
   - [Web search and fetch](#web-search-and-fetch)
   - [Handoff](#handoff)
   - [Subagent](#subagent)
+  - [Modes](#modes)
 - [Configuration](#configuration)
 - [Security](#security)
 - [Provenance](#provenance)
@@ -77,6 +78,7 @@ pi -e ./sassy-pi-extensions
 | **`web-search`** | `web_search`, `web_fetch` | Searches the web via Exa and fetches readable page text with local-address protection. |
 | **`handoff`** | `/handoff <goal>` | Summarizes the session into a continuation prompt and opens a fresh session with it in the editor for you to submit. |
 | **`subagent`** | `subagent` tool | Runs single, parallel, or chained tasks in isolated pi processes and returns compact results. |
+| **`modes`** | `alt+m`, `/ask`, `/work` | Ask mode removes the write tools and runs bash under an OS-level read-only sandbox. Work mode is pi as usual. |
 
 ### Auto-title
 
@@ -134,6 +136,28 @@ Parallel dispatch defaults to two concurrent subagents. A three-worker MiniMax M
 
 A watchdog kills a subagent when it emits no output for two minutes, which catches provider streams that hang after a partial response. Completed runs append one JSON line to `~/.pi/agent/subagent-runs.jsonl` with model, thinking level, wall time, model time, tool time, turns, error turns, retries, token usage, cost, and the watchdog outcome. Use it to compare models instead of reconstructing runs from session files.
 
+### Modes
+
+Two modes, toggled with `alt+m` or `/ask` and `/work`. Ask mode makes it safe to think out loud; work mode is pi as usual.
+
+Ask mode enforces read-only access on two levels:
+
+1. **Toolset.** `edit`, `write`, `codemode`, `subagent`, and any other tool that can change files or run arbitrary code are removed from the model's active toolset, so it never sees them. A `tool_call` gate blocks them anyway, which also covers nested calls made by tools that stay active.
+2. **Sandboxed bash.** `read`, `grep`, `find`, `ls`, `bash`, `web_search`, and `web_fetch` stay available, because searching and reading is how the model answers honestly. Every bash command, including `!` input, is wrapped in an OS-level sandbox that denies filesystem writes:
+   - macOS: `sandbox-exec` with a `deny file-write*` profile.
+   - Linux: `bwrap` with `--ro-bind / /`.
+
+Writes do not fail quietly and they are not matched by pattern. `rm`, `sed -i`, `tee`, `>` redirection, `git checkout`, and a nested `bash -c` all fail at the OS level with `Operation not permitted`, while `git log`, `git diff`, `rg`, and network calls keep working. `/dev` and the temp directory stay writable so ordinary tools behave.
+
+A backend is only trusted after it proves both halves of the contract: reads inside the working directory must succeed **and** a probe write there must fail. A backend that is installed but cannot enforce (for example bubblewrap on a distribution that blocks unprivileged user namespaces) is discarded, and ask mode continues without bash rather than falling back to a command allowlist. The working directory always wins over the temp allowance: if the project itself lives under the temp directory, temp writes are denied too and `/modes` reports `temp dir is read-only`.
+
+`/modes` shows the verdict. While ask mode is active, the footer is replaced by a compact one that draws the badge on the working-directory/session line — `⏸ ask · ro(sandbox-exec)` or `⏸ ask · bash off` — instead of taking a row of its own; other extension statuses keep their line. Leaving ask mode restores pi's native footer.
+
+- `--ask` starts a session in ask mode; the mode persists across resume.
+- `shift+tab` is not used, because pi binds it to the thinking level. To match an editor that uses it for modes, bind `app.thinking.cycle` to something else in `~/.pi/agent/keybindings.json` and add a shortcut there.
+- Ask mode is a guardrail for local changes, not a jail. Network access stays open, so a command can still change remote state if it holds a credential. Use pi's containerized setup when the boundary has to hold against a hostile model.
+- **Windows is unsupported by design.** Ask mode needs an OS-level read-only sandbox that Windows does not offer cheaply, so the extension registers nothing there. `/ask` and `/work` do not exist, and every tool behaves as before.
+
 ## Configuration
 
 | Variable | Default | Effect |
@@ -141,6 +165,8 @@ A watchdog kills a subagent when it emits no output for two minutes, which catch
 | `PI_AUTO_TITLE` | unset | Set to `0` to disable automatic titles. `/title` still works. |
 | `EXA_API_KEY` | unset | Use the direct Exa API instead of the public Exa MCP endpoint. |
 | `PI_AGENTS_DIR` | `~/.pi/agent/agents` | Target directory for `scripts/install-agents.sh`. |
+| `PI_MODES_BASH` | `auto` | Set to `off` to skip backend detection. Ask mode then runs without bash. |
+| `PI_MODES_ASK_TOOLS` | unset | Comma-separated extra tool names to allow in ask mode. |
 | `PI_SUBAGENT_CONCURRENCY` | `2` | Maximum parallel subagent processes. DeepSeek Flash handled 4; MiniMax M3.1 Flash stalled with 3. |
 | `PI_SUBAGENT_IDLE_TIMEOUT_MS` | `120000` | Kill a subagent after this many milliseconds with no stdout/stderr events. Set to `0` to disable. |
 | `PI_SUBAGENT_TELEMETRY` | `~/.pi/agent/subagent-runs.jsonl` | Telemetry JSONL path, or `0`/`off` to disable. |
@@ -153,6 +179,7 @@ Extensions run inside the pi process with the same OS permissions as pi. Review
 - `auto-title` sends a short transcript of the opening turns to the model already selected for the session. Provider terms and data handling apply.
 - `/handoff` sends the conversation and your goal to the current model to generate the continuation prompt.
 - `subagent` starts additional pi processes. Their permissions match the tools allowed by their agent file and the pi process that spawned them.
+- `modes` ask mode denies local filesystem writes through the OS sandbox described above. It does not restrict network access, so a sandboxed command can still change remote state if it can authenticate. Work mode has no restrictions.
 - No credentials are stored by this package. `EXA_API_KEY` is read from the environment at call time.
 
 ## Provenance
@@ -167,6 +194,9 @@ sassy-pi-extensions/
 │   ├── auto-title.ts
 │   ├── handoff.ts
 │   ├── web-search.ts
+│   ├── modes/
+│   │   ├── backends.ts
+│   │   └── index.ts
 │   └── subagent/
 │       ├── agents.ts
 │       └── index.ts

package/extensions/modes/backends.ts

@@ -0,0 +1,201 @@
+/**
+ * Read-only bash backends for ask mode.
+ *
+ * A backend rewrites a shell command so that it runs under an OS-level sandbox
+ * that denies every filesystem write except /dev and the temp directory. There
+ * is deliberately no regex or command-allowlist fallback: a backend either
+ * proves that it blocks a write inside the working directory, or ask mode runs
+ * without bash at all.
+ *
+ * When the working directory itself sits inside the temp directory, the temp
+ * allowance is dropped instead of the working directory one: the repository is
+ * always read-only, at the cost of a read-only temp directory in that case.
+ */
+
+import { existsSync, realpathSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { createLocalBashOperations, type BashOperations } from "@earendil-works/pi-coding-agent";
+
+export type BackendId = "sandbox-exec" | "bwrap";
+
+export interface SandboxBackend {
+	/** Short identifier shown in the status bar. */
+	id: BackendId;
+	/** Rewrite a command so it executes under the read-only sandbox. */
+	wrap: (command: string) => string;
+}
+
+export interface DetectResult {
+	backend?: SandboxBackend;
+	/** Why the backend was accepted or rejected. Shown by `/modes`. */
+	reason: string;
+}
+
+const PROBE_TIMEOUT_SECONDS = 5;
+const PROBE_FILE = ".pi-modes-probe";
+
+/** macOS paths that stay writable. `/private/var/folders` is behind `$TMPDIR`. */
+const MACOS_WRITE_ALLOW = ["/dev", "/private/tmp", "/private/var/folders"];
+
+/** Linux: bind the whole filesystem read-only, then give back /dev and a scratch /tmp. */
+const LINUX_TEMP = "/tmp";
+
+/** POSIX single-quote escaping, so an arbitrary command survives one more shell layer. */
+export function shellQuote(value: string): string {
+	return `'${value.split("'").join(`'\\''`)}'`;
+}
+
+function realPath(value: string): string {
+	try {
+		return realpathSync(value);
+	} catch {
+		return value;
+	}
+}
+
+function isInside(path: string, root: string): boolean {
+	const resolvedPath = realPath(path);
+	const resolvedRoot = realPath(root);
+	const prefix = resolvedRoot.endsWith("/") ? resolvedRoot : `${resolvedRoot}/`;
+	return resolvedPath === resolvedRoot || resolvedPath.startsWith(prefix);
+}
+
+function macProfile(cwd: string): string {
+	const allowed = MACOS_WRITE_ALLOW.filter((root) => !isInside(cwd, root));
+	const lines = ["(version 1)", "(allow default)", "(deny file-write*)"];
+	if (allowed.length > 0) {
+		lines.push("(allow file-write*");
+		allowed.forEach((root, index) => {
+			const close = index === allowed.length - 1 ? ")" : "";
+			lines.push(`  (subpath "${root}")${close}`);
+		});
+	}
+	return lines.join("\n");
+}
+
+function linuxArgs(cwd: string): string[] {
+	const args = ["bwrap", "--ro-bind", "/", "/", "--dev", "/dev", "--proc", "/proc"];
+	// Do not shadow the working directory with a fresh /tmp.
+	if (!isInside(cwd, LINUX_TEMP)) args.push("--tmpfs", LINUX_TEMP);
+	args.push("--setenv", "TMPDIR", LINUX_TEMP, "--die-with-parent", "--");
+	return args;
+}
+
+function createBackend(id: BackendId, cwd: string): SandboxBackend {
+	if (id === "sandbox-exec") {
+		const profile = shellQuote(macProfile(cwd));
+		return {
+			id,
+			wrap: (command) => `sandbox-exec -p ${profile} /bin/bash -c ${shellQuote(command)}`,
+		};
+	}
+
+	const prefix = linuxArgs(cwd).map(shellQuote).join(" ");
+	return {
+		id,
+		wrap: (command) => `${prefix} /bin/bash -c ${shellQuote(command)}`,
+	};
+}
+
+/**
+ * Run a command through a backend using pi's own shell configuration, so the
+ * probe exercises exactly the execution path ask mode will use.
+ */
+export async function runIn(
+	backend: SandboxBackend,
+	command: string,
+	cwd: string,
+	timeoutSeconds = PROBE_TIMEOUT_SECONDS,
+): Promise<{ output: string; exitCode: number | null }> {
+	const operations = createLocalBashOperations();
+	let output = "";
+	try {
+		const { exitCode } = await operations.exec(backend.wrap(command), cwd, {
+			onData: (chunk) => {
+				output += chunk.toString();
+			},
+			timeout: timeoutSeconds,
+		});
+		return { output, exitCode };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { output: `${output}${message}`, exitCode: null };
+	}
+}
+
+/**
+ * Backend operations for `!command` input, which bypasses the `bash` tool and
+ * therefore the `tool_call` handler.
+ */
+export function createWrappedOperations(backend: SandboxBackend): BashOperations {
+	const local = createLocalBashOperations();
+	return {
+		exec: (command, cwd, options) => local.exec(backend.wrap(command), cwd, options),
+	};
+}
+
+/**
+ * Prove both halves of the contract before trusting a backend: reads must
+ * succeed, and a write inside the working directory must fail. A backend that
+ * "exists" but cannot enforce (for example bubblewrap on a distribution that
+ * blocks unprivileged user namespaces) fails here.
+ *
+ * Temp-directory writability is reported but not required, because the working
+ * directory always wins.
+ */
+async function verify(backend: SandboxBackend, cwd: string): Promise<{ ok: boolean; reason: string }> {
+	const read = await runIn(backend, `printf pi-modes-ok && ls ${shellQuote(cwd)} > /dev/null`, cwd);
+	if (read.exitCode !== 0 || !read.output.includes("pi-modes-ok")) {
+		return { ok: false, reason: `${backend.id}: reads do not work (${firstLine(read.output) || `exit ${read.exitCode}`})` };
+	}
+
+	const probePath = join(cwd, PROBE_FILE);
+	const wrote = await runIn(backend, `printf x > ${shellQuote(probePath)}`, cwd);
+	if (wrote.exitCode === 0) {
+		if (existsSync(probePath)) {
+			try {
+				unlinkSync(probePath);
+			} catch {
+				// Best effort: the probe already failed, do not mask the real reason.
+			}
+		}
+		return { ok: false, reason: `${backend.id}: write inside the working directory was allowed` };
+	}
+
+	const tmpProbe = '"${TMPDIR:-/tmp}/pi-modes-probe-$$"';
+	const tmp = await runIn(backend, `printf x > ${tmpProbe} && printf tmp-ok && rm -f ${tmpProbe}`, cwd);
+	const tmpWritable = tmp.exitCode === 0 && tmp.output.includes("tmp-ok");
+
+	const detail = tmpWritable ? "reads work, writes are denied" : "reads work, writes are denied, temp dir is read-only";
+	return { ok: true, reason: `${backend.id}: ${detail}` };
+}
+
+function firstLine(value: string): string {
+	return (value.split("\n").find((line) => line.trim().length > 0) ?? "").trim();
+}
+
+/**
+ * Pick a backend for this platform and verify it. `PI_MODES_BASH=off` skips
+ * detection entirely, which leaves ask mode with no bash.
+ */
+export async function detectBackend(cwd: string): Promise<DetectResult> {
+	if ((process.env.PI_MODES_BASH ?? "auto").toLowerCase() === "off") {
+		return { reason: "bash disabled by PI_MODES_BASH=off" };
+	}
+
+	const candidates: BackendId[] =
+		process.platform === "darwin" ? ["sandbox-exec"] : process.platform === "linux" ? ["bwrap"] : [];
+	if (candidates.length === 0) {
+		return { reason: `no read-only bash backend for ${process.platform}` };
+	}
+
+	const failures: string[] = [];
+	for (const id of candidates) {
+		const backend = createBackend(id, cwd);
+		const verdict = await verify(backend, cwd);
+		if (verdict.ok) return { backend, reason: verdict.reason };
+		failures.push(verdict.reason);
+	}
+
+	return { reason: failures.join("; ") };
+}

package/extensions/modes/footer.ts

@@ -0,0 +1,164 @@
+/**
+ * Ask-mode footer.
+ *
+ * The built-in footer puts every `ctx.ui.setStatus()` entry on its own line
+ * below the token stats, which leaves stale blank space above the model line
+ * and pushes the transcript up by one row. This footer is installed only while
+ * ask mode is active, and draws the mode badge on the working-directory/session
+ * line instead, right-aligned into space that is otherwise empty.
+ *
+ * It is deliberately a subset of pi's footer: working directory, git branch,
+ * session name, token totals, cost, context usage, and model. Any other
+ * extension statuses are kept on their own line.
+ */
+
+import { homedir } from "node:os";
+import { relative, resolve, sep } from "node:path";
+import type { Component } from "@earendil-works/pi-tui";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { ExtensionContext, ReadonlyFooterDataProvider, Theme } from "@earendil-works/pi-coding-agent";
+
+export interface ModeBadge {
+	text: string;
+	tone: "warning" | "error";
+}
+
+interface Usage {
+	input?: number;
+	output?: number;
+	cost?: { total?: number };
+}
+
+interface Totals {
+	input: number;
+	output: number;
+	cost: number;
+}
+
+const EMPTY_TOTALS: Totals = { input: 0, output: 0, cost: 0 };
+
+export function formatTokens(count: number): string {
+	if (count < 1000) return count.toString();
+	if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
+	if (count < 1000000) return `${Math.round(count / 1000)}k`;
+	if (count < 10000000) return `${(count / 1000000).toFixed(1)}M`;
+	return `${Math.round(count / 1000000)}M`;
+}
+
+export function formatCwd(cwd: string, home = homedir()): string {
+	const resolvedCwd = resolve(cwd);
+	const resolvedHome = resolve(home);
+	const delta = relative(resolvedHome, resolvedCwd);
+	const insideHome = delta === "" || (delta !== ".." && !delta.startsWith(`..${sep}`) && !isAbsolutePath(delta));
+	if (!insideHome) return cwd;
+	return delta === "" ? "~" : `~${sep}${delta}`;
+}
+
+function isAbsolutePath(value: string): boolean {
+	return value.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(value);
+}
+
+/** Left text on the left edge, right text on the right edge, one space minimum between. */
+function justify(left: string, right: string, width: number): string {
+	const leftWidth = visibleWidth(left);
+	const rightWidth = visibleWidth(right);
+	if (leftWidth + rightWidth + 1 <= width) {
+		return left + " ".repeat(width - leftWidth - rightWidth) + right;
+	}
+
+	const availableLeft = width - rightWidth - 1;
+	if (availableLeft >= 12) {
+		const shortened = truncateToWidth(left, availableLeft, "…");
+		const shortenedWidth = visibleWidth(shortened);
+		return shortened + " ".repeat(Math.max(0, width - shortenedWidth - rightWidth)) + right;
+	}
+
+	if (rightWidth + 1 <= width) {
+		return " ".repeat(Math.max(0, width - rightWidth)) + right;
+	}
+
+	return truncateToWidth(right, width, "…");
+}
+
+function addUsage(totals: Totals, usage: Usage | undefined): void {
+	if (!usage) return;
+	totals.input += usage.input ?? 0;
+	totals.output += usage.output ?? 0;
+	totals.cost += usage.cost?.total ?? 0;
+}
+
+export function createModesFooter(
+	ctx: ExtensionContext,
+	theme: Theme,
+	footerData: ReadonlyFooterDataProvider,
+	badge: () => ModeBadge,
+): Component & { dispose?(): void } {
+	let cacheKey = "";
+	let cache: Totals = EMPTY_TOTALS;
+
+	function totals(): Totals {
+		const leaf = ctx.sessionManager.getLeafId() ?? "";
+		const entries = ctx.sessionManager.getEntries();
+		const key = `${leaf}:${entries.length}`;
+		if (key === cacheKey) return cache;
+
+		const next: Totals = { input: 0, output: 0, cost: 0 };
+		for (const entry of entries) {
+			const record = entry as { type: string; usage?: Usage; message?: { role?: string; usage?: Usage } };
+			if (record.type === "usage") {
+				addUsage(next, record.usage);
+			} else if (record.type === "message") {
+				addUsage(next, record.message?.usage);
+			}
+		}
+		cacheKey = key;
+		cache = next;
+		return next;
+	}
+
+	function render(width: number): string[] {
+		const model = ctx.model;
+		const branch = footerData.getGitBranch();
+		const sessionName = ctx.sessionManager.getSessionName();
+
+		let place = formatCwd(ctx.sessionManager.getCwd());
+		if (branch) place += ` (${branch})`;
+		if (sessionName) place += ` • ${sessionName}`;
+
+		const current = badge();
+		const lines = [justify(theme.fg("dim", place), theme.fg(current.tone, current.text), width)];
+
+		const used = totals();
+		const stats: string[] = [];
+		if (used.input) stats.push(`↑${formatTokens(used.input)}`);
+		if (used.output) stats.push(`↓${formatTokens(used.output)}`);
+		if (used.cost) stats.push(`$${used.cost.toFixed(3)}`);
+		const context = ctx.getContextUsage();
+		if (context) {
+			const percent = context.percent === null ? "?" : `${context.percent.toFixed(1)}%`;
+			stats.push(`${percent}/${formatTokens(context.contextWindow ?? 0)}`);
+		}
+
+		let modelText = model?.id ?? "no-model";
+		if (model?.reasoning) modelText += ` • ${ctx.thinkingLevel ?? "off"}`;
+		if (stats.length > 0) {
+			lines.push(justify(theme.fg("dim", stats.join(" ")), theme.fg("dim", modelText), width));
+		}
+
+		const statuses = [...footerData.getExtensionStatuses().entries()]
+			.filter(([key]) => key !== "modes")
+			.sort(([a], [b]) => a.localeCompare(b))
+			.map(([, text]) => text.replace(/[\r\n\t]/g, " ").replace(/ +/g, " ").trim())
+			.filter((text) => text.length > 0);
+		if (statuses.length > 0) {
+			lines.push(truncateToWidth(statuses.join(" "), width, "…"));
+		}
+
+		return lines;
+	}
+
+	return {
+		invalidate() {},
+		render,
+	};
+}

package/extensions/modes/index.ts

@@ -0,0 +1,318 @@
+/**
+ * Modes - ask and work
+ *
+ * Ask mode is read-only: the write tools are removed from the model's toolset,
+ * and bash runs under an OS-level sandbox that denies filesystem writes (see
+ * backends.ts). Work mode is pi as usual.
+ *
+ * Toggle with `alt+m`, `/ask`, `/work`, or start in ask mode with `--ask`.
+ *
+ * Configuration:
+ * - PI_MODES_BASH=auto|off   Detect a read-only bash backend, or skip detection.
+ * - PI_MODES_ASK_TOOLS=a,b   Extra tool names to allow in ask mode.
+ *
+ * Windows is intentionally unsupported: no modes are registered there.
+ */
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createWrappedOperations, detectBackend, type SandboxBackend } from "./backends.ts";
+import { createModesFooter, type ModeBadge } from "./footer.ts";
+
+type Mode = "work" | "ask";
+
+/** Tools that may run in ask mode. Everything else is hidden and blocked. */
+const ASK_TOOLS = ["read", "grep", "find", "ls", "bash", "web_search", "web_fetch", "questionnaire"];
+
+const CONTEXT_CUSTOM_TYPE = "modes-ask-context";
+const CONTEXT_MARKER = "[ASK MODE ACTIVE]";
+const STATE_CUSTOM_TYPE = "modes";
+const SHORTCUT = "alt+m";
+
+interface PersistedState {
+	mode?: Mode;
+}
+
+const ASK_PROMPT = `${CONTEXT_MARKER}
+You are in ask mode: reading, searching, and answering only.
+
+Rules:
+- Do not modify files. The edit and write tools are not available.
+- bash runs inside a read-only sandbox. Reading, searching, git history, and network access work; anything that writes fails with a permission error. Do not retry a failed write - report the limitation instead.
+- Answer from evidence: cite file paths with line numbers, and URLs for web results.
+- If a change is needed, describe it precisely and tell the user to switch to work mode (/work or alt+m).`;
+
+export default function modesExtension(pi: ExtensionAPI): void {
+	// Ask mode depends on an OS-level sandbox that Windows does not provide.
+	// Rather than ship a weaker guardrail, the extension does nothing there.
+	if (process.platform === "win32") return;
+
+	let mode: Mode = "work";
+	let backend: SandboxBackend | undefined;
+	let backendReason = "not detected yet";
+	let backendChecked = false;
+	let workTools: string[] | undefined;
+	let footerTui: { requestRender(): void } | undefined;
+	let footerOwned = false;
+	const wrappedCalls = new Set<string>();
+
+	function configuredAskTools(): string[] {
+		const extra = (process.env.PI_MODES_ASK_TOOLS ?? "")
+			.split(",")
+			.map((name) => name.trim())
+			.filter((name) => name.length > 0);
+		return [...new Set([...ASK_TOOLS, ...extra])];
+	}
+
+	/** Ask toolset, restricted to tools that actually exist in this session. */
+	function askToolset(): string[] {
+		const registered = new Set(pi.getAllTools().map((tool) => tool.name));
+		return configuredAskTools().filter((name) => registered.has(name));
+	}
+
+	function persist(): void {
+		pi.appendEntry(STATE_CUSTOM_TYPE, { mode } satisfies PersistedState);
+	}
+
+	function updateStatus(ctx: ExtensionContext): void {
+		ctx.ui.setStatus("modes", undefined);
+
+		if (mode !== "ask") return;
+
+		// In the TUI the badge lives in the footer's first line; other modes have
+		// no footer, so they keep the plain status line.
+		if (ctx.mode === "tui") {
+			footerTui?.requestRender();
+			return;
+		}
+
+		const badge = badgeSpec();
+		ctx.ui.setStatus("modes", ctx.ui.theme.fg(badge.tone, badge.text));
+	}
+
+	function badgeSpec(): ModeBadge {
+		if (backend) return { text: `⏸ ask · ro(${backend.id})`, tone: "warning" };
+		return { text: "⏸ ask · bash off", tone: "error" };
+	}
+
+	/**
+	 * Ask mode replaces the built-in footer so the badge can sit on the
+	 * directory/session line instead of taking a row of its own. Work mode
+	 * restores pi's native footer.
+	 */
+	function installAskFooter(ctx: ExtensionContext): void {
+		if (ctx.mode !== "tui" || footerOwned) return;
+		try {
+			ctx.ui.setFooter((tui, theme, footerData) => {
+				footerTui = tui;
+				const unsubscribe = footerData.onBranchChange(() => tui.requestRender());
+				return {
+					...createModesFooter(ctx, theme, footerData, badgeSpec),
+					dispose() {
+						unsubscribe();
+						footerTui = undefined;
+					},
+				};
+			});
+			footerOwned = true;
+		} catch {
+			// Fall back to the status line rendered by updateStatus().
+			ctx.ui.setFooter(undefined);
+			footerOwned = false;
+			footerTui = undefined;
+		}
+	}
+
+	function removeAskFooter(ctx: ExtensionContext): void {
+		if (ctx.mode !== "tui" || !footerOwned) return;
+		ctx.ui.setFooter(undefined);
+		footerOwned = false;
+		footerTui = undefined;
+	}
+
+	function describe(): string {
+		const lines = [
+			`Mode: ${mode}`,
+			`Read-only bash: ${backend ? backend.id : "unavailable"}`,
+			`Backend check: ${backendReason}`,
+		];
+		if (mode === "ask") {
+			lines.push(`Allowed tools: ${askToolset().join(", ") || "(none)"}`);
+		}
+		lines.push("", "Toggle: alt+m, /ask, /work");
+		return lines.join("\n");
+	}
+
+	/** Detect a backend at most once per session, on first use. */
+	async function ensureBackend(cwd: string): Promise<void> {
+		if (backendChecked) return;
+		backendChecked = true;
+		const detected = await detectBackend(cwd);
+		backend = detected.backend;
+		backendReason = detected.reason;
+	}
+
+	async function setMode(next: Mode, ctx: ExtensionContext): Promise<void> {
+		if (next === mode) {
+			updateStatus(ctx);
+			return;
+		}
+
+		if (next === "ask") {
+			await ensureBackend(ctx.cwd);
+			mode = "ask";
+			workTools = pi.getActiveTools();
+			pi.setActiveTools(askToolset());
+			installAskFooter(ctx);
+			updateStatus(ctx);
+			persist();
+			if (backend) {
+				ctx.ui.notify(`Ask mode: no changes. bash is read-only (${backend.id}).`, "info");
+			} else {
+				ctx.ui.notify(`Ask mode: no changes, and bash is disabled. ${backendReason}`, "warning");
+			}
+			return;
+		}
+
+		mode = "work";
+		pi.setActiveTools(workTools ?? pi.getActiveTools());
+		workTools = undefined;
+		removeAskFooter(ctx);
+		updateStatus(ctx);
+		persist();
+		ctx.ui.notify("Work mode: full access restored.", "info");
+	}
+
+	pi.registerFlag("ask", {
+		description: "Start in ask mode (read-only)",
+		type: "boolean",
+		default: false,
+	});
+
+	pi.registerCommand("ask", {
+		description: "Switch to ask mode (read-only)",
+		handler: async (_args, ctx) => setMode("ask", ctx),
+	});
+
+	pi.registerCommand("work", {
+		description: "Switch to work mode (full access)",
+		handler: async (_args, ctx) => setMode("work", ctx),
+	});
+
+	pi.registerCommand("modes", {
+		description: "Show the current mode and sandbox backend",
+		handler: async (_args, ctx) => ctx.ui.notify(describe(), "info"),
+	});
+
+	pi.registerShortcut(SHORTCUT, {
+		description: "Toggle ask/work mode",
+		handler: async (ctx) => setMode(mode === "ask" ? "work" : "ask", ctx),
+	});
+
+	// Bash is the one tool that survives ask mode, so it is wrapped at the call
+	// site instead of being replaced. Each call id is wrapped once.
+	pi.on("tool_call", async (event) => {
+		if (mode !== "ask") return undefined;
+
+		if (event.toolName === "bash") {
+			const input = event.input as { command?: unknown };
+			if (typeof input.command !== "string") return undefined;
+			if (!backend) {
+				return {
+					block: true,
+					reason:
+						"Ask mode: bash is disabled because no read-only sandbox backend is available. Use /work to leave ask mode.",
+				};
+			}
+			if (wrappedCalls.has(event.toolCallId)) return undefined;
+			wrappedCalls.add(event.toolCallId);
+			if (wrappedCalls.size > 512) wrappedCalls.clear();
+			input.command = backend.wrap(input.command);
+			return undefined;
+		}
+
+		if (configuredAskTools().includes(event.toolName)) return undefined;
+
+		return {
+			block: true,
+			reason: `Ask mode: ${event.toolName} is not available, because it can change files or run arbitrary code. Use /work to leave ask mode.`,
+		};
+	});
+
+	// `!command` bypasses the bash tool and therefore the tool_call handler.
+	pi.on("user_bash", () => {
+		if (mode !== "ask") return undefined;
+		if (!backend) {
+			return {
+				result: {
+					output:
+						"Ask mode: bash is disabled because no read-only sandbox backend is available. Use /work to leave ask mode.",
+					exitCode: 1,
+					cancelled: false,
+					truncated: false,
+				},
+			};
+		}
+		return { operations: createWrappedOperations(backend) };
+	});
+
+	pi.on("before_agent_start", async (event) => {
+		if (mode !== "ask") return undefined;
+		if (event.messageType !== "user") return undefined;
+		return {
+			message: {
+				customType: CONTEXT_CUSTOM_TYPE,
+				content: ASK_PROMPT,
+				display: false,
+			},
+		};
+	});
+
+	// Drop ask-mode context once the session leaves ask mode.
+	pi.on("context", async (event) => {
+		if (mode === "ask") return undefined;
+		return { messages: event.messages.filter((message) => !isAskContext(message)) };
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		const entries = ctx.sessionManager.getEntries();
+		const state = entries
+			.filter(
+				(entry: { type: string; customType?: string }) =>
+					entry.type === "custom" && entry.customType === STATE_CUSTOM_TYPE,
+			)
+			.pop() as { data?: PersistedState } | undefined;
+
+		mode = state?.data?.mode ?? "work";
+		if (pi.getFlag("ask") === true) mode = "ask";
+
+		workTools = undefined;
+		if (mode === "ask") {
+			await ensureBackend(ctx.cwd);
+			workTools = pi.getActiveTools();
+			pi.setActiveTools(askToolset());
+			installAskFooter(ctx);
+		} else {
+			removeAskFooter(ctx);
+		}
+		updateStatus(ctx);
+	});
+}
+
+/** True for the hidden ask-mode prompt and for user messages that carry it. */
+function isAskContext(message: AgentMessage): boolean {
+	const candidate = message as AgentMessage & { customType?: string };
+	if (candidate.customType === CONTEXT_CUSTOM_TYPE) return true;
+	if (candidate.role === "assistant") return false;
+	const content = (candidate as { content?: unknown }).content;
+	if (typeof content === "string") return content.includes(CONTEXT_MARKER);
+	if (!Array.isArray(content)) return false;
+	return content.some(
+		(part) =>
+			!!part &&
+			typeof part === "object" &&
+			(part as { type?: unknown }).type === "text" &&
+			typeof (part as { text?: unknown }).text === "string" &&
+			(part as { text: string }).text.includes(CONTEXT_MARKER),
+	);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sassywares/pi-extensions",
-  "version": "0.3.18",
-  "description": "A zesty power pack for pi: auto-titled sessions, real web access, clean handoffs, and isolated subagents.",
+  "version": "0.3.20",
+  "description": "A zesty power pack for pi: auto-titled sessions, real web access, clean handoffs, isolated subagents, and ask/work modes.",
   "type": "module",
   "license": "MIT",
   "author": "Sassywares",
@@ -20,7 +20,8 @@
     "auto-title",
     "web-search",
     "handoff",
-    "subagent"
+    "subagent",
+    "modes"
   ],
   "files": [
     "extensions",
@@ -35,6 +36,7 @@
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
   "pi": {
@@ -42,7 +44,8 @@
       "./extensions/auto-title.ts",
       "./extensions/web-search.ts",
       "./extensions/handoff.ts",
-      "./extensions/subagent/index.ts"
+      "./extensions/subagent/index.ts",
+      "./extensions/modes/index.ts"
     ]
   }
 }