one-code-extension 0.3.0 → 0.4.0

package/extensions/lib/scratchpad.ts

@@ -14,11 +14,11 @@
  * module state — so each re-derives it through `sessionScratchpadDir`.
  */
 
-import { realpathSync } from "node:fs";
 import os from "node:os";
 import { join } from "node:path";
 import { findGitRoot } from "./git.ts";
 import { projectSlug } from "./memory.ts";
+import { tryRealpath } from "./paths.ts";
 
 /** Pure core, testable: Claude Code's path shape under a One Code-named owner dir. */
 export function scratchpadDir(
@@ -32,17 +32,18 @@ export function scratchpadDir(
 }
 
 /**
- * `/tmp` resolved through its symlink (macOS: `/private/tmp`), so the path in
- * the prompt, the path the permission check compares, and the case-folded
- * resolved subject all name the same real location. Falls back to os.tmpdir()
- * where /tmp does not exist.
+ * The temp root in its resolved spelling, so the path in the prompt, the path
+ * the permission check compares, and the resolved subject all name the same
+ * real location: `/tmp` through its symlink (macOS: `/private/tmp`), and on
+ * Windows — which has no `/tmp`; `os.tmpdir()` is `%TEMP%`, Claude Code's own
+ * choice there — `%TEMP%` through its 8.3 short names, which Windows often
+ * spells it with (`C:\Users\RUNNER~1\…`, `ISURUW~1` for a long user name).
+ * A write's subject arrives realpath'd to the long name, so a scratchpad dir
+ * kept in the short spelling never contained anything (the runner showed it,
+ * findings §22). Falls back to the spelling as given where resolution fails.
  */
 function resolveTmpRoot(): string {
-	try {
-		return realpathSync("/tmp");
-	} catch {
-		return os.tmpdir();
-	}
+	return tryRealpath(process.platform === "win32" ? os.tmpdir() : "/tmp") ?? os.tmpdir();
 }
 
 /** The session's scratchpad, derived the same way by every consumer. */

package/extensions/lib/shell-spawn.ts

@@ -0,0 +1,298 @@
+/**
+ * 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
+ * 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
+ * with a warning when it is not a bash/sh binary (CC 2.1.219). PowerShell is
+ * `pwsh.exe` then `powershell.exe` on Windows (pi's own resolution), and a
+ * `pwsh` on PATH elsewhere — which is how the tool is developed and tested on
+ * this Mac (plan §Open questions 2). The argument list is pi's, copied because
+ * pi does not export the constant: `-NoProfile -NonInteractive
+ * -ExecutionPolicy Bypass -Command`, so the three safety flags are never lost.
+ *
+ * Resolution goes through pi's exported `getShellConfig` / `getPowerShellConfig`
+ * so a bash found here is the same bash pi's own bash tool runs. Both
+ * resolvers are injectable for tests (`platform`, `env`, `exists`, `fallback`).
+ *
+ * `createPowerShellOperations` supplies the spawn for pi's
+ * `createPowerShellToolDefinition(cwd, { operations })`: pi's own local
+ * operations throw off Windows, so the schema, cwd handling, truncation and
+ * rendering stay pi's while the process model is ours (spawn, stream both
+ * pipes, process-tree kill on abort/timeout, wait for exit) — the same ~60
+ * lines pi runs on Windows, with the same error strings the tool formats.
+ */
+
+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 { readSettingsEnv } from "./claude-settings.ts";
+import { detachedSpawnOptions, killProcessTree, waitForChildExit } from "./process-tree.ts";
+import { whichOnPath } from "./which.ts";
+
+/** How to start a shell for one command line. */
+export interface ShellSpawn {
+	shell: string;
+	args: string[];
+	/**
+	 * pi's legacy-WSL form (`C:\Windows\System32\bash.exe`): the command goes in
+	 * on stdin (`bash -s`) instead of as an argument. Default: argv.
+	 */
+	commandTransport?: "argv" | "stdin";
+}
+
+/** pi's PowerShell argument list (utils/shell.ts `POWERSHELL_ARGS`, not exported). */
+export const POWERSHELL_ARGS = ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command"] as const;
+
+/** 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";
+
+export const GIT_BASH_PATH_VAR = "CLAUDE_CODE_GIT_BASH_PATH";
+
+// ---------------------------------------------------------------------------
+// bash
+
+/** A path names a bash or sh binary — `bash`, `sh`, `bash.exe`, `sh.exe`, any case (CC 2.1.219's check). */
+export function isBashBinaryName(path: string): boolean {
+	const name = basename(path.replace(/\\/g, "/")).toLowerCase();
+	return name === "bash" || name === "sh" || name === "bash.exe" || name === "sh.exe";
+}
+
+export interface GitBashOverride {
+	path: string;
+	source: "env" | "settings";
+}
+
+/** The user's `CLAUDE_CODE_GIT_BASH_PATH`, process env first, then Claude Code's user-settings `env` block. */
+export function gitBashOverride(
+	env: NodeJS.ProcessEnv = process.env,
+	settingsEnv: Record<string, string> = {},
+): GitBashOverride | undefined {
+	const fromEnv = env[GIT_BASH_PATH_VAR]?.trim();
+	if (fromEnv) return { path: fromEnv, source: "env" };
+	const fromSettings = settingsEnv[GIT_BASH_PATH_VAR]?.trim();
+	if (fromSettings) return { path: fromSettings, source: "settings" };
+	return undefined;
+}
+
+export interface BashResolveInput {
+	env?: NodeJS.ProcessEnv;
+	/** Claude Code's settings `env` block (user scope only — lib/claude-settings.ts `readSettingsEnv`). */
+	settingsEnv?: Record<string, string>;
+	exists?: (path: string) => boolean;
+	/** pi's `getShellConfig`; injectable so tests never depend on this machine's shells. */
+	fallback?: (customShellPath?: string) => ShellSpawn;
+}
+
+export interface BashResolution {
+	/** Undefined when no bash exists (Windows without Git for Windows). */
+	spawn?: ShellSpawn;
+	/** An override that was ignored, and why — surfaced to the user once. */
+	warning?: string;
+	/** Why no bash could be found, in pi's own words. */
+	error?: string;
+}
+
+export function resolveBashSpawn(input: BashResolveInput = {}): BashResolution {
+	const exists = input.exists ?? existsSync;
+	const fallback = input.fallback ?? ((custom?: string) => getShellConfig(custom) as ShellSpawn);
+	const override = gitBashOverride(input.env, input.settingsEnv);
+	let warning: string | undefined;
+	if (override) {
+		const where = override.source === "env" ? `${GIT_BASH_PATH_VAR}` : `${GIT_BASH_PATH_VAR} (settings.json env)`;
+		if (!isBashBinaryName(override.path)) {
+			warning = `${where} ignored: "${override.path}" is not a bash or sh binary.`;
+		} else if (!exists(override.path)) {
+			warning = `${where} ignored: "${override.path}" does not exist.`;
+		} else {
+			try {
+				return { spawn: fallback(override.path) };
+			} catch (error) {
+				warning = `${where} ignored: ${error instanceof Error ? error.message : String(error)}`;
+			}
+		}
+	}
+	try {
+		return { spawn: fallback(), warning };
+	} catch (error) {
+		return { warning, error: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+let cachedBash: BashResolution | undefined;
+
+/**
+ * The bash this extension spawns, resolved once per module instance (pi's
+ * Windows lookup runs `where`, and hooks resolve on every tool call). The
+ * resolution reads Claude Code's user-settings `env` block itself, so every
+ * consumer — bash tool, hooks, monitor, PowerShell fallback — sees the same
+ * `CLAUDE_CODE_GIT_BASH_PATH`. Note the cache is per extension file: jiti
+ * gives each extension its own copy of this module (findings §3), so this is
+ * a memo, never a cross-extension channel — each extension resolves once.
+ */
+export function bashSpawn(): BashResolution {
+	cachedBash ??= resolveBashSpawn({ settingsEnv: readSettingsEnv(homedir()) });
+	return cachedBash;
+}
+
+/** The resolved bash, or a throw naming the fix (only reachable on Windows without Git for Windows). */
+export function bashSpawnOrThrow(): ShellSpawn {
+	const resolved = bashSpawn();
+	if (!resolved.spawn) throw new Error(resolved.error ?? "No bash shell found.");
+	return resolved.spawn;
+}
+
+/** Test seam. */
+export function resetShellSpawnCache(): void {
+	cachedBash = undefined;
+	cachedPowerShell = undefined;
+}
+
+// ---------------------------------------------------------------------------
+// PowerShell
+
+export interface PowerShellResolveInput {
+	platform?: NodeJS.Platform;
+	env?: NodeJS.ProcessEnv;
+	/** PATH lookup (lib/which.ts `whichOnPath`); injectable for tests. */
+	which?: (command: string, env: NodeJS.ProcessEnv) => string | undefined;
+	/** pi's `getPowerShellConfig` (Windows only); injectable for tests. */
+	windowsFallback?: () => ShellSpawn;
+}
+
+/** pi's resolver on Windows (`pwsh.exe` then `powershell.exe`); the first executable `pwsh` on PATH elsewhere. */
+export function resolvePowerShellSpawn(input: PowerShellResolveInput = {}): ShellSpawn | undefined {
+	const platform = input.platform ?? process.platform;
+	if (platform === "win32") {
+		try {
+			return (input.windowsFallback ?? (() => getPowerShellConfig() as ShellSpawn))();
+		} catch {
+			return undefined;
+		}
+	}
+	const pwsh = (input.which ?? ((cmd, env) => whichOnPath(cmd, env, platform)))("pwsh", input.env ?? process.env);
+	return pwsh ? { shell: pwsh, args: [...POWERSHELL_ARGS] } : undefined;
+}
+
+let cachedPowerShell: { spawn: ShellSpawn | undefined } | undefined;
+
+/** The PowerShell this process spawns, resolved once per process. */
+export function powerShellSpawn(): ShellSpawn | undefined {
+	cachedPowerShell ??= { spawn: resolvePowerShellSpawn() };
+	return cachedPowerShell.spawn;
+}
+
+/** 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";
+	const name = basename(spawnSpec.shell.replace(/\\/g, "/")).toLowerCase();
+	if (name === "pwsh" || name === "pwsh.exe") return "core";
+	if (name === "powershell.exe" || name === "powershell") return "desktop";
+	return "unknown";
+}
+
+// ---------------------------------------------------------------------------
+// spawning
+
+/**
+ * Start `command` under `spec`. argv transport appends the command to the
+ * 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.
+ */
+export function spawnShellCommand(spec: ShellSpawn, command: string, options: SpawnOptions): ChildProcess {
+	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 });
+		child.stdin?.on("error", () => {});
+		child.stdin?.end(command);
+		return child;
+	}
+	return spawn(spec.shell, [...spec.args, command], { ...options, windowsHide: true });
+}
+
+// ---------------------------------------------------------------------------
+// PowerShell operations for pi's tool definition
+
+/** pi's `BashOperations` shape (core/tools/bash.ts), spelled locally so this module has one pi import site. */
+export interface ShellOperations {
+	exec: (
+		command: string,
+		cwd: string,
+		options: { onData: (data: Buffer) => void; signal?: AbortSignal; timeout?: number; env?: NodeJS.ProcessEnv },
+	) => Promise<{ exitCode: number | null }>;
+}
+
+const MAX_TIMEOUT_MS = 2_147_483_647;
+
+/** pi's timeout validation (seconds → ms), same messages. */
+function resolveTimeoutMs(timeout: number | undefined): number | undefined {
+	if (timeout === undefined) return undefined;
+	if (!Number.isFinite(timeout) || timeout <= 0) throw new Error("Invalid timeout: must be a finite number of seconds");
+	const ms = timeout * 1000;
+	if (ms > MAX_TIMEOUT_MS) throw new Error(`Invalid timeout: maximum is ${MAX_TIMEOUT_MS / 1000} seconds`);
+	return ms;
+}
+
+/**
+ * Operations for `createPowerShellToolDefinition(cwd, { operations })` backed
+ * by the PowerShell `resolve()` names. Mirrors pi's local shell operations
+ * (spawn, stream, kill the tree on abort/timeout, wait) with pi's error strings
+ * — `aborted`, `timeout:<seconds>` — which the tool definition formats.
+ */
+export function createPowerShellOperations(resolve: () => ShellSpawn | undefined = powerShellSpawn): ShellOperations {
+	return {
+		exec: async (command, cwd, { onData, signal, timeout, env }) => {
+			const timeoutMs = resolveTimeoutMs(timeout);
+			if (signal?.aborted) throw new Error("aborted");
+			const spec = resolve();
+			if (!spec) {
+				throw new Error(
+					process.platform === "win32"
+						? "No PowerShell executable found. Install PowerShell or add powershell.exe/pwsh.exe to PATH."
+						: "No PowerShell executable found. Install PowerShell 7 (pwsh) and put it on PATH.",
+				);
+			}
+			try {
+				await access(cwd, constants.F_OK);
+			} catch {
+				throw new Error(`Working directory does not exist: ${cwd}\nCannot execute PowerShell commands.`);
+			}
+			const child = spawnShellCommand(spec, `${POWERSHELL_UTF8_PREFIX}${command}`, {
+				cwd,
+				...detachedSpawnOptions(),
+				env: env ?? process.env,
+				stdio: ["ignore", "pipe", "pipe"],
+			});
+			let timedOut = false;
+			let timer: NodeJS.Timeout | undefined;
+			const onAbort = () => killProcessTree(child, "SIGKILL");
+			try {
+				if (timeoutMs !== undefined) {
+					timer = setTimeout(() => {
+						timedOut = true;
+						killProcessTree(child, "SIGKILL");
+					}, timeoutMs);
+				}
+				child.stdout?.on("data", onData);
+				child.stderr?.on("data", onData);
+				if (signal) {
+					if (signal.aborted) onAbort();
+					else signal.addEventListener("abort", onAbort, { once: true });
+				}
+				const { code: exitCode } = await waitForChildExit(child);
+				if (signal?.aborted) throw new Error("aborted");
+				if (timedOut) throw new Error(`timeout:${timeout}`);
+				return { exitCode };
+			} finally {
+				if (timer) clearTimeout(timer);
+				signal?.removeEventListener("abort", onAbort);
+			}
+		},
+	};
+}

package/extensions/lib/shell-tool.ts

@@ -0,0 +1,252 @@
+/**
+ * The shared body of One Code's two shell tools (`bash`, `powershell`):
+ * Claude Code's `run_in_background` on top of pi's own shell tool
+ * definitions. Each extension supplies what differs — the tool's names and
+ * texts, pi's base definition, its per-cwd foreground executor, its
+ * pre-execution guard, and the spawn spec for a background run — and this
+ * module owns the orchestration: guard → millisecond timeout clamp →
+ * foreground delegate, or the background branch (blocking in one-shot modes,
+ * detached on the shared background registry with a completion notification
+ * otherwise). See extensions/bash/index.ts for why each piece is shaped as
+ * it is; extensions/powershell/index.ts is the second consumer.
+ */
+
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionContext, 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 type { ShellSpawn } from "./shell-spawn.ts";
+import { ccWrapBuiltinRenderers, linesComponent, resultLines } from "./tui-render.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 cap; the tools' `timeout` is milliseconds, as CC's is. */
+export const MAX_TIMEOUT_MS = 600_000;
+
+/** The parameter shape both shell tools share (descriptions differ per tool). */
+export interface ShellToolParams {
+	command: string;
+	timeout?: number;
+	description?: string;
+	run_in_background?: boolean;
+}
+
+/** The parts of pi's shell tool definition the shared body reads (structural, so the concrete generic types assign). */
+export interface ShellToolBase {
+	label: string;
+	promptSnippet?: string;
+	promptGuidelines?: readonly string[];
+	executionMode?: ToolDefinition["executionMode"];
+	constrainedSampling?: ToolDefinition["constrainedSampling"];
+	renderCall?: (args: any, theme: any, context: any) => any;
+	renderResult?: (result: any, options: any, theme: any, context: any) => any;
+}
+
+/** 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>;
+}
+
+/** What one shell tool's definition supplies; everything else is shared. */
+export interface ShellToolSpec<P extends TObject> {
+	/** pi tool name (`bash`, `powershell`). */
+	name: string;
+	/** Claude Code's label for the `● Label(cmd)` transcript line and the notifications. */
+	ccLabel: string;
+	description: string;
+	parameters: P;
+	/** pi's base definition: label, snippet, guidelines, execution mode, renderers. */
+	base: ShellToolBase;
+	promptGuidelines?: readonly string[];
+	/** The per-cwd foreground executor (pi's definition takes seconds). */
+	foreground: (cwd: string) => ShellToolExecutor;
+	/** Pre-execution guard on the model's ORIGINAL command; a string refuses the call. */
+	guard: (command: string, opts: { background: boolean }) => string | undefined;
+	/** The spawn for a background run, or undefined when the shell is unavailable. */
+	backgroundShell: () => ShellSpawn | undefined;
+	/** Rewrites the command for a background spawn (PowerShell prepends its UTF-8 prefix). Default: identity. */
+	wrapBackgroundCommand?: (command: string) => string;
+}
+
+/**
+ * How a shell task ended, read once from the finish summary: CC's `<status>`
+ * (a stop is `killed`, a timeout or non-zero exit `failed`) and, for a failure
+ * that an exit code does not explain, the detail (the timeout, the signal).
+ * `finishLine` (foreground text) and the background notification both build
+ * on this, so the two can never disagree.
+ */
+export function shellFinish(summary: BashFinishSummary, timeoutSeconds?: number): { status: TaskStatus; detail?: string } {
+	if (summary.stopped) return { status: "killed" };
+	if (summary.timedOut) return { status: "failed", detail: `timed out after ${timeoutSeconds}s` };
+	if (summary.exitCode === 0) return { status: "completed" };
+	return { status: "failed", detail: summary.exitCode === null ? `terminated by ${summary.signal ?? "unknown signal"}` : undefined };
+}
+
+export function finishLine(summary: BashFinishSummary, timeoutSeconds?: number): string {
+	const { status, detail } = shellFinish(summary, timeoutSeconds);
+	if (status === "killed") return "stopped";
+	if (status === "completed") return "completed";
+	return `failed (${detail ?? `exit code ${summary.exitCode}`})`;
+}
+
+/** `<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);
+		mkdirSync(dir, { recursive: true });
+		return join(dir, "output.log");
+	} catch {
+		return undefined;
+	}
+}
+
+export function registerShellTool<P extends TObject>(pi: ExtensionAPI, spec: ShellToolSpec<P>): 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 });
+	// A worktree session cd-wraps input.command; the pre-wrapper original arrives
+	// over the bus keyed by toolCallId (never read from params — model-writable).
+	const originalCommands = trackOriginalCommands(pi);
+	const notify = (text: string, details: Record<string, unknown>) => notifyTask("task-notification", text, details);
+	const wrap = spec.wrapBackgroundCommand ?? ((command: string) => command);
+
+	// `● Label(cmd)` / elbow-indented output, like every other One Code tool.
+	// Not passing base.renderCall also drops its timer state, so the misleading
+	// "Took Ns" that counted permission-prompt wait disappears.
+	const wrapped = ccWrapBuiltinRenderers<{ command?: string }>(spec.ccLabel, spec.base, { title: (a) => a?.command });
+
+	pi.registerTool({
+		name: spec.name,
+		label: spec.base.label,
+		description: spec.description,
+		promptSnippet: spec.base.promptSnippet,
+		promptGuidelines: spec.promptGuidelines ?? spec.base.promptGuidelines,
+		executionMode: spec.base.executionMode,
+		// pi 0.86 samples its own shell tools against a strict JSON schema by
+		// default (`{ type: "json_schema", strict: "prefer" }`); inherit that as
+		// tool-style does for read/edit/write, so every built-in-shaped tool gets
+		// the same treatment. Our parameter objects are strict-compatible, pi
+		// strips the `null` a strict optional arrives as before validation, and
+		// a provider without strict tools is left alone by "prefer".
+		constrainedSampling: spec.base.constrainedSampling,
+		renderShell: wrapped.renderShell,
+		renderCall: wrapped.renderCall as ToolDefinition<P>["renderCall"],
+		renderResult: ((result, options, theme, context) => {
+			// A background start returns a model-facing instruction paragraph;
+			// the transcript needs one line (Claude Code: "Running in the background").
+			const details = result.details as { taskId?: string; logPath?: string } | undefined;
+			if (details?.taskId && !context.isError) {
+				const line = options.expanded
+					? `Running in the background (task ${details.taskId}${details.logPath ? ` · log: ${details.logPath}` : ""})`
+					: "Running in the background (↓ to manage)";
+				return linesComponent(() => resultLines(theme as any, line, options.expanded, false));
+			}
+			return wrapped.renderResult(result, options, theme, context);
+		}) as ToolDefinition<P>["renderResult"],
+		parameters: spec.parameters,
+		async execute(toolCallId, rawParams, signal, onUpdate, ctx) {
+			const params = rawParams as Static<P> & ShellToolParams;
+			// Guards check the model's original command — a worktree session rewrites
+			// input.command to `cd '<wt>' && (…)`, which would hide the real lead.
+			const originalCommand = commandToEvaluate(originalCommands, toolCallId, params.command);
+			const guardReason = spec.guard(originalCommand, { background: params.run_in_background === true });
+			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;
+
+			if (!params.run_in_background) {
+				return spec.foreground(ctx.cwd).execute(toolCallId, { command: params.command, timeout: timeoutSeconds }, signal, onUpdate, ctx);
+			}
+
+			const shell = spec.backgroundShell();
+			if (!shell) {
+				return {
+					content: [{ type: "text" as const, text: `No ${spec.ccLabel} executable is available for a background run.` }],
+					isError: true,
+					details: {},
+				};
+			}
+			const id = generateTaskId();
+			const logPath = taskLogPath(ctx, id);
+			const description = params.description || params.command.slice(0, 80);
+			const command = wrap(params.command);
+
+			// One-shot modes (`-p` / `--mode json`) exit when the turn settles: a
+			// 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.
+			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 });
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `${spec.ccLabel} task ${id} (${description}) ${finishLine(summary, timeoutSeconds)}. ${oneShotNote("command")}${logPath ? ` Log: ${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,
+				};
+			}
+
+			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);
+					notify(
+						taskNotification({
+							kind: "shell",
+							taskId: id,
+							toolUseId: toolCallId,
+							outputFile: logPath,
+							status,
+							summary: shellSummary(description, status, summary.exitCode, detail),
+							result: logPath ? undefined : tailCap(summary.output, NOTIFY_OUTPUT_CAP).trim() || undefined,
+						}),
+						{ taskId: id, status: finishedTask.status, exitCode: summary.exitCode, logPath },
+					);
+				},
+			});
+			// The shell panel lists the task by the model's command, not a wrapped one.
+			task.command = params.command;
+			pi.events.emit(TASK_REGISTER_CHANNEL, task);
+
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text: `⏳ ${spec.ccLabel} task ${id} running in background (${description}).\n\nCompletion will arrive as a task notification on its own naming the output file — you do not need to wait for it or poll; keep working.${logPath ? ` To check interim output, read ${logPath}.` : ""} If your next step cannot proceed without the result, task_output with block=true waits for it. Stop with task_stop.`,
+					},
+				],
+				details: { taskId: id, logPath },
+			};
+		},
+	} as ToolDefinition<P>);
+}

package/extensions/lib/shell-tools.ts

@@ -0,0 +1,13 @@
+/**
+ * The tools whose subject is a shell command line (pure, no pi imports): the
+ * one list the permission matcher (`isShellTool`), the classifier transcript
+ * (`{"Bash":…}` / `{"PowerShell":…}` rendering) and the worktree rewriter
+ * read, so adding a shell tool is one edit.
+ */
+
+export const SHELL_TOOLS: ReadonlySet<string> = new Set(["bash", "powershell"]);
+
+/** Whether an already-normalized (pi snake_case) tool name is a shell tool. */
+export function isShellToolName(normalizedName: string): boolean {
+	return SHELL_TOOLS.has(normalizedName);
+}