@andares/pi-toolkits 0.9.5 → 0.9.7

package/src/features/ask/index.ts

@@ -1,10 +1,19 @@
 /**
- * ask feature — read-only Q&A mode.
+ * ask feature — read-only consult mode.
  *
- * Design notes (see PLAN.md):
- *  - 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.
+ * Design notes (see PLAN.md and AGENTS.md):
+ *  - Project writes stay impossible: write/edit/powershell are removed from the
+ *    active tool set via pi.setActiveTools(), and pi's runtime rejects calls to
+ *    non-active tools ("Tool not found"). A gate blocks them again as defence in
+ *    depth, in case anything re-enables them.
+ *  - The mode is not "no writes at all": a consult session may need somewhere to
+ *    keep an outline or a checklist, and confiscating temp files made the mode
+ *    hostile enough that it went unused. One write channel is allowed —
+ *    `scratchpad`, which takes a relative note name and can only reach
+ *    `<os.tmpdir()>/pi-ask/<session>`. It is registered `defaultActive: false`
+ *    and activated for the duration, so no path ever arrives from the model and
+ *    the bash sandbox needs no write allowance. When no writable temp dir
+ *    exists, the tool stays inactive and ask mode degrades to pure read-only.
  *  - 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
@@ -13,14 +22,20 @@
  *    replacing it: each feature owns its own concern and the call is blocked
  *    when either objects.
  *  - Mode banner appended to the system prompt via before_agent_start
- *    chained systemPrompt (see prompt.ts), listing blocked -> alternative.
+ *    (see prompt.ts). It is short on purpose: a mode line, the scratch rule, and
+ *    the exit path. Everything else is learned from tool declarations and from
+ *    rejection reasons, which cost tokens only when they apply.
  */
 import type {
 	ExtensionAPI,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import type { GateHub } from "../../lib/gates.js";
+// The jailed-tool registry lives here too: ask marks `scratchpad` while the mode
+// is active so the boundary gate (`permission`) knows it has no path to judge.
 import {
+	clearJailedTool,
+	markJailedTool,
 	restoreActiveTools,
 	snapshotActiveTools,
 	withoutTools,
@@ -28,17 +43,76 @@ import {
 import {
 	ASK_BLOCKED_TOOLS,
 	ASK_READ_ONLY_HELPERS,
+	ASK_SCRATCH_TOOL,
 	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";
+import { createScratchStore, type ScratchStore } from "./scratch.js";
+import { registerScratchTool } from "./scratch-tool.js";
 
-export function registerAsk(pi: ExtensionAPI, gates: GateHub): void {
+export interface AskOptions {
+	/**
+	 * Base directory for the scratch space. Default: the OS temp dir. Tests
+	 * inject a fresh directory so they never touch the real temp space.
+	 */
+	readonly scratchBaseDir?: string;
+}
+
+/** Session id, or a process-scoped fallback when the host exposes none. */
+function sessionIdOf(ctx: ExtensionContext): string {
+	try {
+		return ctx.sessionManager.getSessionId();
+	} catch {
+		return `pid-${process.pid}`;
+	}
+}
+
+export function registerAsk(
+	pi: ExtensionAPI,
+	gates: GateHub,
+	options: AskOptions = {},
+): void {
 	let enabled = false;
 	/** Active tools before ask mode was entered (for exact restore on exit). */
 	let snapshot: string[] = [];
+	/** Scratch space of this session, or undefined when unavailable. */
+	let scratch: ScratchStore | undefined;
+	/** Session id the scratch store is bound to (rebound on session switch). */
+	let scratchSessionId: string | undefined;
+
+	// The tool is registered up front but stays inactive: activating it on entry
+	// is what puts its declaration (and guidelines) into the request.
+	registerScratchTool(pi, () => scratch);
+
+	/**
+	 * Create the scratch store for `sessionId` and bind the state. On failure the
+	 * mode runs degraded (no scratch tool), with a warning.
+	 */
+	function bindScratch(ctx: ExtensionContext, sessionId: string): void {
+		try {
+			scratch = createScratchStore({
+				sessionId,
+				baseDir: options.scratchBaseDir,
+			});
+			scratchSessionId = sessionId;
+			// Self-jailed: permission has no boundary to judge for this tool.
+			markJailedTool(ASK_SCRATCH_TOOL);
+		} catch (error) {
+			// No usable temp dir (read-only TMPDIR, locked-down container, …): fall
+			// back to the fully read-only mode rather than half-opening one.
+			scratch = undefined;
+			scratchSessionId = undefined;
+			clearJailedTool(ASK_SCRATCH_TOOL);
+			const reason = error instanceof Error ? error.message : String(error);
+			ctx.ui.notify(
+				`Ask mode: no scratch space (${reason}) — fully read-only.`,
+				"warning",
+			);
+		}
+	}
 
 	/** Gray footer status while ask mode is active; cleared on exit. */
 	function updateStatus(ctx: ExtensionContext): void {
@@ -48,30 +122,42 @@ export function registerAsk(pi: ExtensionAPI, gates: GateHub): 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));
+	/**
+	 * The tool set ask mode pins: entry snapshot minus the confiscated tools, plus
+	 * the read-only helpers and the scratch tool.
+	 *
+	 * Recomputed (not just applied on entry) because `setActiveTools()` during
+	 * `session_start` — which is how autostart enters the mode — is overwritten
+	 * by the host's loadout preparation for the first run: the mode banner still
+	 * appears, but the run would not declare `scratchpad` (or the helpers).
+	 * Re-asserting in `before_agent_start` makes the mode's tool surface
+	 * deterministic for every run.
+	 */
+	function askToolSet(): string[] {
+		const registered = new Set(pi.getAllTools().map((tool) => tool.name));
+		const helpers = ASK_READ_ONLY_HELPERS.filter(
+			(name) => registered.has(name) && !snapshot.includes(name),
+		);
+		const tools = [...withoutTools(snapshot, ASK_BLOCKED_TOOLS), ...helpers];
+		if (scratch !== undefined && registered.has(ASK_SCRATCH_TOOL)) {
+			tools.push(ASK_SCRATCH_TOOL);
+		}
+		return tools;
 	}
 
+	// Synchronous on purpose: creating the scratch store is sync (see scratch.ts),
+	// so a `/ask` dispatched from `session_start` completes before the first run.
 	function enter(ctx: ExtensionContext): void {
 		if (enabled) return;
 		enabled = true;
 		snapshot = snapshotActiveTools(pi);
-		// 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,
-		]);
+		bindScratch(ctx, sessionIdOf(ctx));
+		pi.setActiveTools(askToolSet());
 		updateStatus(ctx);
 		ctx.ui.notify(
-			"Ask mode ON — read-only (write/edit/powershell disabled, bash sandboxed). /ask to exit.",
+			scratch === undefined
+				? "Ask mode ON — read-only, no scratch space. /ask to exit."
+				: `Ask mode ON — read-only; notes go to ${scratch.root}. /ask to exit.`,
 			"info",
 		);
 	}
@@ -79,6 +165,9 @@ export function registerAsk(pi: ExtensionAPI, gates: GateHub): void {
 	function exit(ctx: ExtensionContext): void {
 		if (!enabled) return;
 		enabled = false;
+		clearJailedTool(ASK_SCRATCH_TOOL);
+		scratch = undefined;
+		scratchSessionId = undefined;
 		restoreActiveTools(pi, snapshot);
 		snapshot = [];
 		updateStatus(ctx);
@@ -94,16 +183,36 @@ export function registerAsk(pi: ExtensionAPI, gates: GateHub): void {
 	}
 
 	pi.registerCommand("ask", {
-		description: "Toggle ask mode (read-only Q&A)",
+		description: "Toggle ask mode (consult mode: no project writes, scratch notes allowed)",
 		handler: async (_args, ctx) => {
 			toggle(ctx);
 		},
 	});
 
+	// The scratch space is per session: an in-process session switch (/new,
+	// /resume, fork) while the mode is on rebinds it to the new session id, so
+	// notes do not keep landing in the previous session's directory. A repeated
+	// emission for the same session (startup rebind) is a no-op.
+	pi.on("session_start", (_event, ctx) => {
+		if (!enabled) return;
+		const sessionId = sessionIdOf(ctx);
+		if (sessionId === scratchSessionId) return;
+		bindScratch(ctx, sessionId);
+		pi.setActiveTools(askToolSet());
+		if (scratch !== undefined) {
+			ctx.ui.notify(
+				`Ask mode: notes now go to ${scratch.root}.`,
+				"info",
+			);
+		}
+	});
+
 	// Defense-in-depth gate while ask mode is active:
 	//  - 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.
+	//    Scratch notes are written by the `scratchpad` tool, not by bash, so the
+	//    sandbox needs no write allowance and no path analysis.
 	// The rejection `reason` reaches the model as the tool result, so it names
 	// the nearest allowed alternative (see reasons.ts).
 	//
@@ -121,7 +230,9 @@ export function registerAsk(pi: ExtensionAPI, gates: GateHub): void {
 			if (ASK_BLOCKED_TOOLS.has(event.toolName)) {
 				return {
 					kind: "block",
-					reason: blockedToolReason(event.toolName),
+					reason: blockedToolReason(event.toolName, {
+						scratch: scratch !== undefined,
+					}),
 				};
 			}
 
@@ -129,7 +240,12 @@ export function registerAsk(pi: ExtensionAPI, gates: GateHub): void {
 				const command =
 					typeof event.input.command === "string" ? event.input.command : "";
 				if (!isReadOnlyCommand(command)) {
-					return { kind: "block", reason: blockedBashReason(command) };
+					return {
+						kind: "block",
+						reason: blockedBashReason(command, {
+							scratch: scratch !== undefined,
+						}),
+					};
 				}
 			}
 			return undefined;
@@ -139,12 +255,20 @@ export function registerAsk(pi: ExtensionAPI, gates: GateHub): void {
 	// Mode banner: chained append to the current system prompt while enabled.
 	pi.on("before_agent_start", (event) => {
 		if (!enabled) return;
+		// Re-assert the mode's tool surface: entering from `session_start` (the
+		// autostart path) is followed by the host's loadout preparation for the
+		// first run, which would otherwise drop the tools set on entry.
+		// Documented contract: a handler may call setActiveTools() and the live
+		// loadout wins over the prepared selection.
+		pi.setActiveTools(askToolSet());
 		// event.systemPrompt is the current (possibly already modified by other
 		// extensions) system prompt — append, don't replace.
 		return {
 			systemPrompt: appendAskBanner(event.systemPrompt, {
-				helperTools: activeHelperTools(),
+				scratch: scratch !== undefined,
 			}),
 		};
 	});
 }
+// (No other write path exists in ask mode: bash is read-only, and the scratch
+// tool is the only thing that can create a file — inside its own temp dir.)

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

@@ -1,45 +1,57 @@
 /**
- * Tests for the ask-mode banner: current state + blocked -> alternative hints.
+ * Tests for the ask-mode banner.
+ *
+ * The banner is part of every request while the mode is on, so the contract has
+ * two halves: it must state the mode, the scratch allowance and the exit path,
+ * and it must stay small and byte-stable (the details live in the tool
+ * declaration and in rejection reasons).
  */
 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");
+	it("states the mode, the scratch channel and the exit path", () => {
+		const banner = buildAskBanner({ scratch: true });
+		expect(banner).toContain("[ASK MODE]");
+		expect(banner).toContain("do not implement");
+		expect(banner).toContain("scratchpad");
+		expect(banner).toContain("is a deliverable");
 		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("drops the scratch line when the session has no scratch space", () => {
+		const banner = buildAskBanner({ scratch: false });
+		expect(banner).not.toContain("scratchpad");
+		expect(banner).toContain("[ASK MODE]");
+		expect(banner).toContain("/ask");
 	});
 
-	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("does not restate the bash allowlist", () => {
+		// The sandbox and reasons.ts own that list; per-request prose was the
+		// bulk of the old banner's ~300 tokens.
+		const banner = buildAskBanner({ scratch: true });
+		expect(banner).not.toContain("rev-parse");
+		expect(banner).not.toContain("sed -n");
+		expect(banner).not.toContain("allowlist");
 	});
 
-	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");
+	it("stays within the token budget", () => {
+		expect(buildAskBanner({ scratch: true }).length).toBeLessThan(500);
+	});
 
-		const withoutHelpers = buildAskBanner();
-		expect(withoutHelpers).not.toContain("active during ask mode");
+	it("is byte-stable for the same state", () => {
+		// Anything per-turn here would break provider prompt caching.
+		expect(buildAskBanner({ scratch: true })).toBe(
+			buildAskBanner({ scratch: true }),
+		);
 	});
 });
 
 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"] });
+		const combined = appendAskBanner(original, { scratch: true });
 		expect(combined.startsWith(original)).toBe(true);
-		expect(combined).toContain("[ASK MODE — read-only]");
+		expect(combined).toContain("[ASK MODE]");
 	});
 });

package/src/features/ask/prompt.ts

@@ -2,54 +2,41 @@
  * 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, 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).
+ * mode is active. It is deliberately short: the system prompt is part of every
+ * request in a run, so the mode line is kept to a few sentences that stay
+ * byte-identical for the whole session (no paths, no timestamps, nothing that
+ * changes per turn) and therefore remains a stable, cacheable prefix. Details
+ * live where they are cheaper and more timely:
+ *
+ *  - the scratchpad tool's own declaration and `promptGuidelines` carry the
+ *    "notes, not deliverables" rule, and only while the tool is active;
+ *  - rejected calls carry the allowed alternative (see reasons.ts), so a model
+ *    that guesses wrong pays for the detail only on the turn it needs it;
+ *  - the read-only bash allowlist is *not* spelled out here. That list used to
+ *    be ~300 tokens per request restating what the sandbox already enforces.
+ *
+ * Do NOT use the removed `systemPromptAppend` field or wholesale systemPrompt
+ * replacement (see PLAN.md).
  */
 
 export interface AskBannerOptions {
-	/** Read-only helper tools active in this session (subset of grep/find/ls). */
-	readonly helperTools?: readonly string[];
+	/** Whether the session has a usable scratch directory (tool active). */
+	readonly scratch?: boolean;
 }
 
-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.
+const BANNER_HEADER = `[ASK MODE] Consult only — read, answer, plan; do not implement.`;
 
-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
+const SCRATCH_LINE = `Throwaway notes go through the \`scratchpad\` tool (a temp directory outside the project); nothing written there is a deliverable.`;
 
-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.`;
+const BANNER_FOOTER = `Any other write is blocked, and a blocked call comes back with the allowed alternative — do not retry variants.
+Exit: the operator runs /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. */
+/** Build the banner, dropping the scratch line when no scratch space exists. */
 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}`;
+	const lines = [BANNER_HEADER];
+	if (options.scratch === true) lines.push(SCRATCH_LINE);
+	lines.push(BANNER_FOOTER);
+	return lines.join("\n");
 }
 
 /** Append the ask-mode banner to an existing system prompt. */

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

@@ -1,18 +1,28 @@
 /**
- * Tests for ask-mode rejection messages: each one must point at a next step.
+ * Tests for ask-mode rejection messages: each one must point at a next step,
+ * and the write-shaped ones must point at `scratchpad` rather than at the exit
+ * command alone.
  */
 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",
+	it.each(["write", "edit"])(
+		"points %s at the scratch tool and the exit path",
 		(tool) => {
 			const reason = blockedToolReason(tool);
 			expect(reason).toContain(tool);
+			expect(reason).toContain("scratchpad");
 			expect(reason).toContain("/ask");
 		},
 	);
+
+	it("names the alternatives for powershell", () => {
+		const reason = blockedToolReason("powershell");
+		expect(reason).toContain("powershell");
+		expect(reason).toContain("scratchpad");
+		expect(reason).toContain("read-only bash");
+	});
 });
 
 describe("blockedBashReason", () => {
@@ -29,7 +39,36 @@ describe("blockedBashReason", () => {
 		expect(blockedBashReason(command)).toContain(needle);
 	});
 
+	it("points write-shaped rejections at the scratch tool", () => {
+		expect(blockedBashReason("cat a > b")).toContain("scratchpad");
+		expect(blockedBashReason("tee out.txt")).toContain("scratchpad");
+	});
+
 	it("always echoes the blocked command", () => {
 		expect(blockedBashReason("git push")).toContain("Command: git push");
 	});
 });
+
+describe("degraded mode (no scratch space)", () => {
+	it("does not point write/edit at the unavailable scratch tool", () => {
+		for (const tool of ["write", "edit", "powershell"]) {
+			const reason = blockedToolReason(tool, { scratch: false });
+			expect(reason).not.toContain("scratchpad");
+			expect(reason).toContain("no scratch space");
+			expect(reason).toContain("/ask");
+		}
+	});
+
+	it("does not point bash rejections at the unavailable scratch tool", () => {
+		for (const command of ["cat a > b", "tee out.txt", "wget https://x", "vim f"]) {
+			expect(blockedBashReason(command, { scratch: false })).not.toContain(
+				"scratchpad",
+			);
+		}
+	});
+
+	it("keeps pointing at scratchpad by default (scratch available)", () => {
+		expect(blockedToolReason("write")).toContain("scratchpad");
+		expect(blockedBashReason("cat a > b")).toContain("scratchpad");
+	});
+});

package/src/features/ask/reasons.ts

@@ -4,27 +4,60 @@
  * 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.
+ * `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. That is also why the mode banner
+ * does not carry the allowlist: this path costs tokens only when it runs.
+ *
+ * When the session has no scratch space (degraded mode), the reasons must not
+ * point at `scratchpad` — the tool is inactive then, and sending the model to
+ * it would cost one wasted call per discovery.
  */
 import { classifyBlockedCommand } from "./bash-sandbox.js";
 
