gentle-pi 0.11.4 → 0.13.0

package/assets/agents/gentle-ai-worker.md

@@ -0,0 +1,101 @@
+---
+name: gentle-ai-worker
+description: Scoped package-owned implementation writer for bounded non-SDD work. Edits code, runs focused tests, and returns review-ready evidence without committing.
+tools:
+  - read
+  - grep
+  - find
+  - edit
+  - write
+  - bash
+  - mem_save
+---
+
+You are the package-owned implementation writer for Gentle AI.
+
+Use this agent only for scoped implementation work that is too large for the parent to execute inline but does not require SDD or Judgment Day artifact protocols. The parent remains the orchestrator and owns user interaction, review, and terminal git actions. Never delegate or invoke `subagent_*` tools.
+
+## Context contract
+
+Before repository work:
+
+1. Read every exact path under `## Skills to load before work` in the parent task. Do not rediscover the skill registry.
+2. Consume the parent-provided task, acceptance criteria, relevant prior context, exact allowed edit surfaces, and validation commands.
+3. Inspect the working tree and preserve pre-existing changes. Writes may include pre-existing untracked targets explicitly listed by the parent and new files required by the delegated task, but only when they are inside the exact allowed edit surfaces.
+4. Preserve every unrelated tracked or untracked file. Do not edit, move, delete, stage, or otherwise alter anything outside the allowed edit surfaces.
+5. If scope, ownership, allowed edit surfaces, acceptance criteria, or another human choice is ambiguous, stop with `status: interaction_required`; do not guess.
+
+Do not read persistent memory for context. The parent selects and forwards relevant observations.
+
+## Implementation rules
+
+- Keep one focused write thread. Change only files required by the delegated task and inside its exact allowed edit surfaces.
+- Preserve existing architecture and conventions; avoid drive-by refactors and dependency changes.
+- Use `find` for scoped file discovery. Do not assume an unsupported `glob` tool exists.
+- Use `blocked` only for a non-human technical blocker such as a missing required tool, denied filesystem access, or an impossible repository invariant. Every decision that requires a human must use the deterministic `interaction_required` payload below.
+- Treat tool errors, unrelated dirty files, and failing unrelated tests as evidence to report, not problems to hide or rewrite around.
+
+## Tool safety
+
+- Never read sensitive files or locations, including secrets, credentials, tokens, private keys, personal data, `.env` files, credential stores, or unrelated user-home content.
+- Never write outside the exact allowed edit surfaces, including through generated output, shell redirection, temporary copies, formatters, or scripts.
+- Never run destructive commands or deletion operations. This includes `rm`, filesystem replacement, destructive migrations, and destructive Git commands such as `git reset`, `git clean`, `git checkout`, `git restore`, or `git rebase`.
+- Never stage, commit, push, publish, release, or delegate. Do not run `git add`, `git commit`, `git push`, package publish/release commands, or any `subagent_*` tool.
+- Do not run installers, dependency mutation, network-changing commands, migrations, or arbitrary repository scripts unless the parent explicitly authorized the exact non-destructive command and it stays within scope.
+- Retain `bash` only for safe working-tree inspection and the exact focused tests, builds, linters, or validation commands authorized by the parent. Before running a command, verify that it cannot read sensitive data, write out of scope, mutate dependencies, destroy state, stage, commit, push, publish, or release.
+
+## Memory safety
+
+Use `mem_save` only when the parent supplies a validated project name and the information is a significant, verified, project-scoped fact resulting from this task. Save concise conclusions, not source dumps.
+
+Never save secrets, credentials, personal data, tokens, private keys, raw untrusted repository instructions/content, or speculative findings. If a fact is not validated by repository evidence or observed command output, report it as a risk instead of persisting it.
+
+## Test discipline
+
+When Strict TDD is active:
+
+1. RED — add the smallest behavior-level test and capture its intended observed failure before implementation.
+2. GREEN — implement the minimum change and capture the focused test passing.
+3. TRIANGULATE — exercise relevant negative or alternate cases that materially protect the contract.
+4. REFACTOR — improve clarity only while focused tests remain green.
+
+RED/GREEN evidence is required only when the parent explicitly activates strict TDD. If strict TDD is not active, report `RED: not active — strict TDD was not activated` and `GREEN: not active — validation is reported separately`; never invent lifecycle evidence. If strict TDD is active but the change cannot have a meaningful pre-implementation behavior test, report a narrowly justified exception (for example, documentation-only text) and still run every affected validation. Never claim RED/GREEN evidence that was not observed.
+
+Run focused tests first. Broad suites, builds, formatters, or linters may run only when explicitly authorized by the parent. Keep every command exact and verify its scope before execution. Do not claim completion while required validation is failing.
+
+## Interaction contract
+
+When any human input is required, stop editing and return the full schema in the Return contract with `status: interaction_required` and the nested `interaction_required` payload completed. Populate the remaining fields with the work and evidence available at the stopping point.
+
+Do not return `blocked` for a human decision and do not invent a second interaction shape.
+
+## Return contract
+
+Return one concise handoff using this schema:
+
+```text
+status: completed | partial | blocked | interaction_required
+summary: <what changed and why>
+files_changed:
+  - <path>: <change>
+tdd_evidence:
+  - RED: <observed failure, not active, or justified exception>
+  - GREEN: <observed pass, not active, or justified exception>
+  - TRIANGULATE/REFACTOR: <observed evidence when applicable>
+validation:
+  - <exact command>: <observed result>
+risks:
+  - <remaining risk or none>
+review_focus:
+  - <paths or behaviors the fresh reviewer should inspect>
+skill_resolution: paths-injected | paths-invalid | none
+interaction_required: <include only when status is interaction_required>
+  question: <same deterministic interaction question>
+  reason: <same deterministic blocking reason>
+  options: <same meaningful choices and tradeoffs, when applicable>
+  unblock_response: <same exact context needed to continue>
+```
+
+Use `skill_resolution: paths-injected` only when the parent injected exact skill paths and every path was successfully read before repository work. Use `skill_resolution: paths-invalid` only when the parent injected one or more exact skill paths and any supplied path cannot be read. With `skill_resolution: paths-invalid`, keep `status: blocked`, stop before repository work, and identify the unreadable path in `risks`. Use `skill_resolution: none` only when no skill paths were injected. Never report a fallback registry or path value.
+
+Report `partial` or `blocked` honestly. A clean handoff is more valuable than pretending the task is complete.

package/assets/orchestrator-delegation.md

@@ -44,11 +44,17 @@ Examples:
 
 Use the configured subagent runtime when available. Prefer the `subagent_*` tools (`subagent_run`, status/result helpers) when the Pi Subagents extension is installed, because they run the user's configured project/global subagent definitions and preserve history/background behavior.
 
