feat(shell cards): Shell cards with minimal content and customize selection between default and minimal

docs/gentle-shell.md

@@ -175,6 +175,17 @@ Pick the conversation-card and shell-chrome style in `/gentle:customize` → **C
 - `float` applies to tool, Code and 🌹 cards, Agent result and stale cards, the review preflight reminder, the dev-binary notice, and the Agents, Todos and Status panels. The prompt and fullscreen header/footer use their specialized float chrome described above. The regular-mode one-line Status bar is unchanged.
 - A theme without a tool background, or a card narrower than 10 columns, falls back to `neon`. A malformed `card-style.json` reads as `float` and the panel refuses to overwrite it.
 
+### Card content
+
+Pick how much a collapsed quiet-tool card shows in `/gentle:customize` → **Cards** → **Card content**. The choice is saved in `card-content.json` in the Gentle Pi config home; a missing, malformed, or unreadable file reads as `default`, and a malformed file is never overwritten.
+
+| Level | Collapsed quiet-tool cards |
+|-------|----------------------------|
+| `default` | Result previews, counts, and summaries, as described above. Bash rows keep pi's native drawing. |
+| `minimal` | Only the command row for `read`, `write`, `bash`, `grep`, `find`, `ls`, and `edit`; the expand key still reveals the full result. Failed calls keep their bounded error tail. Bash rows draw as a Gentle card when the host supports `pi.registerToolRenderer`, with the bare command as the title. |
+
+Quiet tool cards redraw immediately after a change; bash rows follow on new calls. Gentle AI cards keep their full card and elapsed time at both levels.
+
 ### Compact Code card
 
 With quiet tools enabled, `codemode` uses the same rounded **Code** card. The collapsed view shows up to eight observed child calls in their original order, including repeats, with Pi's actual status and available nonnegative duration. Additional calls and failures are counted. Error payloads have a separate two-row preview even when their child falls outside the first eight; final output has a three-row physical budget, and a full-output locator remains visible when available.

extensions/gentle-shell.ts

@@ -14,6 +14,7 @@ import { WorktreeChangesView } from "../lib/shell-changes-view.ts";
 import { SessionWorktreeRegistry, resolveSessionWorktree, worktreeGitEnvironment, type WorktreeResolver, type WorktreeIdentity } from "../lib/session-worktree-registry.ts";
 import { CARD_STYLE, CARD_TONE, cardStyle, renderCard, setCardStyle, type Card, type CardTheme } from "../lib/shell-card.ts";
 import { resolveCardStyle, writeCardStyle } from "../lib/card-style-policy.ts";
+import { CARD_CONTENT, resolveCardContent, setCardContent, writeCardContent } from "../lib/card-content-policy.ts";
 import { CommandPalette, commandsKey, type CommandPaletteResult } from "../lib/command-palette.ts";
 import { buildCommandPaletteGroups } from "../lib/command-palette-catalog.ts";
 import { discoverYoloUiAdapter, YOLO_DISPLAY, type YoloDisplay, type YoloUiAdapter } from "../lib/yolo-session-policy.ts";
@@ -1739,6 +1740,10 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 	// preference fills it at startup and again on every session start.
 	const applyCardStyle = () => setCardStyle(resolveCardStyle(animationOptions).style);
 	applyCardStyle();
