one-code-extension 0.4.1 → 0.6.0

package/extensions/lib/session-model-tier.ts

@@ -0,0 +1,51 @@
+/**
+ * One request-surface tier per session/model boundary. The first consumer owns
+ * the lifecycle handlers; every consumer reads that owner's value over the
+ * event bus. No module state is shared (each extension has its own jiti copy),
+ * and an extension loaded in isolation still installs its own owner.
+ *
+ * Only session_start and model_select classify. A catalog refresh can affect
+ * automatic model selection immediately, but prompt text, tool descriptions,
+ * and tier-dependent steering keep the same tier until the next boundary.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type PromptTier, resolveModelTier } from "./model-tier.ts";
+import { invalidateCatalogCache } from "./model-catalog-data.ts";
+
+const SESSION_TIER_REQUEST_CHANNEL = "one-code:session-tier-request";
+
+interface TierRequest {
+	owned?: boolean;
+	tier?: PromptTier;
+}
+
+/** Install the owner once on this bus, and return a reader of its frozen tier. */
+export function sessionModelTier(pi: Pick<ExtensionAPI, "events" | "on">): () => PromptTier {
+	const request = (): TierRequest => {
+		const query: TierRequest = {};
+		pi.events.emit(SESSION_TIER_REQUEST_CHANNEL, query);
+		return query;
+	};
+	if (!request().owned) {
+		let tier: PromptTier | undefined;
+		pi.events.on(SESSION_TIER_REQUEST_CHANNEL, (data) => {
+			Object.assign(data as TierRequest, { owned: true, tier });
+		});
+		const resolve = (model: Parameters<typeof resolveModelTier>[0]) => {
+			// Doctor's jiti copy cannot clear our memo. Do not freeze a stale
+			// catalog if the boundary lands inside the disk cache's stat throttle.
+			invalidateCatalogCache();
+			tier = resolveModelTier(model);
+		};
+		// Registered before the first consumer's hooks. Later consumers preserve
+		// their own lifecycle ordering (for example, restored bash mode variants).
+		pi.on("session_start", (_event, ctx) => resolve(ctx.model));
+		pi.on("model_select", (event) => resolve(event.model));
+	}
+	return () => {
+		const tier = request().tier;
+		if (tier === undefined) throw new Error("Request tier is unavailable: emit session_start before building the request surface.");
+		return tier;
+	};
+}

package/extensions/lib/session-work.ts

@@ -0,0 +1,64 @@
+/**
+ * What will wake the session later, for Claude Code's Stop hook payload: its
+ * `session_crons` (cron_create jobs, /loop, schedule_wakeup) and
+ * `background_tasks` (in-flight background work) fields, findings §21.
+ *
+ * The hooks extension emits a `SessionWorkQuery` on SESSION_WORK_CHANNEL and
+ * reads it back once the synchronous emit returns; the background extension,
+ * which owns both lists, fills it (jiti isolation: no shared module state).
+ *
+ * Pure: no pi imports.
+ */
+
+export const SESSION_WORK_CHANNEL = "one-code:session-work";
+
+/** Claude Code's `session_crons` item. */
+export interface SessionCron {
+	id: string;
+	/** The cron expression. */
+	schedule: string;
+	/** False for one-shots, a wakeup's single fire time included. */
+	recurring: boolean;
+	prompt: string;
+}
+
+/** Claude Code's `background_tasks` item. */
+export interface SessionBackgroundTask {
+	id: string;
+	/** Friendly type label: shell, subagent, monitor, workflow; else the raw kind. */
+	type: string;
+	status: string;
+	description: string;
+	/** Only for shell tasks. */
+	command?: string;
+}
+
+export interface SessionWorkQuery {
+	crons: SessionCron[];
+	tasks: SessionBackgroundTask[];
+}
+
+/** The hook payload's field cap (Claude Code: 1000 characters, then an in-string marker). */
+const FIELD_CAP = 1000;
+
+/** Claude Code's clip for these fields: the first 1000 characters, then `… [+N chars]`. */
+export function capField(text: string): string {
+	return text.length <= FIELD_CAP ? text : `${text.slice(0, FIELD_CAP)}… [+${text.length - FIELD_CAP} chars]`;
+}
+
+const TYPE_LABELS: Record<string, string> = { bash: "shell", shell: "shell", agent: "subagent", subagent: "subagent", monitor: "monitor", workflow: "workflow" };
+
+export function sessionCron(job: { id: string; cron: string; recurring: boolean; prompt: string }): SessionCron {
+	return { id: job.id, schedule: job.cron, recurring: job.recurring, prompt: capField(job.prompt) };
+}
+
+export function sessionBackgroundTask(task: { id: string; kind: string; status: string; description: string; command?: string }): SessionBackgroundTask {
+	const type = TYPE_LABELS[task.kind] ?? task.kind;
+	return {
+		id: task.id,
+		type,
+		status: task.status,
+		description: capField(task.description),
+		...(type === "shell" && task.command !== undefined && { command: capField(task.command) }),
+	};
+}

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,