+export interface ReasonOptions {
+	/**
+	 * Whether the scratch tool is available. Default true: only the degraded
+	 * no-temp-dir mode passes false, and only then is the scratch hint omitted.
+	 */
+	readonly scratch?: boolean;
+}
+
+function scratchClause(options: ReasonOptions, fallback: string): string {
+	return options.scratch === false
+		? `${fallback} This session has no scratch space, so notes cannot be saved either.`
+		: `${fallback} For throwaway planning notes use \`scratchpad\`.`;
+}
+
 /** Reason for a hard-blocked tool call (write / edit / powershell). */
-export function blockedToolReason(toolName: string): string {
+export function blockedToolReason(
+	toolName: string,
+	options: ReasonOptions = {},
+): 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: powershell is disabled — ask mode does not change project " +
+			"files. Inspect files with the read/grep/find/ls tools or the read-only " +
+			"bash allowlist. " +
+			scratchClause(options, "") +
+			" If a real change is needed, tell the operator 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.";
+	return (
+		`Ask mode: ${toolName} is disabled — ask mode does not change project ` +
+		"files. " +
+		scratchClause(options, "") +
+		" If the answer needs a real change, explain what to change and ask the " +
+		"operator to exit ask mode with /ask."
+	);
 }
 
 /** Reason for a rejected bash command, classified by intent. */
