one-code-extension 0.4.0 → 0.5.0

package/extensions/lib/settings-channels.ts

@@ -1,10 +1,10 @@
 /**
  * Cross-extension "a setting you own just changed on disk" channels (pure
  * constants). jiti isolates module state, so when one extension writes another
- * extension's setting — `/doctor preset` writing the subagent default and the
- * auto-mode classifier model — it announces the write here and the owner
- * re-reads its file and republishes its live status. No payload: the owner's
- * own loader is the source of truth.
+ * extension's setting — `/doctor preset` writing the subagent default and
+ * clearing the auto-mode classifier model — it announces the write here and the
+ * owner re-reads its file and republishes its live status. No payload: the
+ * owner's own loader is the source of truth.
  */
 
 /** `subagentModel` in ~/.onecode/settings.json changed; the subagents extension re-resolves and re-emits its status. */

package/extensions/lib/shell-exit-semantics.ts

@@ -0,0 +1,170 @@
+/**
+ * Claude Code's semantic exit codes (pure): a nonzero exit that is not an
+ * error, such as grep's "no matches" or diff's "files differ", which Claude
+ * Code reports as plain output with no `Exit code N` line. Bash and
+ * PowerShell keep separate tables and separate last-command rules.
+ */
+import { parseBash } from "./bash-parser.ts";
+
+type BashNode = NonNullable<ReturnType<typeof parseBash>>["rootNode"];
+const CONTAINERS = new Set(["program", "list", "pipeline"]);
+const OPERATORS = new Set(["&&", "||", "|", ";", "&", "|&", "\n"]);
+const EXIT_ONE_SUCCESSES = new Set(["grep", "rg", "egrep", "fgrep", "find", "diff", "test", "["]);
+
+/**
+ * The rightmost command's text, or undefined when an `&&` precedes it: a failed
+ * earlier step can explain the exit, not the final search. Redirects and
+ * comments are skipped, as Claude Code's last-command walk does.
+ */
+function lastCommand(root: BashNode): string | undefined {
+	let node: BashNode | undefined = root;
+	while (node && (CONTAINERS.has(node.type) || node.type === "redirected_statement")) {
+		const children: BashNode[] = node.children;
+		const last = children.findLastIndex((child) => !OPERATORS.has(child.type) && child.type !== "comment" && !child.type.endsWith("_redirect"));
+		if (node.type === "list" && children[last - 1]?.type === "&&") return undefined;
+		node = children[last];
+	}
+	return node?.text;
+}
+
+/** git's global options that take their value as the next word (`--git-dir=x` is one word). */
+const GIT_VALUE_OPTIONS = new Set(["-C", "-c", "--git-dir", "--work-tree", "--namespace", "--super-prefix", "--config-env", "--attr-source"]);
+
+/** git's subcommand among the words after `git`: the first that is no option or an option's value. */
+function gitSubcommandOf(args: readonly string[]): string | undefined {
+	for (let i = 0; i < args.length; i++) {
+		if (!args[i].startsWith("-")) return args[i];
+		if (GIT_VALUE_OPTIONS.has(args[i])) i++;
+	}
+	return undefined;
+}
+
+/** Bash: exit 1 from a final grep, rg, egrep, fgrep, find, diff, test, `[` or git grep/diff. */
+export function bashExitOneIsSuccess(command: string): boolean {
+	if (command.length > 10_000) return false;
+	const tree = parseBash(command);
+	if (!tree) return false;
+	try {
+		if (tree.rootNode.type !== "program") return false;
+		const last = lastCommand(tree.rootNode);
+		if (last === undefined) return false;
+		// Claude Code matches the literal first word: no unwrapping of env, assignments or quotes.
+		const [head, ...args] = last.trim().split(/\s+/);
+		if (head !== "git") return EXIT_ONE_SUCCESSES.has(head);
+		const sub = gitSubcommandOf(args);
+		return sub === "grep" || sub === "diff";
+	} finally {
+		tree.delete();
+	}
+}
+
+// PowerShell. The last segment splits on `;`, `|`, newlines, `&&` and a
+// spaced `&`, outside quotes and comments; `&&` before it means an earlier
+// step can explain the exit.
+type Segment = { text: string; andGated: boolean };
+
+function lastSegment(command: string): Segment {
+	const segments: Segment[] = [];
+	let start = 0;
+	let andGated = false;
+	let inSingle = false;
+	let inDouble = false;
+	for (let i = 0; i < command.length; i++) {
+		const c = command[i];
+		if (inSingle) {
+			if (c === "'") inSingle = false;
+			continue;
+		}
+		if (inDouble) {
+			if (c === "`") i++;
+			else if (c === '"') inDouble = false;
+			continue;
+		}
+		if (c === "#" && (i === 0 || " \t\n\r".includes(command[i - 1]))) {
+			segments.push({ text: command.slice(start, i), andGated });
+			while (i + 1 < command.length && command[i + 1] !== "\n" && command[i + 1] !== "\r") i++;
+			start = i + 1;
+			continue;
+		}
+		if (c === "'") {
+			inSingle = true;
+			continue;
+		}
+		if (c === '"') {
+			inDouble = true;
+			continue;
+		}
+		if (c === ";" || c === "|" || c === "\n" || c === "\r") {
+			segments.push({ text: command.slice(start, i), andGated });
+			start = i + 1;
+			if (c !== "|") andGated = false;
+			continue;
+		}
+		if (c === "&") {
+			if (command[i + 1] === "&") {
+				segments.push({ text: command.slice(start, i), andGated });
+				i++;
+				start = i + 1;
+				andGated = true;
+				continue;
+			}
+			const before = command[i - 1];
+			if ((before === " " || before === "\t") && command.slice(start, i).trim() !== "") {
+				segments.push({ text: command.slice(start, i), andGated });
+				start = i + 1;
+				andGated = false;
+			}
+		}
+	}
+	segments.push({ text: command.slice(start), andGated });
+	return segments.findLast((segment) => segment.text.trim()) ?? { text: command, andGated: false };
+}
+
+/** A segment's first word, unquoted, and the text after it; a leading `&` or `.` call operator is dropped. */
+function splitFirstWord(segment: string): { word: string; rest: string } {
+	const line = segment.trim().replace(/^[&.]\s+/, "");
+	const quoted = /^"([^"]*)"|^'([^']*)'/.exec(line);
+	if (quoted) return { word: quoted[1] ?? quoted[2], rest: line.slice(quoted[0].length) };
+	const raw = line.split(/\s+/)[0] ?? "";
+	return { word: raw.replace(/^["']|["']$/g, ""), rest: line.slice(raw.length) };
+}
+
+/** The command's file name, lowercased, without a native .exe/.cmd/.bat extension. */
+function baseCommand(word: string): { base: string; nativeExt: string | undefined } {
+	const file = (word.split(/[\\/]/).pop() || word).toLowerCase();
+	const nativeExt = ["exe", "cmd", "bat"].find((ext) => file.endsWith(`.${ext}`));
+	return { base: nativeExt ? file.slice(0, -(nativeExt.length + 1)) : file, nativeExt };
+}
+
+const exitOneOk = (code: number) => code === 0 || code === 1;
+const POWERSHELL_SEMANTICS = new Map<string, (code: number) => boolean>([
+	["grep", exitOneOk],
+	["rg", exitOneOk],
+	["egrep", exitOneOk],
+	["fgrep", exitOneOk],
+	["findstr", exitOneOk],
+	["robocopy", (code) => code >= 0 && code < 8],
+]);
+// Only as `<name>.exe` with output: bare `where` is Where-Object, bare `fc` Format-Custom.
+const POWERSHELL_EXE_WITH_OUTPUT = new Map<string, (code: number) => boolean>([
+	["where", exitOneOk],
+	["fc", exitOneOk],
+	["diff", exitOneOk],
+]);
+const NOT_RECOGNIZED = /is not recognized as (a name of a cmdlet|the name of a cmdlet|an? internal)/i;
+
+/** PowerShell: a nonzero exit the final command's table calls success. `output` is stdout and stderr merged. */
+export function powershellExitIsSuccess(command: string, exitCode: number, output: string): boolean {
+	if (exitCode === 0) return true;
+	const { text, andGated } = lastSegment(command);
+	const { word, rest } = splitFirstWord(text);
+	const { base, nativeExt } = baseCommand(word);
+	const sub = base === "git" ? gitSubcommandOf(rest.trim().split(/\s+/).filter(Boolean)) : undefined;
+	const ok =
+		sub === "grep" || sub === "diff"
+			? exitOneOk
+			: ((nativeExt === "exe" && output.trim() !== "" ? POWERSHELL_EXE_WITH_OUTPUT.get(base) : undefined) ?? POWERSHELL_SEMANTICS.get(base));
+	if (!ok?.(exitCode)) return false;
+	// A command that never ran, or findstr's own error, is a failure after all.
+	return !(andGated || NOT_RECOGNIZED.test(output) || /CommandNotFoundException/.test(output) || /^FINDSTR: /m.test(output));
+}

package/extensions/lib/shell-quote.ts

@@ -0,0 +1,11 @@
+/** Quoting one word for a shell command line. Pure. */
+
+/** A POSIX shell single-quoted word: the text exactly, whatever it holds. */
+export function shellQuote(word: string): string {
+	return `'${word.replace(/'/g, "'\\''")}'`;
+}
+
+/** PowerShell single-quoted literal: only `'` needs escaping, as `''`. */
+export function powershellQuote(word: string): string {
+	return `'${word.replace(/'/g, "''")}'`;
+}

package/extensions/lib/shell-result.ts

@@ -0,0 +1,70 @@
+/**
+ * Claude Code's shell result text, made from pi's (pure). pi ends a failing
+ * command's output with `\n\nCommand exited with code N` and keeps the
+ * output's trailing newline; Claude Code starts a failure with `Exit code N`
+ * on its own line and trims the output's leading blank lines and trailing
+ * whitespace, and an empty success reads `(<tool> completed with no output)`.
+ * A nonzero exit Claude Code's semantics call success (grep's no match, a
+ * diff that found differences) reads as a success. pi's truncation notes
+ * stay where they are, at the end of the output.
+ */
+
+import { emptyToolResultText } from "./empty-tool-result.ts";
+import { bashExitOneIsSuccess, powershellExitIsSuccess } from "./shell-exit-semantics.ts";
+
+type Block = { type: string; text?: string };
+type ShellResult = { content?: Block[]; structuredContent?: unknown; isError?: boolean };
+
+/** pi's text for an empty output. */
+const PI_NO_OUTPUT = "(no output)";
+
+function successText(output: string, toolName: string): string {
+	if (output === PI_NO_OUTPUT) return emptyToolResultText(toolName);
+	return output.replace(/^(\s*\n)+/, "").trimEnd() || emptyToolResultText(toolName);
+}
+
+/** The output before pi's `Command exited with code N` trailer, or undefined when the text is not pi's failure shape. */
+function failureOutput(text: string, exitCode: number): string | undefined {
+	const status = `Command exited with code ${exitCode}`;
+	if (text !== status && !text.endsWith(`\n\n${status}`)) return undefined;
+	return text.slice(0, Math.max(0, text.length - status.length - 2));
+}
+
+/** Claude Code's failure text: `Exit code N`, then the output on its own lines. */
+function failureText(output: string, exitCode: number): string {
+	return (output === PI_NO_OUTPUT || output === "" ? `Exit code ${exitCode}` : `Exit code ${exitCode}\n${output}`).trimEnd();
+}
+
+/** Claude Code's text for one foreground result, or undefined to keep pi's. */
+export function claudeCodeShellText(text: string, exitCode: unknown, toolName: string): string | undefined {
+	if (typeof exitCode !== "number") return undefined;
+	if (exitCode === 0) return successText(text, toolName);
+	const output = failureOutput(text, exitCode);
+	return output === undefined ? undefined : failureText(output, exitCode);
+}
+
+function semanticSuccess(toolName: string, command: string, exitCode: number, output: string): boolean {
+	if (toolName === "bash") return exitCode === 1 && bashExitOneIsSuccess(command);
+	if (toolName === "powershell") return powershellExitIsSuccess(command, exitCode, output === PI_NO_OUTPUT ? "" : output);
+	return false;
+}
+
+/** A foreground result with its first text block in Claude Code's words; other results pass through. */
+export function withClaudeCodeShellText<R extends ShellResult>(result: R, toolName: string, command: string): R {
+	const first = result?.content?.[0];
+	if (first?.type !== "text" || typeof first.text !== "string") return result;
+	const exitCode = (result.structuredContent as { exit_code?: unknown } | undefined)?.exit_code;
+	const rest = (result.content ?? []).slice(1);
+	let text: string | undefined;
+	if (typeof exitCode === "number" && exitCode !== 0) {
+		const output = failureOutput(first.text, exitCode);
+		if (output !== undefined && semanticSuccess(toolName, command, exitCode, output)) {
+			return { ...result, content: [{ ...first, text: successText(output, toolName) }, ...rest], isError: false };
+		}
+		text = output === undefined ? undefined : failureText(output, exitCode);
+	} else {
+		text = claudeCodeShellText(first.text, exitCode, toolName);
+	}
+	if (text === undefined || text === first.text) return result;
+	return { ...result, content: [{ ...first, text }, ...rest] };
+}

package/extensions/lib/shell-spawn.ts

@@ -2,7 +2,7 @@
  * Which shell One Code spawns, and how — the one place that knows about Git
  * Bash on Windows and about PowerShell.
  *
- * Claude Code's shape (findings §22, docs/decisions/windows.md): Git for
+ * Claude Code's shape (findings §22, working-docs/decisions/windows.md): Git for
  * Windows is optional. When a bash is available it drives the `bash` tool,
  * hooks and background shells; `CLAUDE_CODE_GIT_BASH_PATH` (process env, or
  * Claude Code's user-settings `env` block) names a custom bash and is ignored
@@ -29,9 +29,11 @@ import { type ChildProcess, spawn, type SpawnOptions } from "node:child_process"
 import { constants, existsSync } from "node:fs";
 import { access } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename } from "node:path";
-import { getPowerShellConfig, getShellConfig } from "@earendil-works/pi-coding-agent";
+import { basename, delimiter, join } from "node:path";
+import { getAgentDir, getPowerShellConfig, getShellConfig } from "@earendil-works/pi-coding-agent";
+import { childProcessEnv } from "./app-launch.mjs";
 import { readSettingsEnv } from "./claude-settings.ts";
+import { PowerShellParser, sharedPowerShellParser } from "./powershell-parser.ts";
 import { detachedSpawnOptions, killProcessTree, waitForChildExit } from "./process-tree.ts";
 import { whichOnPath } from "./which.ts";
 
@@ -52,6 +54,20 @@ export const POWERSHELL_ARGS = ["-NoProfile", "-NonInteractive", "-ExecutionPoli
 /** pi's UTF-8 output prefix for PowerShell (core/tools/powershell.ts), so Windows PowerShell 5.1 does not emit UTF-16. */
 export const POWERSHELL_UTF8_PREFIX = "try { [Console]::OutputEncoding=[System.Text.Encoding]::UTF8 } catch {}\n";
 
+/**
+ * What the PowerShell tool prepends to every command, foreground and
+ * background: pi's UTF-8 line, then UTF-8 for `Out-File` and `$OutputEncoding`
+ * and plain-text rendering, as Claude Code's PowerShell tool runs commands.
+ * `$PSStyle.OutputRendering = 'PlainText'` keeps pwsh 7's formatter from
+ * colouring table headers, which otherwise reached the model as raw
+ * `\x1b[32;1m` escapes.
+ */
+export const POWERSHELL_TOOL_PREFIX =
+	// One line, so an error's "At line:N" stays one off the command's own line, as with pi's prefix alone.
+	`${POWERSHELL_UTF8_PREFIX.trimEnd()}; try { $PSDefaultParameterValues['Out-File:Encoding'] = 'utf8' } catch {}; ` +
+	"if ($ExecutionContext.SessionState.LanguageMode -eq 'FullLanguage') { try { $OutputEncoding = [System.Text.UTF8Encoding]::new() } catch {}; " +
+	"if ($null -ne $PSStyle) { try { $PSStyle.OutputRendering = 'PlainText' } catch {} } };\n";
+
 export const GIT_BASH_PATH_VAR = "CLAUDE_CODE_GIT_BASH_PATH";
 
 // ---------------------------------------------------------------------------
@@ -187,6 +203,27 @@ export function powerShellSpawn(): ShellSpawn | undefined {
 	return cachedPowerShell.spawn;
 }
 
+/**
+ * PowerShell's own parser, served by the same executable and arguments the
+ * PowerShell tool runs (lib/powershell-parser.ts), one server per process.
+ * Undefined when no PowerShell resolves. It resolves command names on the
+ * foreground tool's PATH, pi's managed-tools directory first (piShellEnv):
+ * a `findstr.exe` there shadows Windows' own where the command runs. The
+ * background spawn's PATH lacks that directory, so a name resolved to
+ * System32 here resolves there too.
+ */
+export function powerShellParser(spec: ShellSpawn | undefined = powerShellSpawn()): PowerShellParser | undefined {
+	if (!spec) return undefined;
+	return sharedPowerShellParser(
+		spec.shell,
+		() =>
+			new PowerShellParser({
+				spawnServer: (bootstrap) =>
+					spawnShellCommand(spec, bootstrap, { env: piShellEnv(join(getAgentDir(), "bin")), stdio: ["pipe", "pipe", "pipe"] }),
+			}),
+	);
+}
+
 /** Whether the resolved PowerShell is Windows PowerShell 5.1 (`powershell.exe`) or PowerShell 7+ (`pwsh`). */
 export function powerShellEdition(spawnSpec: ShellSpawn | undefined): "core" | "desktop" | "unknown" {
 	if (!spawnSpec) return "unknown";
@@ -204,16 +241,20 @@ export function powerShellEdition(spawnSpec: ShellSpawn | undefined): "core" | "
  * shell's arguments (`bash -c <cmd>`, `pwsh … -Command <cmd>`); stdin transport
  * writes it to the child's stdin (pi's legacy-WSL bash), which needs stdin
  * piped — callers that must feed their own stdin (hooks) reject that form.
+ * The child's environment is `options.env` (default `process.env`) with the
+ * bundled app's launcher variables put back to the user's own values
+ * (app-launch.mjs childProcessEnv), so a `pi` run from a command is the user's pi.
  */
 export function spawnShellCommand(spec: ShellSpawn, command: string, options: SpawnOptions): ChildProcess {
+	const env = childProcessEnv(options.env ?? process.env);
 	if (spec.commandTransport === "stdin") {
 		const stdio = Array.isArray(options.stdio) ? ["pipe", ...options.stdio.slice(1)] : ["pipe", "pipe", "pipe"];
-		const child = spawn(spec.shell, spec.args, { ...options, stdio: stdio as SpawnOptions["stdio"], windowsHide: true });
+		const child = spawn(spec.shell, spec.args, { ...options, env, stdio: stdio as SpawnOptions["stdio"], windowsHide: true });
 		child.stdin?.on("error", () => {});
 		child.stdin?.end(command);
 		return child;
 	}
-	return spawn(spec.shell, [...spec.args, command], { ...options, windowsHide: true });
+	return spawn(spec.shell, [...spec.args, command], { ...options, env, windowsHide: true });
 }
 
 // ---------------------------------------------------------------------------
@@ -228,6 +269,29 @@ export interface ShellOperations {
 	) => Promise<{ exitCode: number | null }>;
 }
 
+/**
+ * pi's shell environment (utils/shell.ts `getShellEnv`, not exported): `env`
+ * with pi's managed-tools directory (`<agentDir>/bin`) first on PATH, the PATH
+ * key found in any case.
+ */
+export function piShellEnv(binDir: string, env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+	const pathKey = Object.keys(env).find((key) => key.toLowerCase() === "path") ?? "PATH";
+	const current = env[pathKey] ?? "";
+	if (current.split(delimiter).includes(binDir)) return { ...env };
+	return { ...env, [pathKey]: [binDir, current].filter(Boolean).join(delimiter) };
+}
+
+/**
+ * `operations` with every command's environment passed through
+ * childProcessEnv; `defaultEnv` stands in when the caller passes none (pi's
+ * user `!` commands never do, and its local operations then use its shell env).
+ */
+export function withChildProcessEnv(operations: ShellOperations, defaultEnv: () => NodeJS.ProcessEnv): ShellOperations {
+	return {
+		exec: (command, cwd, options) => operations.exec(command, cwd, { ...options, env: childProcessEnv(options.env ?? defaultEnv()) }),
+	};
+}
+
 const MAX_TIMEOUT_MS = 2_147_483_647;
 
 /** pi's timeout validation (seconds → ms), same messages. */
@@ -263,7 +327,7 @@ export function createPowerShellOperations(resolve: () => ShellSpawn | undefined
 			} catch {
 				throw new Error(`Working directory does not exist: ${cwd}\nCannot execute PowerShell commands.`);
 			}
-			const child = spawnShellCommand(spec, `${POWERSHELL_UTF8_PREFIX}${command}`, {
+			const child = spawnShellCommand(spec, `${POWERSHELL_TOOL_PREFIX}${command}`, {
 				cwd,
 				...detachedSpawnOptions(),
 				env: env ?? process.env,

package/extensions/lib/shell-tool.ts

@@ -13,24 +13,34 @@
 
 import { mkdirSync } from "node:fs";
 import { join } from "node:path";
-import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, ExtensionToolContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { Static, TObject } from "typebox";
 import { generateTaskId, TASK_REGISTER_CHANNEL } from "../background/registry.ts";
 import { type BashFinishSummary, runBackgroundBashBlocking, startBackgroundBash, tailCap } from "../bash/background.ts";
 import { createTaskNotifier, oneShotNote, sessionOutlivesTurn, shellSummary, type TaskStatus, taskNotification } from "./notifications.ts";
 import { commandToEvaluate, trackOriginalCommands } from "./original-command.ts";
-import { persistIfLarge, sessionResultsDir } from "./persisted-output.ts";
+import { persistedFilePreview, persistIfLarge, sessionResultsDir } from "./persisted-output.ts";
+import { withClaudeCodeShellText } from "./shell-result.ts";
+import { bashParserReady } from "./bash-parser.ts";
 import type { ShellSpawn } from "./shell-spawn.ts";
+import { keepSpillReadable } from "./spill-file.ts";
 import { ccWrapBuiltinRenderers, linesComponent, resultLines } from "./tui-render.ts";
+import { registerVariantTool } from "./tool-variants.ts";
 
 // The completion notification carries status + exit code + where the output is,
 // plus only a short tail: a finished build used to push 30 KB (~8k tokens) into
 // context unasked (review T7). The full tail stays behind task_output / the log.
 export const NOTIFY_OUTPUT_CAP = 2_000;
-/** One-shot modes return the whole output in the result; past this it is persisted (file + preview), never cut. */
-export const ONE_SHOT_OUTPUT_CAP = 30_000;
+/** Claude Code's inline cap for a shell's output; past it the output is persisted (file + head preview), never cut. */
+export const INLINE_OUTPUT_CAP = 30_000;
 /** Claude Code's cap; the tools' `timeout` is milliseconds, as CC's is. */
 export const MAX_TIMEOUT_MS = 600_000;
+/**
+ * Claude Code's default for a command that names no `timeout`, which both
+ * tool descriptions promise. pi's executor has no default, so without this a
+ * foreground `npm run dev` ran until Esc, and forever in a `-p` run.
+ */
+export const DEFAULT_TIMEOUT_MS = 120_000;
 
 /** The parameter shape both shell tools share (descriptions differ per tool). */
 export interface ShellToolParams {
@@ -53,7 +63,7 @@ export interface ShellToolBase {
 
 /** pi's shell tool executor: `execute(toolCallId, { command, timeout: seconds }, signal, onUpdate, ctx)`. */
 export interface ShellToolExecutor {
-	execute: (toolCallId: string, params: { command: string; timeout?: number }, signal: AbortSignal | undefined, onUpdate: any, ctx: ExtensionContext) => Promise<any>;
+	execute: (toolCallId: string, params: { command: string; timeout?: number }, signal: AbortSignal | undefined, onUpdate: any, ctx: ExtensionToolContext) => Promise<any>;
 }
 
 /** What one shell tool's definition supplies; everything else is shared. */
@@ -98,10 +108,20 @@ export function finishLine(summary: BashFinishSummary, timeoutSeconds?: number):
 	return `failed (${detail ?? `exit code ${summary.exitCode}`})`;
 }
 
+/**
+ * Why a one-shot `run_in_background` call was stopped: a one-shot session
+ * cannot keep a command running past the run, so the call is held to the
+ * foreground deadline.
+ */
+export function oneShotDeadlineNote(timeoutMs: number, explicit: boolean): string {
+	const which = explicit ? `its ${timeoutMs} ms timeout` : `the default ${timeoutMs} ms timeout (no \`timeout\` was given)`;
+	return `It was stopped at ${which}: a one-shot session cannot keep a background command running after the run ends, so a server or watcher started this way stops at the deadline. Pass a longer \`timeout\` (max ${MAX_TIMEOUT_MS}) for a long build.`;
+}
+
 /** `<sessionDir>/bash/<taskId>/output.log` — one spool location for every shell tool (the shell panel reads it). */
 export function taskLogPath(ctx: ExtensionContext, taskId: string): string | undefined {
 	try {
-		const dir = join(ctx.sessionManager.getSessionDir(), "bash", taskId);
+		const dir = join(sessionResultsDir(ctx), "bash", taskId);
 		mkdirSync(dir, { recursive: true });
 		return join(dir, "output.log");
 	} catch {
@@ -109,7 +129,13 @@ export function taskLogPath(ctx: ExtensionContext, taskId: string): string | und
 	}
 }
 
-export function registerShellTool<P extends TObject>(pi: ExtensionAPI, spec: ShellToolSpec<P>): void {
+/**
+ * Register the shell tool; the returned setter registers it again with a new
+ * description (a no-op when the text is unchanged), for a description that
+ * follows the session (lib/tool-variants.ts). Everything else — the notifier,
+ * the original-command tracker, execute — is built once.
+ */
+export function registerShellTool<P extends TObject>(pi: ExtensionAPI, spec: ShellToolSpec<P>): (description: string) => void {
 	// A completion whose output task_output just returned is withdrawn (CC's
 	// delivered_as_tool_result) — the model already has it.
 	const notifyTask = createTaskNotifier(pi, { withdrawOnDelivery: true });
@@ -124,7 +150,7 @@ export function registerShellTool<P extends TObject>(pi: ExtensionAPI, spec: She
 	// "Took Ns" that counted permission-prompt wait disappears.
 	const wrapped = ccWrapBuiltinRenderers<{ command?: string }>(spec.ccLabel, spec.base, { title: (a) => a?.command });
 
-	pi.registerTool({
+	const definition = {
 		name: spec.name,
 		label: spec.base.label,
 		description: spec.description,
@@ -162,14 +188,24 @@ export function registerShellTool<P extends TObject>(pi: ExtensionAPI, spec: She
 			if (guardReason) return { content: [{ type: "text" as const, text: guardReason }], isError: true, details: {} };
 			// pi's executor takes seconds; the model-facing unit is milliseconds
 			// (Claude Code's), so a habitual `timeout: 120000` is 2 minutes, not
-			// 33 hours (review T11).
-			const timeoutSeconds =
-				params.timeout !== undefined && Number.isFinite(params.timeout) && params.timeout > 0
-					? Math.min(params.timeout, MAX_TIMEOUT_MS) / 1000
-					: undefined;
+			// 33 hours (review T11). A command that names none gets Claude Code's
+			// default, which is what the descriptions promise.
+			const explicitTimeout = params.timeout !== undefined && Number.isFinite(params.timeout) && params.timeout > 0;
+			const timeoutSeconds = (explicitTimeout ? Math.min(params.timeout!, MAX_TIMEOUT_MS) : DEFAULT_TIMEOUT_MS) / 1000;
 
 			if (!params.run_in_background) {
-				return spec.foreground(ctx.cwd).execute(toolCallId, { command: params.command, timeout: timeoutSeconds }, signal, onUpdate, ctx);
+				// pi spills a long output to os.tmpdir(), outside every readable root;
+				// move it where the model's read of it is a working-space read, and
+				// cut the output Claude Code's way (its head, not pi's tail). Then
+				// Claude Code's result text (`Exit code N` first, trimmed output).
+				const result = await keepSpillReadable(
+					() => spec.foreground(ctx.cwd).execute(toolCallId, { command: params.command, timeout: timeoutSeconds }, signal, onUpdate, ctx),
+					sessionResultsDir(ctx),
+					{ inlineMax: INLINE_OUTPUT_CAP, id: `${spec.name}-${toolCallId}` },
+				);
+				// The no-match check parses the command; only bash results need the grammar.
+				if (spec.name === "bash") await bashParserReady();
+				return withClaudeCodeShellText(result, spec.name, originalCommand);
 			}
 
 			const shell = spec.backgroundShell();
@@ -189,48 +225,61 @@ export function registerShellTool<P extends TObject>(pi: ExtensionAPI, spec: She
 			// detached task would be orphaned, and its completion callback would
 			// call sendMessage on the disposed session and crash pi (measured,
 			// STEERING-REVIEW-2026-09-05 H3). Run blocking there — the same rule the
-			// Agent tool applies — and return the output in the result.
+			// Agent tool applies — and return the output in the result. The call
+			// holds the turn like a foreground command, so it gets the foreground
+			// deadline (the model's `timeout`, else the default): with none, a
+			// server started this way hung the run forever. A detached shell below
+			// keeps having no deadline (findings §31).
 			if (!sessionOutlivesTurn(ctx.mode)) {
 				const summary = await runBackgroundBashBlocking({ id, command, description, cwd: ctx.cwd, timeoutSeconds, logPath, shell }, signal);
-				const output = persistIfLarge(summary.output, { dir: sessionResultsDir(ctx), id: `${spec.name}-${id}`, maxBytes: ONE_SHOT_OUTPUT_CAP });
+				const spool = summary.logPath && Buffer.byteLength(summary.output, "utf8") > INLINE_OUTPUT_CAP
+					? persistedFilePreview(summary.logPath)
+					: undefined;
+				const output = spool ?? persistIfLarge(summary.output, { dir: sessionResultsDir(ctx), id: `${spec.name}-${id}`, maxBytes: INLINE_OUTPUT_CAP });
+				const deadline = summary.timedOut ? ` ${oneShotDeadlineNote(timeoutSeconds * 1000, explicitTimeout)}` : "";
 				return {
 					content: [
 						{
 							type: "text" as const,
-							text: `${spec.ccLabel} task ${id} (${description}) ${finishLine(summary, timeoutSeconds)}. ${oneShotNote("command")}${logPath ? ` Log: ${logPath}.` : ""}\n\n${output}`,
+							text: `${spec.ccLabel} task ${id} (${description}) ${finishLine(summary, timeoutSeconds)}. ${oneShotNote("command")}${deadline}${summary.logPath ? ` Log: ${summary.logPath}.` : ""}\n\n${output}`,
 						},
 					],
 					// No taskId: nothing was registered behind task_output/task_stop, and
 					// its presence is what renderResult reads as "running in the background".
-					details: { logPath },
-					isError: summary.exitCode !== 0 && !summary.stopped,
+					details: { logPath: summary.logPath },
+					isError: shellFinish(summary, timeoutSeconds).status === "failed",
 				};
 			}
 
+			// No timeout here: Claude Code clears a command's timeout the
+			// moment it goes to the background, so a detached shell has no
+			// deadline (findings §31). Models habitually send `timeout: 600000`
+			// next to `run_in_background`, which used to kill a dev server at
+			// exactly 10 minutes. The one-shot path above keeps the timeout
+			// because there the command holds the turn.
 			const task = startBackgroundBash({
 				id,
 				command,
 				description,
 				cwd: ctx.cwd,
-				timeoutSeconds,
 				logPath,
 				shell,
 				onFinished: (finishedTask, summary) => {
 					// Claude Code's shell completion names the output file and nothing
 					// else — the model reads it (or task_output) when it needs the text.
 					// Without a spool file the tail rides `<result>` so nothing is lost.
-					const { status, detail } = shellFinish(summary, timeoutSeconds);
+					const { status, detail } = shellFinish(summary);
 					notify(
 						taskNotification({
 							kind: "shell",
 							taskId: id,
 							toolUseId: toolCallId,
-							outputFile: logPath,
+							outputFile: finishedTask.logPath,
 							status,
 							summary: shellSummary(description, status, summary.exitCode, detail),
-							result: logPath ? undefined : tailCap(summary.output, NOTIFY_OUTPUT_CAP).trim() || undefined,
+							result: finishedTask.logPath ? undefined : tailCap(summary.output, NOTIFY_OUTPUT_CAP).trim() || undefined,
 						}),
-						{ taskId: id, status: finishedTask.status, exitCode: summary.exitCode, logPath },
+						{ taskId: id, status: finishedTask.status, exitCode: summary.exitCode, logPath: finishedTask.logPath },
 					);
 				},
 			});
@@ -248,5 +297,6 @@ export function registerShellTool<P extends TObject>(pi: ExtensionAPI, spec: She
 				details: { taskId: id, logPath },
 			};
 		},
-	} as ToolDefinition<P>);
+	} as ToolDefinition<P>;
+	return registerVariantTool(pi, spec.description, (description) => ({ ...definition, description }) as unknown as ToolDefinition);
 }