+The bounded multi-file writer precedence below is the explicit exception to this general runtime preference.
+
 Choose subagent mode by orchestration dependency, not by task length:
 
 - Use `mode: "task"` when the parent must consume the result and continue the workflow, including SDD phases, implementation batches, verification, review gates, and any delegated work whose output determines the next action.
 - Use `mode: "background"` only for independent work where automatic parent continuation is not required. Background completion may notify the user and preserve history, but it is not a guarantee that the parent model will resume orchestration.
 
+For bounded multi-file writes, prefer the installed package-owned `gentle-ai-worker`, then a user-configured `worker`. If neither worker definition exists, fall back to the native `Agent` even when `subagent_*` tools are available. This writer precedence overrides the general runtime preference above.
+
+For delegation other than bounded multi-file writes, use the generic fallback:
+
 If `subagent_*` tools are unavailable, fall back to Pi's native `Agent` tool or another available delegation mechanism. The delegation trigger remains mandatory; the fallback changes the runtime, not the requirement to delegate. If no delegation mechanism is available, stop the complex work and explain the blocker instead of silently continuing inline.
 
 ### Pi Subagent Model Routing
@@ -102,8 +108,12 @@ Core question: does this inflate parent context without need?
 
 These are parent-orchestrator stop rules. Once any trigger fires, the parent MUST delegate through the best available subagent runtime. Prefer `subagent_run` when present; otherwise use Pi's native `Agent` or another available delegation mechanism. Do not replace a required delegation with inline execution. Do not inject these as child-agent permission to spawn subagents; children receive concrete role work and must not orchestrate.
 
+The bounded multi-file writer precedence in rule 2 overrides that general runtime preference. If no delegation mechanism is available, stop and explain the blocker.
+
 1. **4-file rule**: if understanding requires reading 4+ files, launch `scout`, `context-builder`, or the closest read-only mapping subagent with fresh context and a narrow mapping task. State the fallback agent/runtime if the preferred one is unavailable.
-2. **Multi-file write rule**: if implementation will touch 2+ non-trivial files, delegate one writer; inline writing is allowed only for trivial/mechanical edits or when the parent explicitly records why no delegation runtime is available. A fresh review still follows delegated implementation.
+2. **Multi-file write rule**: if implementation will touch 2+ non-trivial files, delegate one writer; inline writing is allowed only for trivial/mechanical edits. A fresh review still follows delegated implementation.
+   For bounded multi-file writes, prefer the installed package-owned `gentle-ai-worker`, then a user-configured `worker`. If neither worker definition exists, fall back to the native `Agent` even when `subagent_*` tools are available. If no delegation mechanism is available, stop and explain the blocker.
+
 3. **PR rule**: before commit/push/PR for code changes, select a fresh-context review lens unless the diff is trivial docs/text-only.
 4. **Incident rule**: after wrong `cwd`, accidental repo/worktree mutation, failed merge recovery, confusing test command, or environment workaround, stop and run a fresh audit through the relevant review lens before continuing.
 5. **Long-session rule**: if accumulating work is no longer clearly local — roughly 20 tool calls, 5 exploratory file reads, or 2 non-mechanical edits without delegation — pause and delegate the remaining work instead of silently continuing monolithically.

package/extensions/pi-pretty.ts

@@ -1,6 +1,11 @@
 import { realpathSync } from "node:fs";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