+	// The Card content preference rides the same kind of slot: the quiet tool
+	// renderers read it live, so the saved level applies from the first render.
+	const applyCardContent = () => setCardContent(resolveCardContent(animationOptions).content);
+	applyCardContent();
 	const reportVim = (ctx: ExtensionContext, result: ReturnType<typeof resolveVimPolicy>) => {
 		const source = result.source === "default" ? "built-in default" : `global file ${result.globalFile}`;
 		const effective = prompt?.effectiveVimPolicy;
@@ -1835,6 +1840,7 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 		registry = new SessionWorktreeRegistry(pi, ctx.sessionManager, ctx.cwd, deps.resolveWorktree);
 		registry.start();
 		applyCardStyle();
+		applyCardContent();
 		if (!ctx.hasUI) return;
 		visualSettings = resolveVisualSettings(animationOptions).settings;
 		if (!overrides.activeProfile) {
@@ -2233,6 +2239,26 @@ export default function gentleShell(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
 				},
 				() => ({ title: `Cards · ${style}`, sample: `${cardStylePreview[style]}${resolveCardStyle(home).malformed ? " · malformed or unreadable file" : ""}` }),
 			);
+			// The content level picks between the quiet tools' result previews
+			// (default) and command-only cards (minimal).
+			const cardContentPreview = {
+				[CARD_CONTENT.DEFAULT]: "≡ read a.ts · result previews + counts · bash rows keep pi's native card",
+				[CARD_CONTENT.MINIMAL]: "≡ read a.ts · command only · ctrl+o expands · bash draws as a Gentle card",
+			};
+			for (const content of Object.values(CARD_CONTENT)) add(
+				() => {
+					const current = resolveCardContent(home);
+					return `Card content: ${content}${current.content === content && !current.malformed ? " (current)" : ""}`;
+				},
+				`Card content: ${content}. Quiet tool cards redraw now; bash rows follow on new calls.`,
+				() => {
+					writeCardContent(content, home);
+					setCardContent(content);
+					renderHost?.requestRender();
+					requestCustomizeRender?.();
+				},
+				() => ({ title: `Cards · content ${content}`, sample: `${cardContentPreview[content]}${resolveCardContent(home).malformed ? " · malformed or unreadable file" : ""}` }),
+			);
 			category = "Sections";
 			for (const key of VISUAL_SECTION_KEYS) add(
 				() => `Section ${key}: ${visual().visibility[key] ? "shown" : "hidden"}`,

extensions/quiet-tools.ts

@@ -12,6 +12,7 @@ import { Text, type Component } from "@earendil-works/pi-tui";
 import { homedir } from "node:os";
 import { isAbsolute } from "node:path";
 import { resolveGentleAiDevBinaryOverride, type GentleAiDevBinaryOverride } from "../lib/gentle-ai-binary.ts";
+import { CARD_CONTENT, cardContent } from "../lib/card-content-policy.ts";
 import { GentleAiElapsedTimingLedger } from "../lib/gentle-ai-elapsed-store.ts";
 import { quietToolsEnabled } from "../lib/quiet-tools-config.ts";
 import { registerCompactCodemode } from "../lib/codemode-renderer.ts";
@@ -56,6 +57,11 @@ const COLLAPSED_COUNT_LABELS: Partial<Record<QuietToolName, string>> = {
 	ls: "entries",
 };
 
+// Cards that show only the command while the Card content preference is
+// minimal: their results stay one expand key away and never add rows to the
+// transcript view.
+const COMMAND_ONLY_TOOLS: ReadonlySet<QuietToolName> = new Set(["read", "bash", "grep", "find", "ls", "edit", "write"]);
+
 const COLLAPSED_TAIL_LINE_LIMIT = 10;
 const PREVIEW_LINE_LIMIT = 3;
 
@@ -486,7 +492,9 @@ function formatToolCall(toolName: QuietToolName, args: Record<string, unknown>,
 		case "bash": {
 			const command = safeText(asString(args.command, "..."));
 			const timeout = typeof args.timeout === "number" ? theme.fg("muted", ` (timeout ${args.timeout}s)`) : "";
-			return `${theme.fg("toolTitle", theme.bold(`bash $ ${command}`))}${timeout}`;
+			// Minimal cards title bash with the bare command; the card glyph supplies the `$` prompt.
+			const title = cardContent() === CARD_CONTENT.MINIMAL ? command : `bash $ ${command}`;
+			return `${theme.fg("toolTitle", theme.bold(title))}${timeout}`;
 		}
 		case "grep": {
 			let text = `${theme.fg("toolTitle", theme.bold("grep"))} ${theme.fg("accent", `/${safeText(asString(args.pattern))}/`)} in ${safeText(shortenPath(args.path) || ".")}`;
@@ -708,7 +716,7 @@ function gentleAiRenderTransition(
 	return { directResult: false };
 }
 
-/** Rendering-only factory; Bash renderers are not attached to production native Bash. */
+/** Rendering-only factory; the default export attaches the Bash renderers to native Bash through pi.registerToolRenderer, so execution and schema stay pi's. */
 export function createQuietToolRenderer(
 	toolName: QuietToolName,
 	resolveOverride: GentleAiDevBinaryOverrideResolver = () => undefined,
@@ -758,6 +766,13 @@ export function createQuietToolRenderer(
 			}
 			const resultTone = toolTone(options.isPartial === true, isError);
 			const carded = (component: () => Component, cacheable = options.isPartial !== true): Component => new ToolCardBody(component, resultTone, theme, cacheable);
+			// Under the minimal Card content preference, every quiet tool draws
+			// the command alone while collapsed; the expand key still reveals
+			// the full result. Failures keep their bounded error tail so a red
+			// card always says why. The default preference keeps the previews.
+			if (COMMAND_ONLY_TOOLS.has(toolName) && !options.expanded && !isError && cardContent() === CARD_CONTENT.MINIMAL) {
+				return carded(() => new Text("", 0, 0));
+			}
 			if (options.isPartial) {
 				if (options.expanded) return carded(() => new Text(`${theme.fg("warning", partialLabel(toolName, text))}\n${theme.fg("muted", text)}`, 0, 0));
 				const visible = lastOutputLines(text, PREVIEW_LINE_LIMIT);
@@ -848,5 +863,15 @@ export default function quietTools(
 	for (const toolName of Object.keys(TOOL_CREATORS) as RegisteredToolName[]) {
 		registerQuietTool(pi, toolName, resolveOverride, () => elapsedTiming);
 	}
+	// Native Bash keeps pi's execution and schema; only its drawing becomes a
+	// Gentle card while the Card content preference is minimal, so quiet bash
+	// rows match the other tools. The resolver API is newer than this
+	// package's pinned pi types, so it is probed structurally; hosts without it
+	// — and the default content preference — keep pi's native bash rendering.
+	const host = pi as typeof pi & { registerToolRenderer?: (resolver: (toolName: string, next: () => unknown) => unknown) => void };
+	if (typeof host.registerToolRenderer === "function") {
+		host.registerToolRenderer((toolName, next) =>
+			toolName === "bash" && cardContent() === CARD_CONTENT.MINIMAL ? createQuietToolRenderer("bash", resolveOverride, () => elapsedTiming) : next());
+	}
 	return registerCompactCodemode(pi);
 }

lib/card-content-policy.ts

@@ -0,0 +1,85 @@
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { gentlePiConfigHome } from "./agent-home.ts";
+
+// The conversation card content level chosen in Gentle → Customize. `default`
+// keeps the quiet tools' result previews; `minimal` draws every quiet tool
+// card as the command alone. A missing file means default, so nobody loses the
+// previews without choosing to; a malformed or unreadable one also reads as
+// default, and the writer refuses
+// to replace it so a hand edit is never lost. There is no environment override.
+export const CARD_CONTENT_SCHEMA = "gentle-pi.card-content/v1";
+const CARD_CONTENT_FILE = "card-content.json";
+
+export const CARD_CONTENT = {
+	DEFAULT: "default",
+	MINIMAL: "minimal",
+} as const;
+
+export type CardContent = (typeof CARD_CONTENT)[keyof typeof CARD_CONTENT];
+
+interface CardContentOptions { gentlePiConfigHome?: string }
+
+export interface CardContentResolution {
+	content: CardContent;
+	source: "global_file" | "default";
+	malformed: boolean;
+	globalFile: string;
+}
+
+function isCardContent(value: unknown): value is CardContent {
+	return value === CARD_CONTENT.DEFAULT || value === CARD_CONTENT.MINIMAL;
+}
+
+export function parseCardContentFile(raw: string): CardContent | undefined {
+	try {
+		const value: unknown = JSON.parse(raw);
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+		if (Object.keys(value).length !== 2 || !("schema" in value) || value.schema !== CARD_CONTENT_SCHEMA || !("content" in value)) return undefined;
+		return isCardContent(value.content) ? value.content : undefined;
+	} catch { return undefined; }
+}
+
+export function resolveCardContent(options: CardContentOptions = {}): CardContentResolution {
+	const globalFile = join(options.gentlePiConfigHome ?? gentlePiConfigHome(), CARD_CONTENT_FILE);
+	try {
+		const content = parseCardContentFile(readFileSync(globalFile, "utf8"));
+		return { content: content ?? CARD_CONTENT.DEFAULT, source: "global_file", malformed: content === undefined, globalFile };
+	} catch (error) {
+		const missing = typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+		return { content: CARD_CONTENT.DEFAULT, source: missing ? "default" : "global_file", malformed: !missing, globalFile };
+	}
+}
+
+export function writeCardContent(content: CardContent, options: CardContentOptions = {}): string {
+	if (!isCardContent(content)) throw new TypeError("Invalid card content");
+	const home = options.gentlePiConfigHome ?? gentlePiConfigHome();
+	const current = resolveCardContent({ gentlePiConfigHome: home });
+	if (current.malformed) throw new Error(`Cannot update malformed or unreadable card content preference: ${current.globalFile}`);
+	const path = current.globalFile;
+	const temporary = `${path}.${randomUUID()}.tmp`;
+	mkdirSync(home, { recursive: true });
+	try {
+		writeFileSync(temporary, `${JSON.stringify({ schema: CARD_CONTENT_SCHEMA, content })}\n`, { flag: "wx", mode: 0o600 });
+		renameSync(temporary, path);
+	} finally {
+		try { unlinkSync(temporary); } catch { /* Rename consumed the temporary file. */ }
+	}
+	return path;
+}
+
+// Pi loads every extension with its own module cache, so the renderers in
+// quiet-tools and the customize command in gentle-shell never share a module
+// instance. The process-wide slot keeps one live content level per process,
+// exactly like the card style slot; an unset slot reads as default.
+const CARD_CONTENT_SLOT = Symbol.for("gentle-pi.card-content");
+const contentState = globalThis as typeof globalThis & { [CARD_CONTENT_SLOT]?: unknown };
+
+export function cardContent(): CardContent {
+	return contentState[CARD_CONTENT_SLOT] === CARD_CONTENT.MINIMAL ? CARD_CONTENT.MINIMAL : CARD_CONTENT.DEFAULT;
+}
+
+export function setCardContent(content: CardContent): void {
+	contentState[CARD_CONTENT_SLOT] = content;
+}

tests/card-content-policy.test.ts

@@ -0,0 +1,68 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { CARD_CONTENT, CARD_CONTENT_SCHEMA, cardContent, parseCardContentFile, resolveCardContent, setCardContent, writeCardContent } from "../lib/card-content-policy.ts";
+
+const home = () => mkdtempSync(join(tmpdir(), "gentle-card-content-"));
+
+test("a missing preference means the default content level", () => {
+	const dir = home();
+	assert.deepEqual(resolveCardContent({ gentlePiConfigHome: dir }), { content: "default", source: "default", malformed: false, globalFile: join(dir, "card-content.json") });
+});
+
+test("the preference round-trips through the atomic writer", () => {
+	const dir = home();
+	const path = writeCardContent(CARD_CONTENT.MINIMAL, { gentlePiConfigHome: dir });
+	assert.equal(path, join(dir, "card-content.json"));
+	assert.deepEqual(JSON.parse(readFileSync(path, "utf8")), { schema: CARD_CONTENT_SCHEMA, content: "minimal" });
+	assert.deepEqual(resolveCardContent({ gentlePiConfigHome: dir }), { content: "minimal", source: "global_file", malformed: false, globalFile: path });
+	writeCardContent(CARD_CONTENT.DEFAULT, { gentlePiConfigHome: dir });
+	assert.equal(resolveCardContent({ gentlePiConfigHome: dir }).content, "default");
+	assert.deepEqual(readdirSync(dir), ["card-content.json"], "no temporary file survives the rename");
+});
+
+test("the writer rejects values outside the content domain", () => {
+	const dir = home();
+	assert.throws(() => writeCardContent("clean" as never, { gentlePiConfigHome: dir }), TypeError);
+	assert.equal(existsSync(join(dir, "card-content.json")), false);
+});
+
+test("invalid or unreadable preference files read as default and are never overwritten", () => {
+	for (const raw of ["", "{", "[]", "null", `{"schema":"${CARD_CONTENT_SCHEMA}","content":"clean"}`, `{"schema":"other/v1","content":"minimal"}`, `{"schema":"${CARD_CONTENT_SCHEMA}","content":"default","extra":1}`]) {
+		assert.equal(parseCardContentFile(raw), undefined, raw);
+		const dir = home();
+		const path = join(dir, "card-content.json");
+		writeFileSync(path, raw);
+		assert.deepEqual(resolveCardContent({ gentlePiConfigHome: dir }), { content: "default", source: "global_file", malformed: true, globalFile: path }, raw);
+		assert.throws(() => writeCardContent(CARD_CONTENT.MINIMAL, { gentlePiConfigHome: dir }), /Cannot update malformed or unreadable card content preference/, raw);
+		assert.equal(readFileSync(path, "utf8"), raw, "the malformed file is preserved");
+	}
+	const dir = home();
+	mkdirSync(join(dir, "card-content.json"));
+	assert.equal(resolveCardContent({ gentlePiConfigHome: dir }).malformed, true, "a directory in its place is unreadable, not missing");
+	if (process.getuid?.() !== 0) {
+		const locked = home();
+		writeCardContent(CARD_CONTENT.MINIMAL, { gentlePiConfigHome: locked });
+		chmodSync(join(locked, "card-content.json"), 0o000);
+		try {
+			assert.deepEqual({ ...resolveCardContent({ gentlePiConfigHome: locked }), globalFile: "" }, { content: "default", source: "global_file", malformed: true, globalFile: "" });
+		} finally {
+			chmodSync(join(locked, "card-content.json"), 0o600);
+		}
+	}
+});
+
+test("the live slot shares one content level per process and an unset slot reads default", (t) => {
+	const slot = Symbol.for("gentle-pi.card-content");
+	const state = globalThis as typeof globalThis & { [slot]?: unknown };
+	const found = state[slot];
+	t.after(() => { state[slot] = found; });
+	delete state[slot];
+	assert.equal(cardContent(), CARD_CONTENT.DEFAULT);
+	setCardContent(CARD_CONTENT.DEFAULT);
+	assert.equal(cardContent(), CARD_CONTENT.DEFAULT);
+	setCardContent(CARD_CONTENT.MINIMAL);
+	assert.equal(cardContent(), CARD_CONTENT.MINIMAL);
+});