-export function blockedBashReason(command: string): string {
+export function blockedBashReason(
+	command: string,
+	options: ReasonOptions = {},
+): string {
 	const suffix = `\nCommand: ${command}`;
 	switch (classifyBlockedCommand(command)) {
 		case "substitution":
@@ -32,9 +65,12 @@ export function blockedBashReason(command: string): string {
 				"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;
+			return "Ask mode: output redirection is blocked — ask mode does not " +
+				"write project files. " +
+				(options.scratch === false
+					? "This session has no scratch space either; inspect files with the read/grep/find/ls tools."
+					: "Keep throwaway output as a note with `scratchpad` instead, and inspect files with the read/grep/find/ls tools.") +
+				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 " +
@@ -42,27 +78,36 @@ export function blockedBashReason(command: string): string {
 				"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;
+				"dd of=, tee, sed -i, git --output, ...). " +
+				(options.scratch === false
+					? "There is no writable place in this session."
+					: "The only writable place is `scratchpad`, and it is written by the tool, not by bash.") +
+				" 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;
+				"or `wget -O - <url>` to read a URL to stdout instead" +
+				(options.scratch === false ? "." : ", and keep notes with `scratchpad`.") +
+				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;
+				"repository, ask the operator 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 " +
+				"to actually install or build, ask the operator 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;
+				"read/grep/find/ls tools" +
+				(options.scratch === false
+					? ", a recognised read-only bash command, or tell the operator the command is blocked."
+					: ", `scratchpad` for notes, a recognised read-only bash command, or tell the operator the command is blocked.") +
+				suffix;
 	}
 }