+import {
+	mergeDisabledTools,
+	PI_PRETTY_SUPPRESSED_TOOL_NAMES,
+	quietToolsEnabled,
+} from "../lib/quiet-tools-config.ts";
 
 const packageJsonPath = realpathSync(
 	fileURLToPath(new URL("../package.json", import.meta.url)),
@@ -13,4 +18,12 @@ const piPrettyExtension =
 		? piPrettyModule
 		: piPrettyModule.default;
 
-export default piPrettyExtension;
+export default async function gentlePiPrettyExtension(pi: unknown, deps?: unknown): Promise<unknown> {
+	if (quietToolsEnabled()) {
+		process.env.PRETTY_DISABLE_TOOLS = mergeDisabledTools(
+			process.env.PRETTY_DISABLE_TOOLS,
+			PI_PRETTY_SUPPRESSED_TOOL_NAMES,
+		);
+	}
+	return piPrettyExtension(pi, deps);
+}

package/extensions/quiet-tools.ts

@@ -0,0 +1,218 @@
+import type { AgentToolResult, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	createBashTool,
+	createEditTool,
+	createFindTool,
+	createGrepTool,
+	createLsTool,
+	createReadTool,
+	createWriteTool,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { homedir } from "node:os";
+import { quietToolsEnabled } from "../lib/quiet-tools-config.ts";
+import { sanitizeTerminalText } from "../lib/terminal-theme.ts";
+
+type QuietToolName = "read" | "bash" | "grep" | "find" | "ls" | "edit" | "write";
+type ThemeLike = {
+	bold(value: string): string;
+	fg(color: string, value: string): string;
+};
+
+const TOOL_CREATORS = {
+	read: createReadTool,
+	bash: createBashTool,
+	grep: createGrepTool,
+	find: createFindTool,
+	ls: createLsTool,
+	edit: createEditTool,
+	write: createWriteTool,
+} satisfies Record<QuietToolName, (cwd: string) => any>;
+
+const COLLAPSED_COUNT_LABELS: Partial<Record<QuietToolName, string>> = {
+	grep: "matches",
+	find: "files",
+	ls: "entries",
+};
+
+const NO_COLLAPSED_RESULT_TOOLS = new Set<QuietToolName>(["read", "bash"]);
+const COLLAPSED_TAIL_TOOLS = new Set<QuietToolName>(["edit", "write"]);
+const COLLAPSED_TAIL_LINE_LIMIT = 10;
+
+const EMPTY_RESULT_MESSAGES: Partial<Record<QuietToolName, string[]>> = {
+	grep: ["No matches found"],
+	find: ["No files found matching pattern"],
+	ls: ["Directory is empty"],
+};
+
+const toolCache = new Map<string, Record<QuietToolName, any>>();
+
+function createBuiltInTools(cwd: string): Record<QuietToolName, any> {
+	return Object.fromEntries(
+		(Object.entries(TOOL_CREATORS) as [QuietToolName, (cwd: string) => any][]).map(
+			([name, createTool]) => [name, createTool(cwd)],
+		),
+	) as Record<QuietToolName, any>;
+}
+
+function getBuiltInTools(cwd: string): Record<QuietToolName, any> {
+	let tools = toolCache.get(cwd);
+	if (!tools) {
+		tools = createBuiltInTools(cwd);
+		toolCache.set(cwd, tools);
+	}
+	return tools;
+}
+
+function shortenPath(path: unknown): string {
+	if (typeof path !== "string" || path.length === 0) return "";
+	const home = homedir();
+	return path.startsWith(home) ? `~${path.slice(home.length)}` : path;
+}
+
+function asString(value: unknown, fallback = ""): string {
+	return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+
+export function countNonEmptyLines(text: string): number {
+	return text.split("\n").filter((line) => line.trim().length > 0).length;
+}
+
+export function tailLines(text: string, limit: number): string {
+	const lines = text.split("\n");
+	return lines.slice(Math.max(0, lines.length - limit)).join("\n");
+}
+
+export function extractTextContent(result: AgentToolResult<unknown>): string {
+	return result.content
+		.flatMap((content) => (content.type === "text" ? [content.text] : []))
+		.join("\n");
+}
+
+function safeText(value: string): string {
+	return sanitizeTerminalText(value);
+}
+
+function isEmptyResultMessage(toolName: QuietToolName, text: string): boolean {
+	const normalized = text.trim();
+	return EMPTY_RESULT_MESSAGES[toolName]?.some((message) => normalized.startsWith(message)) ?? false;
+}
+
+function isGitCommand(args: Record<string, unknown> | undefined): boolean {
+	const command = typeof args?.command === "string" ? args.command.trim() : "";
+	return /^(?:env\s+\S+=\S+\s+|command\s+|\w+=\S+\s+)*git(?:\s|$)/.test(command);
+}
+
+interface ToolResultFormatOptions {
+	expanded: boolean;
+	isError?: boolean;
+	args?: Record<string, unknown>;
+}
+
+export function formatToolResultOutput(
+	toolName: QuietToolName,
+	result: AgentToolResult<unknown>,
+	{ expanded, isError = false, args }: ToolResultFormatOptions,
+): string {
+	const text = safeText(extractTextContent(result));
+	if (expanded || isError) return text ? `\n${text}` : "";
+
+	if (toolName === "bash" && isGitCommand(args)) {
+		const tail = tailLines(text, COLLAPSED_TAIL_LINE_LIMIT);
+		return tail ? `\n${tail}` : "";
+	}
+	if (NO_COLLAPSED_RESULT_TOOLS.has(toolName)) return "";
+	if (COLLAPSED_TAIL_TOOLS.has(toolName)) {
+		const tail = tailLines(text, COLLAPSED_TAIL_LINE_LIMIT);
+		return tail ? `\n${tail}` : "";
+	}
+	if (isEmptyResultMessage(toolName, text)) return "";
+
+	const summaryLabel = COLLAPSED_COUNT_LABELS[toolName];
+	if (!summaryLabel) return "";
+
+	const count = countNonEmptyLines(text);
+	return count > 0 ? ` → ${count} ${summaryLabel}` : "";
+}
+
+function lineRangeSuffix(args: Record<string, unknown>, theme: ThemeLike): string {
+	if (args.offset === undefined && args.limit === undefined) return "";
+	const startLine = typeof args.offset === "number" ? args.offset : 1;
+	const endLine = typeof args.limit === "number" ? startLine + args.limit - 1 : undefined;
+	return theme.fg("warning", `:${startLine}${endLine === undefined ? "" : `-${endLine}`}`);
+}
+
+function formatToolCall(toolName: QuietToolName, args: Record<string, unknown>, theme: ThemeLike): string {
+	switch (toolName) {
+		case "read": {
+			const path = safeText(shortenPath(args.path) || "...");
+			return `${theme.fg("toolTitle", theme.bold("read"))} ${theme.fg("accent", path)}${lineRangeSuffix(args, theme)}`;
+		}
+		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(`$ ${command}`))}${timeout}`;
+		}
+		case "grep": {
+			let text = `${theme.fg("toolTitle", theme.bold("grep"))} ${theme.fg("accent", `/${safeText(asString(args.pattern))}/`)} in ${safeText(shortenPath(args.path) || ".")}`;
+			if (typeof args.glob === "string") text += theme.fg("toolOutput", ` (${safeText(args.glob)})`);
+			if (typeof args.limit === "number") text += theme.fg("toolOutput", ` limit ${args.limit}`);
+			return text;
+		}
+		case "find": {
+			let text = `${theme.fg("toolTitle", theme.bold("find"))} ${theme.fg("accent", safeText(asString(args.pattern, "*")))} in ${safeText(shortenPath(args.path) || ".")}`;
+			if (typeof args.limit === "number") text += theme.fg("toolOutput", ` limit ${args.limit}`);
+			return text;
+		}
+		case "ls": {
+			let text = `${theme.fg("toolTitle", theme.bold("ls"))} ${theme.fg("accent", safeText(shortenPath(args.path) || "."))}`;
+			if (typeof args.limit === "number") text += theme.fg("toolOutput", ` limit ${args.limit}`);
+			return text;
+		}
+		case "edit":
+			return `${theme.fg("toolTitle", theme.bold("edit"))} ${theme.fg("accent", safeText(shortenPath(args.path) || "..."))}`;
+		case "write": {
+			const content = typeof args.content === "string" ? args.content : "";
+			const lineInfo = content.length > 0 ? theme.fg("muted", ` (${content.split("\n").length} lines)`) : "";
+			return `${theme.fg("toolTitle", theme.bold("write"))} ${theme.fg("accent", safeText(shortenPath(args.path) || "..."))}${lineInfo}`;
+		}
+	}
+}
+
+function partialLabel(toolName: QuietToolName): string {
+	return toolName === "bash" ? "Running..." : `${toolName}...`;
+}
+
+function registerQuietTool(pi: ExtensionAPI, toolName: QuietToolName): void {
+	const registrationTool = getBuiltInTools(process.cwd())[toolName];
+
+	pi.registerTool({
+		...registrationTool,
+		async execute(toolCallId, params, signal, onUpdate, ctx) {
+			const runtimeTool = getBuiltInTools(ctx.cwd)[toolName];
+			return runtimeTool.execute(toolCallId, params, signal, onUpdate, ctx);
+		},
+		renderCall(args, theme) {
+			return new Text(formatToolCall(toolName, args as Record<string, unknown>, theme), 0, 0);
+		},
+		renderResult(result, options, theme, context) {
+			if (options.isPartial) {
+				return new Text(theme.fg("warning", partialLabel(toolName)), 0, 0);
+			}
+			const output = formatToolResultOutput(toolName, result, {
+				expanded: options.expanded,
+				isError: options.isError,
+				args: context.args as Record<string, unknown> | undefined,
+			});
+			const color = options.expanded ? "toolOutput" : options.isError ? "error" : "muted";
+			return new Text(output ? theme.fg(color, output) : "", 0, 0);
+		},
+	});
+}
+
+export default function quietTools(pi: ExtensionAPI): void {
+	if (!quietToolsEnabled()) return;
+	for (const toolName of Object.keys(TOOL_CREATORS) as QuietToolName[]) {
+		registerQuietTool(pi, toolName);
+	}
+}

package/lib/quiet-tools-config.ts

@@ -0,0 +1,17 @@
+export const QUIET_TOOLS_ENV = "GENTLE_PI_QUIET_TOOLS";
+export const PI_PRETTY_SUPPRESSED_TOOL_NAMES = ["read", "bash", "ls", "find", "grep"] as const;
+
+export function quietToolsEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+	return env[QUIET_TOOLS_ENV] !== "0";
+}
+
+export function mergeDisabledTools(existing: string | undefined, tools: readonly string[]): string {
+	const disabled = new Set(
+		(existing ?? "")
+			.split(",")
+			.map((tool) => tool.trim().toLowerCase())
+			.filter(Boolean),
+	);
+	for (const tool of tools) disabled.add(tool);
+	return [...disabled].join(",");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "0.11.4",
+  "version": "0.13.0",
   "description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
   "license": "MIT",
   "type": "module",

package/tests/orchestrator-budget.test.ts

@@ -121,19 +121,19 @@ test(`getOrchestratorPrompt return value stays within the 10,240 B budget at a r
 //
 // Every normative line of the frozen pre-diet fixture is assigned to exactly
 // one documented disposition: CORE_VERBATIM (byte-identical in the new
-// core), or LAZY_VERBATIM (byte-identical in one specific lazy file, while
-// core carries a freshly-authored CORE_SUMMARIZED_INTO summary sentence that
-// is NOT literal-matched against the original line). Section headings that
-// are reused unchanged as the new core's summary heading are CORE_VERBATIM;
-// section bodies that are condensed away in core are LAZY_VERBATIM against
-// their one target lazy file — never a blanket union across all three.
+// core), LAZY_VERBATIM (byte-identical in one specific lazy file), or OBSOLETE
+// (intentionally absent from every live model-facing asset). Section headings
+// that are reused unchanged as the new core's summary heading are
+// CORE_VERBATIM; section bodies that are condensed away in core are
+// LAZY_VERBATIM against their one target lazy file — never a blanket union
+// across all three.
 // ---------------------------------------------------------------------------
 
 type Target = "core" | "delegation" | "memory" | "skills";
 
 interface DispositionRange {
 	lines: [number, number];
-	target: Target;
+	target: Target | "obsolete";
 	label: string;
 }
 
@@ -162,9 +162,19 @@ const DISPOSITION_MAP: DispositionRange[] = [
 	{ lines: [112, 112], target: "core", label: "Delegation Rules heading" },
 	{ lines: [114, 114], target: "core", label: "Delegation Rules core question" },
 	{
-		lines: [116, 181],
+		lines: [116, 132],
 		target: "delegation",
-		label: "Delegation Rules table + Mandatory Triggers + Cost/Context Balance + Canonical Workflows + Review Lens Selection",
+		label: "Delegation Rules table + Mandatory Triggers preamble",
+	},
+	{
+		lines: [133, 133],
+		target: "obsolete",
+		label: "Superseded no-runtime inline exception",
+	},
+	{
+		lines: [134, 181],
+		target: "delegation",
+		label: "Mandatory Triggers remainder + Cost/Context Balance + Canonical Workflows + Review Lens Selection",
 	},
 	{ lines: [183, 191], target: "core", label: "SDD Workflow pointer" },
 	{ lines: [193, 193], target: "core", label: "Memory Contract heading" },
@@ -194,11 +204,21 @@ for (const range of DISPOSITION_MAP) {
 	test(
 		`disposition-mapped union: ${range.label} (fixture:${range.lines[0]}-${range.lines[1]}) -> ${range.target}`,
 		() => {
-			const targetContent = readRealAsset(TARGET_FILE[range.target]);
+			const targetContent =
+				range.target === "obsolete"
+					? Object.values(TARGET_FILE).map(readRealAsset).join("\n")
+					: readRealAsset(TARGET_FILE[range.target]);
 			for (let ln = range.lines[0]; ln <= range.lines[1]; ln++) {
 				const raw = fixtureLines[ln - 1];
 				if (raw === undefined || !isNormativeLine(raw)) continue;
 				const trimmed = raw.trim();
+				if (range.target === "obsolete") {
+					assert.ok(
+						!targetContent.includes(trimmed),
+						`obsolete line retained: fixture:${ln} "${trimmed}" remains in a live model-facing asset (section: ${range.label})`,
+					);
+					continue;
+				}
 				assert.ok(
 					targetContent.includes(trimmed),
 					`normative line lost: fixture:${ln} "${trimmed}" not found verbatim in ${TARGET_FILE[range.target]} (disposition: ${range.target}, section: ${range.label})`,

package/tests/package-manifest.test.ts

@@ -1,8 +1,16 @@
 import assert from "node:assert/strict";
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import {
+	existsSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	rmSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
+import { installSddAssets } from "../lib/sdd-preflight.ts";
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 
@@ -49,6 +57,10 @@ test("package manifest installs pi-pretty through a wrapper without bundling nat
 		existsSync(join(PACKAGE_ROOT, "extensions", "pi-pretty.ts")),
 		"gentle-pi must expose pi-pretty through a packaged wrapper extension",
 	);
+	assert.ok(
+		existsSync(join(PACKAGE_ROOT, "extensions", "quiet-tools.ts")),
+		"gentle-pi must expose quiet built-in tool rendering through a packaged extension",
+	);
 	assert.ok(
 		!packageJson.bundledDependencies?.includes("@heyhuynhgiabuu/pi-pretty"),
 		"pi-pretty must not be bundled because its native optional dependencies are platform-specific",
@@ -67,6 +79,126 @@ function readAgentFrontmatter(file: string): string {
 	return match[1];
 }
 
+function readAgentDefinition(file: string): {
+	name: string;
+	source: string;
+	tools: string[];
+} {
+	const source = readFileSync(file, "utf8");
+	const frontmatter = readAgentFrontmatter(file);
+	const name = frontmatter.match(/^name:\s*(\S+)$/m)?.[1];
+	assert.ok(name, `${file} must declare a frontmatter name`);
+	const toolsBlock = frontmatter.match(/^tools:\n((?: {2}- [\w-]+\n?)+)/m)?.[1];
+	assert.ok(toolsBlock, `${file} must declare a YAML tool list`);
+	const tools = [...toolsBlock.matchAll(/^ {2}- ([\w-]+)$/gm)].map(
+		(match) => match[1],
+	);
+
+	return { name, source, tools };
+}
+
+function readTextContract(source: string, heading: string): string {
+	const escapedHeading = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const match = source.match(
+		new RegExp(`^## ${escapedHeading}\\n[\\s\\S]*?\\n\\x60\\x60\\x60text\\n([\\s\\S]*?)\\n\\x60\\x60\\x60`, "m"),
+	);
+	assert.ok(match, `${heading} must include a text contract block`);
+	return match[1];
+}
+
+function contractFields(contract: string, indentation = 0): string[] {
+	const prefix = " ".repeat(indentation);
+	return contract
+		.split("\n")
+		.flatMap((line) => {
+			const match = line.match(new RegExp(`^${prefix}([a-z_]+):`));
+			return match ? [match[1]] : [];
+		});
+}
+
+function nestedContractFields(contract: string, parent: string): string[] {
+	const lines = contract.split("\n");
+	const parentIndexes = lines.flatMap((line, index) =>
+		line.startsWith(`${parent}:`) ? [index] : [],
+	);
+	assert.equal(parentIndexes.length, 1, `${parent} must appear exactly once at top level`);
+
+	const tail = lines.slice(parentIndexes[0] + 1);
+	const relativeEnd = tail.findIndex((line) => /^\S/.test(line));
+	const nestedBlock = relativeEnd === -1 ? tail : tail.slice(0, relativeEnd);
+
+	return contractFields(nestedBlock.join("\n"), 2);
+}
+
+function readMarkdownSection(source: string, heading: string): string {
+	const lines = source.split(/\r?\n/);
+	const matches = lines.flatMap((line, index) => {
+		const match = line.match(/^(#{1,6})\s+(.+?)\s*$/);
+		return match?.[2] === heading
+			? [{ index, level: match[1].length }]
+			: [];
+	});
+	assert.equal(matches.length, 1, `Markdown must contain exactly one ${heading} section`);
+
+	const [{ index: start, level }] = matches;
+	const relativeEnd = lines.slice(start + 1).findIndex((line) => {
+		const match = line.match(/^(#{1,6})\s+/);
+		return match !== null && match[1].length <= level;
+	});
+	const end = relativeEnd === -1 ? lines.length : start + 1 + relativeEnd;
+
+	return lines.slice(start + 1, end).join("\n").trim();
+}
+
+function assertWorkerFallbackRouting(section: string, sectionName: string): void {
+	const boundedWriterPolicy = section.match(
+		/For bounded multi-file writes,[\s\S]*?(?=\n\n|\n\s*\d+\.|$)/,
+	)?.[0];
+	assert.ok(boundedWriterPolicy, `${sectionName} must define bounded writer routing`);
+
+	const preferred = boundedWriterPolicy.indexOf("`gentle-ai-worker`");
+	const configuredFallback = boundedWriterPolicy.indexOf("user-configured `worker`");
+	const nativeFallback = boundedWriterPolicy.indexOf("native `Agent`");
+
+	assert.ok(preferred >= 0, `${sectionName} must reference exact gentle-ai-worker name`);
+	assert.ok(
+		configuredFallback > preferred,
+		`${sectionName} must prefer the package-owned worker before a user-configured worker`,
+	);
+	assert.ok(
+		nativeFallback > configuredFallback,
+		`${sectionName} must place native Agent after both named worker definitions`,
+	);
+	assert.match(
+		boundedWriterPolicy,
+		/If neither (?:worker )?definition exists[^.]*native `Agent`[^.]*even when `subagent_\*` tools are available\./,
+		`${sectionName} must choose native Agent when neither worker definition exists`,
+	);
+	assert.match(
+		section,
+		/If no delegation mechanism is available, stop/,
+		`${sectionName} must stop when delegation is impossible`,
+	);
+}
+
+test("Markdown section extraction isolates policy text from sibling sections", () => {
+	const markdown = [
+		"# Agent",
+		"## Context contract",
+		"context-only policy",
+		"### Context detail",
+		"nested context policy",
+		"## Tool safety",
+		"tool-only policy",
+	].join("\n");
+
+	const context = readMarkdownSection(markdown, "Context contract");
+
+	assert.match(context, /context-only policy/);
+	assert.match(context, /nested context policy/);
+	assert.doesNotMatch(context, /tool-only policy/);
+});
+
 test("packaged agents use YAML list syntax for tool allowlists", () => {
 	const agentsDir = join(PACKAGE_ROOT, "assets", "agents");
 	const agentFiles = readdirSync(agentsDir).flatMap((entry) =>
@@ -96,6 +228,184 @@ test("jd-fix-agent packaged allowlist includes write tools", () => {
 	}
 });
 
+test("gentle-ai-worker packages the exact scoped writer contract", () => {
+	const agentsDir = join(PACKAGE_ROOT, "assets", "agents");
+	const agentPath = join(agentsDir, "gentle-ai-worker.md");
+	assert.ok(existsSync(agentPath), "gentle-pi must package gentle-ai-worker.md");
+	for (const genericName of ["worker.md", "generic-writer.md"]) {
+		assert.ok(
+			!existsSync(join(agentsDir, genericName)),
+			`the package-owned writer must not use collision-prone ${genericName}`,
+		);
+	}
+
+	const { name, source, tools } = readAgentDefinition(agentPath);
+	assert.equal(name, "gentle-ai-worker");
+	assert.deepEqual(tools, [
+		"read",
+		"grep",
+		"find",
+		"edit",
+		"write",
+		"bash",
+		"mem_save",
+	]);
+	assert.ok(
+		tools.every((tool) => !tool.startsWith("subagent_")),
+		"a subagent must not be able to delegate",
+	);
+	assert.ok(!tools.includes("glob"), "the unsupported glob tool must not return");
+
+	const interactionContract = readMarkdownSection(source, "Interaction contract");
+	assert.doesNotMatch(
+		interactionContract,
+		/```text/,
+		"the interaction section must not define a second normative envelope",
+	);
+	assert.match(interactionContract, /stop editing/i);
+	assert.match(interactionContract, /full schema in the Return contract/);
+	assert.match(interactionContract, /`status: interaction_required`/);
+	assert.match(interactionContract, /nested `interaction_required` payload/);
+
+	const returnContract = readTextContract(source, "Return contract");
+	assert.deepEqual(contractFields(returnContract), [
+		"status",
+		"summary",
+		"files_changed",
+		"tdd_evidence",
+		"validation",
+		"risks",
+		"review_focus",
+		"skill_resolution",
+		"interaction_required",
+	]);
+	assert.deepEqual(nestedContractFields(returnContract, "interaction_required"), [
+		"question",
+		"reason",
+		"options",
+		"unblock_response",
+	]);
+	assert.match(
+		returnContract,
+		/skill_resolution: paths-injected \| paths-invalid \| none/,
+	);
+	assert.equal(
+		(source.match(/```text/g) ?? []).length,
+		1,
+		"the Return contract must be the single authoritative full handoff schema",
+	);
+	assert.doesNotMatch(source, /fallback-(?:registry|path)/);
+
+	const returnContractSection = readMarkdownSection(source, "Return contract");
+	assert.match(
+		returnContractSection,
+		/Use `skill_resolution: paths-invalid` only when the parent injected one or more exact skill paths and any supplied path cannot be read/,
+	);
+	assert.match(
+		returnContractSection,
+		/With `skill_resolution: paths-invalid`, keep `status: blocked`/,
+	);
+
+	const contextContract = readMarkdownSection(source, "Context contract");
+	assert.match(contextContract, /pre-existing untracked targets explicitly listed by the parent/);
+	assert.match(contextContract, /new files required by the delegated task/);
+
+	const implementationRules = readMarkdownSection(source, "Implementation rules");
+	assert.match(implementationRules, /`blocked` only for a non-human technical blocker/);
+
+	const toolSafety = readMarkdownSection(source, "Tool safety");
+	assert.match(toolSafety, /sensitive files/);
+	assert.match(toolSafety, /stage, commit, push, publish/);
+
+	const memorySafety = readMarkdownSection(source, "Memory safety");
+	assert.match(memorySafety, /secrets, credentials, personal data/);
+	assert.match(memorySafety, /raw untrusted repository/);
+
+	const testDiscipline = readMarkdownSection(source, "Test discipline");
+	assert.match(testDiscipline, /Strict TDD is active/);
+	assert.match(testDiscipline, /not active/);
+	assert.match(
+		testDiscipline,
+		/Broad suites, builds, formatters, or linters may run only when explicitly authorized by the parent\./,
+	);
+	assert.match(testDiscipline, /Keep every command exact and verify its scope before execution\./);
+	assert.doesNotMatch(testDiscipline, /clearly required by the repository contract/);
+});
+
+test("installSddAssets installs gentle-ai-worker with a loader-compatible scoped identity", () => {
+	const temporaryAgentHome = mkdtempSync(join(tmpdir(), "gentle-pi-agent-home-"));
+	const previousAgentHome = process.env.GENTLE_PI_AGENT_HOME;
+
+	try {
+		process.env.GENTLE_PI_AGENT_HOME = temporaryAgentHome;
+		installSddAssets(PACKAGE_ROOT, true);
+
+		const installedAgentsDir = join(temporaryAgentHome, "agents");
+		const installedAgentPath = join(installedAgentsDir, "gentle-ai-worker.md");
+		assert.ok(existsSync(installedAgentPath), "the production installer must install gentle-ai-worker.md");
+		for (const genericName of ["worker.md", "generic-writer.md"]) {
+			assert.ok(
+				!existsSync(join(installedAgentsDir, genericName)),
+				`the installer must not create collision-prone ${genericName}`,
+			);
+		}
+
+		const { name, source, tools } = readAgentDefinition(installedAgentPath);
+		const normalizedRuntimeIdentity = name.trim().toLowerCase();
+		assert.equal(normalizedRuntimeIdentity, "gentle-ai-worker");
+		assert.deepEqual(tools, [
+			"read",
+			"grep",
+			"find",
+			"edit",
+			"write",
+			"bash",
+			"mem_save",
+		]);
+		assert.doesNotMatch(
+			readAgentFrontmatter(installedAgentPath),
+			/^package\s*:/m,
+			"package frontmatter must not alter external loader identity",
+		);
+		assert.doesNotMatch(source, /^name:\s*(?:worker|generic-writer)$/m);
+	} finally {
+		if (previousAgentHome === undefined) {
+			delete process.env.GENTLE_PI_AGENT_HOME;
+		} else {
+			process.env.GENTLE_PI_AGENT_HOME = previousAgentHome;
+		}
+		rmSync(temporaryAgentHome, { recursive: true, force: true });
+	}
+
+	assert.equal(process.env.GENTLE_PI_AGENT_HOME, previousAgentHome);
+	assert.ok(
+		!existsSync(temporaryAgentHome),
+		"the integration test must delete only its temporary agent home",
+	);
+});
+
+test("bounded implementation routing uses the same explicit fallback in both policy sections", () => {
+	const routing = readFileSync(
+		join(PACKAGE_ROOT, "assets", "orchestrator-delegation.md"),
+		"utf8",
+	);
+	const simpleDelegation = readMarkdownSection(routing, "2. Simple Delegation");
+	const mandatoryDelegation = readMarkdownSection(routing, "Mandatory Delegation Triggers");
+
+	assertWorkerFallbackRouting(simpleDelegation, "Simple Delegation");
+	assertWorkerFallbackRouting(mandatoryDelegation, "Mandatory Delegation Triggers");
+	assert.doesNotMatch(
+		routing,
+		/non-normative compatibility quotation|former wording is retained|no-runtime inline exception|superseded by the stop requirement/,
+		"model-facing routing must not retain contradictory dead prose",
+	);
+	assert.doesNotMatch(
+		routing,
+		/`generic-writer`/,
+		"routing must not revive the collision-prone generic package name",
+	);
+});
+
 test("pi-pretty wrapper uses real package path resolution for pnpm symlink installs", () => {
 	const wrapper = readFileSync(
 		join(PACKAGE_ROOT, "extensions", "pi-pretty.ts"),
@@ -105,4 +415,6 @@ test("pi-pretty wrapper uses real package path resolution for pnpm symlink insta
 	assert.match(wrapper, /realpathSync/);
 	assert.match(wrapper, /createRequire/);
 	assert.match(wrapper, /@heyhuynhgiabuu\/pi-pretty/);
+	assert.match(wrapper, /PI_PRETTY_SUPPRESSED_TOOL_NAMES/);
+	assert.match(wrapper, /quietToolsEnabled/);
 });

package/tests/quiet-tool-rendering.test.ts

@@ -0,0 +1,249 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import piPretty from "../extensions/pi-pretty.ts";
+import quietTools, {
+	countNonEmptyLines,
+	extractTextContent,
+	formatToolResultOutput,
+	tailLines,
+} from "../extensions/quiet-tools.ts";
+
+const passthroughTheme = {
+	bold(value: string) {
+		return value;
+	},
+	fg(_color: string, value: string) {
+		return value;
+	},
+};
+
+function renderToString(component: { render(width: number): string[] }): string {
+	return component.render(120).join("\n");
+}
+
+function textResult(text: string) {
+	return {
+		content: [{ type: "text", text }],
+	};
+}
+
+function createPi(options: { throwOnToolConflict?: boolean } = {}) {
+	const tools = new Map<string, any>();
+	const commands = new Map<string, any>();
+	const hooks = new Map<string, any[]>();
+	return {
+		tools,
+		pi: {
+			registerTool(tool: any) {
+				if (options.throwOnToolConflict && tools.has(tool.name)) {
+					throw new Error(`Tool ${tool.name} already registered`);
+				}
+				tools.set(tool.name, tool);
+			},
+			registerCommand(name: string, command: any) {
+				commands.set(name, command);
+			},
+			on(name: string, handler: any) {
+				hooks.set(name, [...(hooks.get(name) ?? []), handler]);
+			},
+		},
+	};
+}
+
+function createSdkTool(name: string) {
+	return {
+		name,
+		label: name,
+		description: `${name} tool`,
+		parameters: { type: "object", properties: {} },
+		execute: async () => textResult(`${name} result`),
+	};
+}
+
+const fakePiPrettyDeps = {
+	sdk: {
+		createReadTool: () => createSdkTool("read"),
+		createBashTool: () => createSdkTool("bash"),
+		createLsTool: () => createSdkTool("ls"),
+		createFindTool: () => createSdkTool("find"),
+		createGrepTool: () => createSdkTool("grep"),
+	},
+};
+
+function withEnv<T>(updates: Record<string, string | undefined>, run: () => T): T {
+	const previous = Object.fromEntries(Object.keys(updates).map((key) => [key, process.env[key]]));
+	try {
+		for (const [key, value] of Object.entries(updates)) {
+			if (value === undefined) delete process.env[key];
+			else process.env[key] = value;
+		}
+		return run();
+	} finally {
+		for (const [key, value] of Object.entries(previous)) {
+			if (value === undefined) delete process.env[key];
+			else process.env[key] = value;
+		}
+	}
+}
+
+async function withEnvAsync<T>(updates: Record<string, string | undefined>, run: () => Promise<T>): Promise<T> {
+	const previous = Object.fromEntries(Object.keys(updates).map((key) => [key, process.env[key]]));
+	try {
+		for (const [key, value] of Object.entries(updates)) {
+			if (value === undefined) delete process.env[key];
+			else process.env[key] = value;
+		}
+		return await run();
+	} finally {
+		for (const [key, value] of Object.entries(previous)) {
+			if (value === undefined) delete process.env[key];
+			else process.env[key] = value;
+		}
+	}
+}
+
+test("quiet tool rendering registers noisy built-in tools", () => {
+	withEnv({ GENTLE_PI_QUIET_TOOLS: undefined }, () => {
+		const { pi, tools } = createPi();
+
+		quietTools(pi as any);
+
+		for (const toolName of ["read", "bash", "grep", "find", "ls", "edit", "write"]) {
+			const tool = tools.get(toolName);
+			assert.ok(tool, `missing quiet renderer for ${toolName}`);
+			assert.equal(typeof tool.execute, "function", `${toolName} must delegate execution`);
+			assert.ok(tool.parameters, `${toolName} must preserve built-in parameters`);
+		}
+	});
+});
+
+test("quiet tool rendering can be disabled by env", () => {
+	withEnv({ GENTLE_PI_QUIET_TOOLS: "0" }, () => {
+		const { pi, tools } = createPi();
+
+		quietTools(pi as any);
+
+		assert.equal(tools.size, 0);
+	});
+});
+
+test("pi-pretty suppresses overlapping tools before quiet tools register", async () => {
+	await withEnvAsync(
+		{ GENTLE_PI_QUIET_TOOLS: undefined, PRETTY_DISABLE_TOOLS: "multi_grep" },
+		async () => {
+			const { pi, tools } = createPi({ throwOnToolConflict: true });
+
+			await piPretty(pi as any, fakePiPrettyDeps as any);
+			quietTools(pi as any);
+
+			for (const toolName of ["read", "bash", "grep", "find", "ls", "edit", "write"]) {
+				assert.ok(tools.has(toolName), `missing quiet tool ${toolName}`);
+			}
+			assert.equal(process.env.PRETTY_DISABLE_TOOLS, "multi_grep,read,bash,ls,find,grep");
+		},
+	);
+});
+
+test("pi-pretty suppression is skipped when quiet tools are disabled", async () => {
+	await withEnvAsync(
+		{ GENTLE_PI_QUIET_TOOLS: "0", PRETTY_DISABLE_TOOLS: undefined },
+		async () => {
+			const { pi, tools } = createPi();
+
+			await piPretty(pi as any, fakePiPrettyDeps as any);
+			quietTools(pi as any);
+
+			for (const toolName of ["read", "bash", "grep", "find", "ls"]) {
+				assert.ok(tools.has(toolName), `pi-pretty should keep ${toolName} when quiet tools are disabled`);
+			}
+			assert.equal(process.env.PRETTY_DISABLE_TOOLS, undefined);
+		},
+	);
+});
+
+test("quiet tool rendering hides noisy result bodies while collapsed and restores them when expanded", () => {
+	const { pi, tools } = createPi();
+	withEnv({ GENTLE_PI_QUIET_TOOLS: undefined }, () => quietTools(pi as any));
+
+	const cases = [
+		{ tool: "read", text: "first line\nsecond line", hidden: "first line", expanded: "second line" },
+		{ tool: "bash", text: "stdout line\nstderr line", hidden: "stdout line", expanded: "stderr line" },
+		{ tool: "grep", text: "src/a.ts:1:match\nsrc/b.ts:2:match", hidden: "src/a.ts", expanded: "src/b.ts" },
+		{ tool: "find", text: "src/a.ts\nsrc/b.ts", hidden: "src/a.ts", expanded: "src/b.ts" },
+		{ tool: "ls", text: "file-a.ts\nfile-b.ts", hidden: "file-a.ts", expanded: "file-b.ts" },
+	];
+
+	for (const entry of cases) {
+		const tool = tools.get(entry.tool);
+		const collapsed = renderToString(
+			tool.renderResult(textResult(entry.text), { expanded: false, isPartial: false }, passthroughTheme, {}),
+		);
+		const expanded = renderToString(
+			tool.renderResult(textResult(entry.text), { expanded: true, isPartial: false }, passthroughTheme, {}),
+		);
+
+		assert.doesNotMatch(collapsed, new RegExp(entry.hidden.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")), `${entry.tool} collapsed output must not include result body`);
+		assert.match(expanded, new RegExp(entry.expanded.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")), `${entry.tool} expanded output must include full result body`);
+	}
+});
+
+test("quiet tool rendering keeps compact collapsed summaries for search and listing tools", () => {
+	assert.equal(countNonEmptyLines("a\n\n b \n"), 2);
+	assert.equal(extractTextContent(textResult("alpha\nbeta") as any), "alpha\nbeta");
+	assert.equal(formatToolResultOutput("grep", textResult("a\nb\n") as any, { expanded: false }), " → 2 matches");
+	assert.equal(formatToolResultOutput("find", textResult("a\nb\n") as any, { expanded: false }), " → 2 files");
+	assert.equal(formatToolResultOutput("ls", textResult("a\nb\n") as any, { expanded: false }), " → 2 entries");
+	assert.equal(formatToolResultOutput("grep", textResult("No matches found") as any, { expanded: false }), "");
+	assert.equal(formatToolResultOutput("find", textResult("No files found matching pattern") as any, { expanded: false }), "");
+	assert.equal(formatToolResultOutput("ls", textResult("Directory is empty") as any, { expanded: false }), "");
+	assert.equal(formatToolResultOutput("read", textResult("a\nb\n") as any, { expanded: false }), "");
+	assert.equal(formatToolResultOutput("bash", textResult("a\nb\n") as any, { expanded: false }), "");
+	assert.equal(formatToolResultOutput("bash", textResult("a\nb\n") as any, { expanded: false, args: { command: "git diff" } }), "\na\nb\n");
+	assert.equal(formatToolResultOutput("bash", textResult("a\nb\n") as any, { expanded: false, args: { command: "git -C repo status" } }), "\na\nb\n");
+	assert.equal(formatToolResultOutput("bash", textResult("a\nb\n") as any, { expanded: false, args: { command: "echo git diff" } }), "");
+	assert.equal(formatToolResultOutput("edit", textResult("updated") as any, { expanded: false }), "\nupdated");
+	assert.equal(formatToolResultOutput("write", textResult("wrote") as any, { expanded: false }), "\nwrote");
+	assert.equal(formatToolResultOutput("grep", textResult("a\nb\n") as any, { expanded: true }), "\na\nb\n");
+	assert.equal(formatToolResultOutput("read", textResult("ENOENT: missing file") as any, { expanded: false, isError: true }), "\nENOENT: missing file");
+});
+
+test("quiet tool rendering keeps collapsed git bash result tails", () => {
+	const text = Array.from({ length: 12 }, (_, index) => `git line ${index + 1}`).join("\n");
+
+	assert.equal(formatToolResultOutput("bash", textResult(text) as any, { expanded: false, args: { command: "git diff" } }), `\n${tailLines(text, 10)}`);
+	assert.equal(formatToolResultOutput("bash", textResult(text) as any, { expanded: false, args: { command: "git status --short" } }), `\n${tailLines(text, 10)}`);
+});
+
+test("quiet tool rendering keeps collapsed edit and write result tails", () => {
+	const text = Array.from({ length: 12 }, (_, index) => `line ${index + 1}`).join("\n");
+
+	assert.equal(tailLines(text, 10), Array.from({ length: 10 }, (_, index) => `line ${index + 3}`).join("\n"));
+	assert.equal(formatToolResultOutput("edit", textResult(text) as any, { expanded: false }), `\n${tailLines(text, 10)}`);
+	assert.equal(formatToolResultOutput("write", textResult(text) as any, { expanded: false }), `\n${tailLines(text, 10)}`);
+});
+
+test("quiet tool rendering sanitizes collapsed output and call rows", () => {
+	const { pi, tools } = createPi();
+	withEnv({ GENTLE_PI_QUIET_TOOLS: undefined }, () => quietTools(pi as any));
+
+	const collapsed = renderToString(
+		tools.get("write").renderResult(textResult("safe\x1b[31mred\x1b[0m"), { expanded: false, isPartial: false }, passthroughTheme, {}),
+	);
+	const call = renderToString(tools.get("bash").renderCall({ command: "echo \x1b[31mred\x1b[0m" }, passthroughTheme, {}));
+
+	assert.equal(collapsed.replace(/[ \t]+$/gm, ""), "\nsafered");
+	assert.equal(call.trimEnd(), "$ echo red");
+});
+
+test("quiet tool rendering call rows show tool calls without result output", () => {
+	const { pi, tools } = createPi();
+	withEnv({ GENTLE_PI_QUIET_TOOLS: undefined }, () => quietTools(pi as any));
+
+	const readCall = renderToString(tools.get("read").renderCall({ path: "/tmp/example.ts", offset: 2, limit: 3 }, passthroughTheme, {}));
+	const bashCall = renderToString(tools.get("bash").renderCall({ command: "printf noisy", timeout: 5 }, passthroughTheme, {}));
+	const grepCall = renderToString(tools.get("grep").renderCall({ pattern: "needle", path: "src", glob: "*.ts" }, passthroughTheme, {}));
+
+	assert.match(readCall, /read .*example\.ts:2-4/);
+	assert.match(bashCall, /\$ printf noisy \(timeout 5s\)/);
+	assert.match(grepCall, /grep \/needle\/ in src \(\*\.ts\)/);
+});

package/tests/runtime-harness.mjs

@@ -12,6 +12,7 @@ import { stripAnsi } from "../lib/terminal-theme.ts";
 const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const EXTENSIONS = [
 	"extensions/gentle-ai.ts",
+	"extensions/quiet-tools.ts",
 	"extensions/skill-registry.ts",
 	"extensions/sdd-init.ts",
 	"extensions/startup-banner.ts",
@@ -59,6 +60,7 @@ function createPi() {
 	const hooks = new Map();
 	const commands = new Map();
 	const flags = new Map();
+	const tools = new Map();
 	const flagValues = new Map([["no-skill-registry", true]]);
 	let activeTools = ["read", "bash", "edit", "write"];
 
@@ -74,6 +76,9 @@ function createPi() {
 		registerFlag(name, definition) {
 			flags.set(name, definition);
 		},
+		registerTool(definition) {
+			tools.set(definition.name, definition);
+		},
 		getFlag(name) {
 			return flagValues.get(name) ?? false;
 		},
@@ -100,7 +105,7 @@ function createPi() {
 		},
 	};
 
-	return { pi, hooks, commands, flags };
+	return { pi, hooks, commands, flags, tools };
 }
 
 function createUi() {
@@ -170,7 +175,7 @@ async function run() {
 	process.env.GENTLE_PI_TEST_ASSETS_DIR = ambientTestAssetsDir;
 	const globalModelsPath = join(globalConfigHome, "models.json");
 	const globalSubagentsPath = join(globalAgentHome, "subagents.json");
-	const { pi, hooks, commands, flags } = createPi();
+	const { pi, hooks, commands, flags, tools } = createPi();
 	await loadExtensions(pi);
 
 	for (const name of EXPECTED_COMMANDS) {
@@ -185,6 +190,9 @@ async function run() {
 	assert.ok(hooks.has("input"), "missing input hook");
 	assert.ok(hooks.has("before_agent_start"), "missing before_agent_start hook");
 	assert.ok(hooks.has("tool_call"), "missing tool_call hook");
+	for (const toolName of ["read", "bash", "grep", "find", "ls", "edit", "write"]) {
+		assert.ok(tools.has(toolName), `missing quiet built-in tool renderer ${toolName}`);
+	}
 
 	for (const entry of await readdir(join(ROOT, "assets", "agents"))) {
 		if (!entry.endsWith(".md")) continue;