pi-pwsh-native 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented here.
+
+## 0.1.0 — 2026-07-30
+
+### Added
+
+- Native model-callable `pwsh` tool built on Pi's standard shell tool definition.
+- PowerShell routing for interactive `!` and `!!` commands.
+- Strict global JSON configuration with environment overrides.
+- Verified PowerShell 7 runtime discovery using an absolute executable path.
+- UTF-8, multiline, and long-command transport using base64 source over stdin.
+- Native exit-code preservation and PowerShell cmdlet failure mapping.
+- Full Windows process-tree termination for timeout and cancellation.
+- Python UTF-8 and unbuffered environment defaults that preserve explicit user values.
+- Unit, Windows integration, runtime, exit-code, timeout, and cancellation tests.
+- Upstream provenance and MIT attribution documentation.
+
+### Changed from @4fu/pi-pwsh 0.6.2
+
+- Preserve Pi's dedicated `ls`, `find`, and `grep` tools by default.
+- Use the resolved absolute `pwsh.exe` path for all foreground commands.
+- Do not pass `-ExecutionPolicy Bypass` unless explicitly configured.
+- Do not probe or advertise elevation by default.
+- Do not translate or retry PowerShell source through `cmd.exe`.
+- Fail without silently restoring Bash when PowerShell setup is invalid.
+
+### Removed from the lean core
+
+- Detached background-job emulation.
+- Background-operator rewriting.
+- ConPTY sessions and `node-pty`.
+- Named-pipe RPC and PowerShell-to-TUI request helpers.
+- Runtime dependencies and native install scripts.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 4fuu
+Copyright (c) 2026 Tako
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+# pi-pwsh-native
+
+Native PowerShell 7 tooling for the [Pi coding agent](https://pi.dev/) on Windows.
+
+`pi-pwsh-native` replaces Pi's model-callable `bash` tool with a tool named `pwsh` and routes interactive `!`/`!!` commands through the same verified PowerShell executable. It does not translate Bash syntax and does not silently fall back to another shell.
+
+## Design
+
+- Registers a real `pwsh` tool so models are prompted to write PowerShell, not POSIX shell syntax.
+- Reuses Pi's built-in shell tool definition for streaming previews, the standard renderer, non-zero exit handling, tail truncation (2,000 lines / 50 KB), and full-output temporary files.
+- Keeps Pi's dedicated `read`, `write`, `edit`, `ls`, `find`, and `grep` tools active by default. Dedicated tools avoid unnecessary PowerShell startup and usually produce more focused output.
+- Routes user-entered `!command` and `!!command` through PowerShell by default while preserving Pi's context-inclusion semantics.
+- Requires PowerShell 7 or newer. Windows PowerShell 5.1 and Bash are not fallbacks.
+- Resolves and uses an absolute `pwsh.exe` path for every command.
+- Uses an ASCII bootstrap plus base64-over-stdin source transport. This preserves Unicode and multiline source without Windows command-line length limitations.
+- Forces plain UTF-8 output without a BOM and preserves native executable exit codes.
+- Kills the full process tree on timeout or cancellation.
+- Has no runtime dependencies, native install scripts, telemetry, or network calls.
+
+## Requirements
+
+- Windows
+- PowerShell 7+
+- Pi with extension support
+
+The initial implementation is developed and tested against:
+
+- Pi `0.83.0`
+- PowerShell `7.6.4`
+
+## Installation
+
+Install the pinned npm release:
+
+```powershell
+pi install npm:pi-pwsh-native@0.1.0
+```
+
+Alternatively, install the public GitHub package directly:
+
+```powershell
+pi install git:github.com/takomine/pi-pwsh-native
+```
+
+## Try from source
+
+```powershell
+Set-Location D:\pi\pi-pwsh-native
+npm install --ignore-scripts
+pi -e .\src\index.ts
+```
+
+For global development use, add the source path to `~/.pi/agent/settings.json`:
+
+```json
+{
+  "extensions": [
+    "D:/pi/pi-pwsh-native/src/index.ts"
+  ]
+}
+```
+
+Restart Pi or run `/reload` after changing extension code or configuration.
+
+The npm package name is `pi-pwsh-native`. Releases are validated by Windows CI and published from version tags after the initial package bootstrap.
+
+## Tool behavior
+
+With the default configuration:
+
+- `bash` is inactive.
+- `pwsh` is active.
+- `ls`, `find`, and `grep` remain active.
+- Existing tools from other extensions remain active.
+- `!` and `!!` execute through the selected PowerShell 7 runtime.
+
+Example model commands:
+
+```powershell
+Get-ChildItem
+$env:NODE_ENV = 'test'; npm test
+rg --glob '*.ts' 'createFileRoute' src
+fd --extension ts . src
+```
+
+PowerShell syntax is not translated. A Bash-only command fails visibly so the model can correct it.
+
+## Configuration
+
+The global configuration file is:
+
+```text
+~/.pi/agent/pwsh-native.json
+```
+
+Example:
+
+```json
+{
+  "executable": "C:\\Program Files\\PowerShell\\7\\pwsh.exe",
+  "loadProfile": false,
+  "executionPolicy": null,
+  "replaceUserBash": true,
+  "preserveDiscoveryTools": true,
+  "strictMode": false,
+  "pythonUtf8": true,
+  "pythonUnbuffered": true,
+  "elevationGuidance": false
+}
+```
+
+All fields are optional. Unknown fields and malformed values are rejected rather than ignored.
+
+| Field | Default | Meaning |
+|---|---:|---|
+| `executable` | `"auto"` | `"auto"` or an absolute path to PowerShell 7 `pwsh.exe` |
+| `loadProfile` | `false` | Load the user's PowerShell profile instead of passing `-NoProfile` |
+| `executionPolicy` | `null` | Optional explicit process execution policy; no override is passed by default |
+| `replaceUserBash` | `true` | Route Pi's `!` and `!!` commands through PowerShell |
+| `preserveDiscoveryTools` | `true` | Keep Pi's `ls`, `find`, and `grep` tools active |
+| `strictMode` | `false` | Set `$ErrorActionPreference = 'Stop'` for each command |
+| `pythonUtf8` | `true` | Default `PYTHONIOENCODING=utf-8` and `PYTHONUTF8=1` when unset |
+| `pythonUnbuffered` | `true` | Default `PYTHONUNBUFFERED=1` when unset |
+| `elevationGuidance` | `false` | Allow elevation-related prompt guidance; never auto-elevates |
+
+Supported explicit execution policies are `AllSigned`, `Bypass`, `Default`, `RemoteSigned`, `Restricted`, `Undefined`, and `Unrestricted`. `Bypass` is accepted only as an explicit user choice.
+
+### Environment overrides
+
+Environment variables override file values:
+
+- `PI_PWSH_NATIVE_CONFIG` — alternate configuration file path
+- `PI_PWSH_NATIVE_EXECUTABLE`
+- `PI_PWSH_NATIVE_LOAD_PROFILE`
+- `PI_PWSH_NATIVE_EXECUTION_POLICY`
+- `PI_PWSH_NATIVE_REPLACE_USER_BASH`
+- `PI_PWSH_NATIVE_PRESERVE_DISCOVERY_TOOLS`
+- `PI_PWSH_NATIVE_STRICT`
+- `PI_PWSH_NATIVE_PYTHON_UTF8`
+- `PI_PWSH_NATIVE_PYTHON_UNBUFFERED`
+- `PI_PWSH_NATIVE_ELEVATION_GUIDANCE`
+
+Boolean environment values accept `true/false`, `1/0`, `yes/no`, or `on/off`.
+
+## Runtime resolution
+
+When `executable` is `"auto"`, resolution checks:
+
+1. `pwsh.exe` found by `where.exe`.
+2. `C:\Program Files\PowerShell\7\pwsh.exe`.
+
+Each candidate is started and its version is verified. The selected absolute path is retained for all model and user commands.
+
+If an explicit executable is invalid, the extension reports that exact failure and does not try another shell. If setup fails, the model's Bash tool is disabled and manual shell commands return an actionable error.
+
+## Environment and exit codes
+
+Model tool calls retain Pi's session environment, including:
+
+- `PI_SESSION_ID`
+- `PI_SESSION_FILE`
+- `PI_PROVIDER`
+- `PI_MODEL`
+- `PI_REASONING_LEVEL`
+
+Manual `!`/`!!` commands follow Pi's documented user-command environment behavior.
+
+The command epilogue preserves `$LASTEXITCODE` when a native program ran. Commands that only use PowerShell map `$?` to exit code `0` or `1`.
+
+## Timeouts and cancellation
+
+There is no default timeout. The model can supply a timeout in seconds for a `pwsh` call. Timeout and Pi cancellation both invoke `taskkill.exe /T /F` for the spawned process, preventing common child-process leaks from tools such as `npm` and development servers.
+
+Persistent background jobs and interactive PTYs are intentionally outside the core package. Use an external terminal for long-running interactive processes until separately reviewed companion functionality is available.
+
+## Development
+
+```powershell
+npm install --ignore-scripts
+npm run typecheck
+npm test
+npm run test:windows
+npm run smoke
+npm run check
+```
+
+Test coverage includes configuration, runtime selection, tool activation, Unicode, multiline/long source transport, native exit codes, `.cmd` execution, timeout, cancellation, inherited stdio handles, and process-tree cleanup.
+
+## Security
+
+Pi extensions execute with the user's full permissions. Review source before installation.
+
+This package:
+
+- does not make network requests;
+- does not collect telemetry;
+- does not auto-elevate;
+- does not override execution policy by default;
+- does not silently retry through `cmd.exe`, Bash, or PowerShell 5.1;
+- does not have runtime dependencies or install scripts;
+- does not accumulate unbounded shell output outside Pi's standard bounded output pipeline.
+
+## Limitations
+
+- Windows-only in the initial release.
+- Each command starts a fresh PowerShell process for isolation and predictable state.
+- PowerShell profiles are disabled by default.
+- Background-job emulation and PTY helpers from the upstream project are not included in the lean core.
+- Competing shell-adapter extensions should not be enabled simultaneously.
+
+## Attribution
+
+This project derives from [`@4fu/pi-pwsh`](https://github.com/4fuu/pi-pwsh), licensed under MIT. See [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) and [`LICENSE`](LICENSE).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,15 @@
+# Third-Party Notices
+
+## @4fu/pi-pwsh
+
+This project is derived from **@4fu/pi-pwsh**, created by 4fuu and distributed under the MIT License.
+
+- Upstream repository: <https://github.com/4fuu/pi-pwsh>
+- Audited npm baseline: `@4fu/pi-pwsh@0.6.2`
+- Upstream git commit: `305b1c6cb07810562c7fccf543430cb5bf331074`
+- Published npm tarball: <https://registry.npmjs.org/@4fu/pi-pwsh/-/pi-pwsh-0.6.2.tgz>
+- npm integrity: `sha512-GmCAJK3Vci0UaaP+MoB4F3oVlsMuIptFzx7xvBS+GTJYRZFgkW7PQs7nClV5mMPjWlN0Vs13CqwvUoZHmtxb9A==`
+
+The published npm tarball integrity was verified, and every file in that tarball matched the corresponding blob in the upstream commit listed above before derivative changes began.
+
+The upstream copyright notice and MIT permission notice are retained in this project's [`LICENSE`](LICENSE) file. Files derived from the upstream implementation may have been modified for this project.

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "pi-pwsh-native",
+  "version": "0.1.0",
+  "description": "Native PowerShell 7 tooling for the Pi coding agent on Windows",
+  "license": "MIT",
+  "author": "Tako (https://github.com/takomine)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/takomine/pi-pwsh-native.git"
+  },
+  "bugs": {
+    "url": "https://github.com/takomine/pi-pwsh-native/issues"
+  },
+  "homepage": "https://github.com/takomine/pi-pwsh-native#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "os": [
+    "win32"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "powershell",
+    "pwsh",
+    "windows"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
+    "CHANGELOG.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "node ./node_modules/typescript/bin/tsc --noEmit",
+    "test": "node --test test/config.test.mjs test/core.test.mjs test/runtime.test.mjs",
+    "test:windows": "node --test test/integration.windows.test.mjs",
+    "test:runtime": "node scripts/smoke-runtime.mjs",
+    "test:exitcode": "node scripts/smoke-exitcode.mjs",
+    "test:timeout": "node scripts/smoke-timeout.mjs",
+    "check": "npm run typecheck && npm test && npm run test:windows",
+    "smoke": "npm run test:runtime && npm run test:exitcode && npm run test:timeout"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.83.0",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,188 @@
+import { readFileSync } from "node:fs";
+import { join, win32 } from "node:path";
+
+export const CONFIG_FILE_NAME = "pwsh-native.json";
+
+const EXECUTION_POLICIES = [
+	"AllSigned",
+	"Bypass",
+	"Default",
+	"RemoteSigned",
+	"Restricted",
+	"Undefined",
+	"Unrestricted",
+] as const;
+
+export type ExecutionPolicy = (typeof EXECUTION_POLICIES)[number];
+
+export interface PwshNativeConfig {
+	executable: "auto" | string;
+	loadProfile: boolean;
+	executionPolicy: ExecutionPolicy | null;
+	replaceUserBash: boolean;
+	preserveDiscoveryTools: boolean;
+	strictMode: boolean;
+	pythonUtf8: boolean;
+	pythonUnbuffered: boolean;
+	elevationGuidance: boolean;
+}
+
+export const DEFAULT_CONFIG: Readonly<PwshNativeConfig> = Object.freeze({
+	executable: "auto",
+	loadProfile: false,
+	executionPolicy: null,
+	replaceUserBash: true,
+	preserveDiscoveryTools: true,
+	strictMode: false,
+	pythonUtf8: true,
+	pythonUnbuffered: true,
+	elevationGuidance: false,
+});
+
+const CONFIG_KEYS = new Set<keyof PwshNativeConfig>(Object.keys(DEFAULT_CONFIG) as Array<keyof PwshNativeConfig>);
+
+const ENV_FIELDS = {
+	PI_PWSH_NATIVE_EXECUTABLE: "executable",
+	PI_PWSH_NATIVE_LOAD_PROFILE: "loadProfile",
+	PI_PWSH_NATIVE_EXECUTION_POLICY: "executionPolicy",
+	PI_PWSH_NATIVE_REPLACE_USER_BASH: "replaceUserBash",
+	PI_PWSH_NATIVE_PRESERVE_DISCOVERY_TOOLS: "preserveDiscoveryTools",
+	PI_PWSH_NATIVE_STRICT: "strictMode",
+	PI_PWSH_NATIVE_PYTHON_UTF8: "pythonUtf8",
+	PI_PWSH_NATIVE_PYTHON_UNBUFFERED: "pythonUnbuffered",
+	PI_PWSH_NATIVE_ELEVATION_GUIDANCE: "elevationGuidance",
+} as const;
+
+export class ConfigError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ConfigError";
+	}
+}
+
+function parseBoolean(value: unknown, field: string, source: string): boolean {
+	if (typeof value === "boolean") return value;
+	if (typeof value === "string") {
+		switch (value.trim().toLowerCase()) {
+			case "1":
+			case "true":
+			case "yes":
+			case "on":
+				return true;
+			case "0":
+			case "false":
+			case "no":
+			case "off":
+				return false;
+		}
+	}
+	throw new ConfigError(`${source}: ${field} must be a boolean (true/false, 1/0, yes/no, or on/off)`);
+}
+
+function parseExecutable(value: unknown, source: string): "auto" | string {
+	if (typeof value !== "string" || !value.trim()) {
+		throw new ConfigError(`${source}: executable must be \"auto\" or an absolute path to pwsh.exe`);
+	}
+	const executable = value.trim();
+	if (executable.toLowerCase() === "auto") return "auto";
+	if (!win32.isAbsolute(executable)) {
+		throw new ConfigError(`${source}: executable must be an absolute Windows path, received ${JSON.stringify(executable)}`);
+	}
+	return executable;
+}
+
+function parseExecutionPolicy(value: unknown, source: string): ExecutionPolicy | null {
+	if (value === null || value === undefined || value === "") return null;
+	if (typeof value !== "string") {
+		throw new ConfigError(`${source}: executionPolicy must be null or a PowerShell execution policy name`);
+	}
+	const policy = EXECUTION_POLICIES.find((candidate) => candidate.toLowerCase() === value.trim().toLowerCase());
+	if (!policy) {
+		throw new ConfigError(
+			`${source}: unsupported executionPolicy ${JSON.stringify(value)}; expected one of ${EXECUTION_POLICIES.join(", ")}`,
+		);
+	}
+	return policy;
+}
+
+function parseConfigObject(value: unknown, source: string): Partial<PwshNativeConfig> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new ConfigError(`${source}: configuration must be a JSON object`);
+	}
+	const input = value as Record<string, unknown>;
+	const unknown = Object.keys(input).filter((key) => !CONFIG_KEYS.has(key as keyof PwshNativeConfig));
+	if (unknown.length > 0) {
+		throw new ConfigError(`${source}: unknown configuration field${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}`);
+	}
+
+	const parsed: Partial<PwshNativeConfig> = {};
+	if ("executable" in input) parsed.executable = parseExecutable(input.executable, source);
+	if ("executionPolicy" in input) parsed.executionPolicy = parseExecutionPolicy(input.executionPolicy, source);
+	for (const key of [
+		"loadProfile",
+		"replaceUserBash",
+		"preserveDiscoveryTools",
+		"strictMode",
+		"pythonUtf8",
+		"pythonUnbuffered",
+		"elevationGuidance",
+	] as const) {
+		if (key in input) parsed[key] = parseBoolean(input[key], key, source);
+	}
+	return parsed;
+}
+
+function parseEnvironment(env: NodeJS.ProcessEnv): Partial<PwshNativeConfig> {
+	const parsed: Partial<PwshNativeConfig> = {};
+	for (const [environmentName, field] of Object.entries(ENV_FIELDS) as Array<
+		[keyof typeof ENV_FIELDS, (typeof ENV_FIELDS)[keyof typeof ENV_FIELDS]]
+	>) {
+		const value = env[environmentName];
+		if (value === undefined) continue;
+		const source = `environment variable ${environmentName}`;
+		if (field === "executable") parsed.executable = parseExecutable(value, source);
+		else if (field === "executionPolicy") parsed.executionPolicy = parseExecutionPolicy(value, source);
+		else parsed[field] = parseBoolean(value, field, source);
+	}
+	return parsed;
+}
+
+export interface LoadConfigOptions {
+	agentDir: string;
+	env?: NodeJS.ProcessEnv;
+	readFile?: typeof readFileSync;
+}
+
+export interface LoadedConfig {
+	config: PwshNativeConfig;
+	path: string;
+}
+
+export function loadConfig({ agentDir, env = process.env, readFile = readFileSync }: LoadConfigOptions): LoadedConfig {
+	const path = env.PI_PWSH_NATIVE_CONFIG?.trim() || join(agentDir, CONFIG_FILE_NAME);
+	let fileConfig: Partial<PwshNativeConfig> = {};
+	try {
+		const text = readFile(path, "utf8");
+		let json: unknown;
+		try {
+			json = JSON.parse(text);
+		} catch (error) {
+			throw new ConfigError(`${path}: invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		fileConfig = parseConfigObject(json, path);
+	} catch (error) {
+		if (error instanceof ConfigError) throw error;
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+			throw new ConfigError(`${path}: unable to read configuration: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+
+	return {
+		path,
+		config: {
+			...DEFAULT_CONFIG,
+			...fileConfig,
+			...parseEnvironment(env),
+		},
+	};
+}

package/src/index.ts

@@ -0,0 +1,105 @@
+import {
+	createBashToolDefinition,
+	getAgentDir,
+	type ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
+import { loadConfig, type PwshNativeConfig } from "./config.ts";
+import { createPowerShellOperations } from "./operations.ts";
+import { resolvePowerShellRuntime, type PowerShellRuntime } from "./runtime.ts";
+
+const DISCOVERY_TOOLS = ["ls", "find", "grep"] as const;
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+export function selectActiveTools(
+	activeTools: readonly string[],
+	preserveDiscoveryTools: boolean,
+	pwshAvailable: boolean,
+): string[] {
+	const disabled = new Set<string>(["bash", "pwsh"]);
+	if (!preserveDiscoveryTools) {
+		for (const name of DISCOVERY_TOOLS) disabled.add(name);
+	}
+	const selected = activeTools.filter((name) => !disabled.has(name));
+	if (pwshAvailable) selected.push("pwsh");
+	return [...new Set(selected)];
+}
+
+function toolDescription(runtime: PowerShellRuntime, config: PwshNativeConfig): string {
+	const elevation = config.elevationGuidance
+		? " Elevation guidance is enabled, but elevate only after an explicit user request."
+		: " Do not elevate unless the user explicitly requests it.";
+	return `Execute a native PowerShell 7 command on Windows with PowerShell ${runtime.version} (${runtime.executable}). Returns stdout and stderr. Output is truncated to the last 2000 lines or 50KB, whichever is reached first; full truncated output is saved to a temporary file. Commands have no default timeout; set timeout in seconds when needed.${elevation}`;
+}
+
+function unavailableUserCommand(reason: string) {
+	return {
+		result: {
+			output: `pi-pwsh-native is unavailable: ${reason}`,
+			exitCode: 1,
+			cancelled: false,
+			truncated: false,
+		},
+	};
+}
+
+export default function piPwshNative(pi: ExtensionAPI): void {
+	if (process.platform !== "win32") {
+		pi.on("session_start", (_event, ctx) => {
+			ctx.ui.notify("pi-pwsh-native is Windows-only; no tools were changed.", "warning");
+		});
+		return;
+	}
+
+	let config: PwshNativeConfig | undefined;
+	let runtime: PowerShellRuntime | undefined;
+	let setupError: string | undefined;
+	try {
+		config = loadConfig({ agentDir: getAgentDir() }).config;
+		runtime = resolvePowerShellRuntime(config);
+	} catch (error) {
+		setupError = errorMessage(error);
+	}
+
+	if (setupError || !config || !runtime) {
+		const reason = setupError ?? "unknown setup failure";
+		pi.on("session_start", (_event, ctx) => {
+			pi.setActiveTools(selectActiveTools(pi.getActiveTools(), true, false));
+			ctx.ui.notify(`pi-pwsh-native: ${reason} Bash was disabled; no shell fallback was activated.`, "error");
+		});
+		pi.on("user_bash", () => unavailableUserCommand(reason));
+		return;
+	}
+
+	const resolvedConfig = config;
+	const resolvedRuntime = runtime;
+	const operations = createPowerShellOperations(resolvedRuntime, resolvedConfig);
+
+	pi.on("session_start", (_event, ctx) => {
+		const definition = createBashToolDefinition(ctx.cwd, { operations });
+		pi.registerTool({
+			...definition,
+			name: "pwsh",
+			label: "pwsh",
+			description: toolDescription(resolvedRuntime, resolvedConfig),
+			promptSnippet: "Execute native PowerShell 7 commands on Windows",
+			promptGuidelines: [
+				"Use pwsh only when a shell is needed; write native PowerShell syntax and avoid Bash-only syntax or implicit Bash translation.",
+				"Prefer read, write, edit, ls, find, and grep over pwsh when a dedicated tool can complete the task more directly.",
+				"In pwsh, use $env:NAME for environment variables; single quotes are literal, double quotes interpolate, and the backtick is the escape character.",
+				"Prefer bounded rg or fd commands for repository search; tightly bound recursive Get-ChildItem and Select-String operations.",
+				"Do not elevate pwsh commands unless the user explicitly requests elevation.",
+				"Inspect PI_* environment variables in pwsh when current Pi model or session metadata is needed.",
+			],
+		});
+		pi.setActiveTools(
+			selectActiveTools(pi.getActiveTools(), resolvedConfig.preserveDiscoveryTools, true),
+		);
+	});
+
+	if (resolvedConfig.replaceUserBash) {
+		pi.on("user_bash", () => ({ operations }));
+	}
+}

package/src/operations.ts

@@ -0,0 +1,48 @@
+import type { BashOperations } from "@earendil-works/pi-coding-agent";
+import type { PwshNativeConfig } from "./config.ts";
+import type { PowerShellRuntime } from "./runtime.ts";
+import { buildPowerShellArguments, buildPowerShellSource } from "./powershell-source.ts";
+import { spawnAndStream } from "./process.ts";
+
+function findEnvironmentKey(env: NodeJS.ProcessEnv, name: string): string | undefined {
+	const normalized = name.toUpperCase();
+	return Object.keys(env).find((key) => key.toUpperCase() === normalized);
+}
+
+function setDefault(env: NodeJS.ProcessEnv, name: string, value: string): void {
+	const existing = findEnvironmentKey(env, name);
+	if (existing === undefined || env[existing] === undefined) env[name] = value;
+}
+
+export function createRuntimeEnvironment(
+	config: PwshNativeConfig,
+	baseEnvironment: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+	const env = { ...baseEnvironment };
+	if (config.pythonUtf8) {
+		setDefault(env, "PYTHONIOENCODING", "utf-8");
+		setDefault(env, "PYTHONUTF8", "1");
+	}
+	if (config.pythonUnbuffered) setDefault(env, "PYTHONUNBUFFERED", "1");
+	return env;
+}
+
+export function createPowerShellOperations(
+	runtime: PowerShellRuntime,
+	config: PwshNativeConfig,
+): BashOperations {
+	const args = buildPowerShellArguments(config);
+	return {
+		async exec(command, cwd, options) {
+			const source = buildPowerShellSource(command, config);
+			const result = await spawnAndStream(runtime.executable, args, cwd, {
+				onData: options.onData,
+				signal: options.signal,
+				timeout: options.timeout,
+				env: createRuntimeEnvironment(config, options.env ?? process.env),
+				stdin: Buffer.from(source, "utf8").toString("base64"),
+			});
+			return { exitCode: result.exitCode };
+		},
+	};
+}

package/src/powershell-source.ts

@@ -0,0 +1,41 @@
+import type { PwshNativeConfig } from "./config.ts";
+
+export const UTF8_PREFIX = [
+	"$__pi_utf8 = [System.Text.UTF8Encoding]::new($false)",
+	"[Console]::InputEncoding = $__pi_utf8",
+	"[Console]::OutputEncoding = $__pi_utf8",
+	"$OutputEncoding = $__pi_utf8",
+	"$PSStyle.OutputRendering = 'PlainText'",
+	"$global:LASTEXITCODE = $null",
+].join("; ") + "; ";
+
+/**
+ * Preserve a native program's real exit code. If no native program set
+ * LASTEXITCODE, map PowerShell's success state to 0/1.
+ *
+ * The leading newline detaches the epilogue from a trailing line comment. The
+ * leading semicolon also prevents a trailing backtick from joining the
+ * epilogue to the user's final command.
+ */
+export const EXIT_EPILOGUE =
+	"\n; $__pi_ok = $?; if ($null -ne $global:LASTEXITCODE) { exit $global:LASTEXITCODE } else { exit ($__pi_ok ? 0 : 1) }";
+
+export function buildPowerShellSource(command: string, config: PwshNativeConfig): string {
+	const strict = config.strictMode ? "$ErrorActionPreference = 'Stop'; " : "";
+	return `${UTF8_PREFIX}${strict}${command}${EXIT_EPILOGUE}`;
+}
+
+export const SOURCE_BOOTSTRAP =
+	"$__pi_source = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String([Console]::In.ReadToEnd())); & ([ScriptBlock]::Create($__pi_source))";
+
+export function buildPowerShellArguments(config: PwshNativeConfig): string[] {
+	const args = ["-NoLogo"];
+	if (!config.loadProfile) args.push("-NoProfile");
+	args.push("-NonInteractive");
+	if (config.executionPolicy) args.push("-ExecutionPolicy", config.executionPolicy);
+	// PowerShell decodes `-Command -` input with the console code page before a
+	// UTF-8 prelude can run. Transporting UTF-8 source as base64 over stdin keeps
+	// the bootstrap ASCII-only, preserves Unicode, and avoids command-line limits.
+	args.push("-Command", SOURCE_BOOTSTRAP);
+	return args;
+}

package/src/process.ts

@@ -0,0 +1,176 @@
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import { spawn, type ChildProcess } from "node:child_process";
+
+const MAX_TIMEOUT_MS = 2_147_483_647;
+const MAX_TIMEOUT_SECONDS = MAX_TIMEOUT_MS / 1000;
+const EXIT_STDIO_GRACE_MS = 100;
+
+export interface SpawnOptions {
+	onData: (data: Buffer) => void;
+	signal?: AbortSignal;
+	timeout?: number;
+	env?: NodeJS.ProcessEnv;
+	stdin?: string;
+}
+
+function timeoutMilliseconds(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 greater than zero");
+	}
+	if (timeout > MAX_TIMEOUT_SECONDS) {
+		throw new Error(`Invalid timeout: maximum is ${MAX_TIMEOUT_SECONDS} seconds`);
+	}
+	return timeout * 1000;
+}
+
+/** Kill a Windows process and all descendants without interpolating a command string. */
+export function killProcessTree(pid: number | undefined): void {
+	if (!pid || !Number.isInteger(pid) || pid <= 0) return;
+	try {
+		spawn("taskkill.exe", ["/PID", String(pid), "/T", "/F"], {
+			stdio: "ignore",
+			windowsHide: true,
+		});
+	} catch {
+		try {
+			process.kill(pid, "SIGTERM");
+		} catch {
+			// The process may already have exited.
+		}
+	}
+}
+
+/**
+ * Resolve after process exit without waiting forever for stdout/stderr handles
+ * inherited by detached descendants. Active trailing output re-arms the short
+ * post-exit grace period.
+ */
+function waitForChildProcess(child: ChildProcess): Promise<number | null> {
+	return new Promise((resolve, reject) => {
+		let settled = false;
+		let exited = false;
+		let exitCode: number | null = null;
+		let postExitTimer: NodeJS.Timeout | undefined;
+		let stdoutEnded = child.stdout === null;
+		let stderrEnded = child.stderr === null;
+
+		const cleanup = () => {
+			if (postExitTimer) clearTimeout(postExitTimer);
+			child.removeListener("error", onError);
+			child.removeListener("exit", onExit);
+			child.removeListener("close", onClose);
+			child.stdout?.removeListener("end", onStdoutEnd);
+			child.stderr?.removeListener("end", onStderrEnd);
+			child.stdout?.removeListener("data", onData);
+			child.stderr?.removeListener("data", onData);
+		};
+		const finish = (code: number | null) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			child.stdout?.destroy();
+			child.stderr?.destroy();
+			resolve(code);
+		};
+		const maybeFinish = () => {
+			if (exited && stdoutEnded && stderrEnded) finish(exitCode);
+		};
+		const armGrace = () => {
+			if (postExitTimer) clearTimeout(postExitTimer);
+			postExitTimer = setTimeout(() => finish(exitCode), EXIT_STDIO_GRACE_MS);
+		};
+		const onData = () => {
+			if (exited && !settled) armGrace();
+		};
+		const onStdoutEnd = () => {
+			stdoutEnded = true;
+			maybeFinish();
+		};
+		const onStderrEnd = () => {
+			stderrEnded = true;
+			maybeFinish();
+		};
+		const onError = (error: Error) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			reject(error);
+		};
+		const onExit = (code: number | null) => {
+			exited = true;
+			exitCode = code;
+			maybeFinish();
+			if (!settled) armGrace();
+		};
+		const onClose = (code: number | null) => finish(code);
+
+		child.stdout?.once("end", onStdoutEnd);
+		child.stderr?.once("end", onStderrEnd);
+		child.stdout?.on("data", onData);
+		child.stderr?.on("data", onData);
+		child.once("error", onError);
+		child.once("exit", onExit);
+		child.once("close", onClose);
+	});
+}
+
+export async function spawnAndStream(
+	executable: string,
+	args: string[],
+	cwd: string,
+	options: SpawnOptions,
+): Promise<{ exitCode: number | null }> {
+	if (options.signal?.aborted) throw new Error("aborted");
+	const timeoutMs = timeoutMilliseconds(options.timeout);
+	try {
+		await access(cwd, constants.F_OK);
+	} catch {
+		throw new Error(`Working directory does not exist: ${cwd}`);
+	}
+
+	const child = spawn(executable, args, {
+		cwd,
+		env: options.env ?? process.env,
+		stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+		windowsHide: true,
+	});
+	if (options.stdin !== undefined) {
+		child.stdin?.on("error", () => {
+			// Process startup/termination errors are reported through child events.
+		});
+		child.stdin?.end(options.stdin, "utf8");
+	}
+
+	let timedOut = false;
+	let timeoutHandle: NodeJS.Timeout | undefined;
+	const onAbort = () => killProcessTree(child.pid);
+	const onStdout = (data: Buffer) => options.onData(data);
+	const onStderr = (data: Buffer) => options.onData(data);
+
+	try {
+		child.stdout?.on("data", onStdout);
+		child.stderr?.on("data", onStderr);
+		if (options.signal) {
+			if (options.signal.aborted) onAbort();
+			else options.signal.addEventListener("abort", onAbort, { once: true });
+		}
+		if (timeoutMs !== undefined) {
+			timeoutHandle = setTimeout(() => {
+				timedOut = true;
+				killProcessTree(child.pid);
+			}, timeoutMs);
+		}
+
+		const exitCode = await waitForChildProcess(child);
+		if (options.signal?.aborted) throw new Error("aborted");
+		if (timedOut) throw new Error(`timeout:${options.timeout}`);
+		return { exitCode };
+	} finally {
+		if (timeoutHandle) clearTimeout(timeoutHandle);
+		options.signal?.removeEventListener("abort", onAbort);
+		child.stdout?.removeListener("data", onStdout);
+		child.stderr?.removeListener("data", onStderr);
+	}
+}

package/src/runtime.ts

@@ -0,0 +1,117 @@
+import { existsSync } from "node:fs";
+import { win32 } from "node:path";
+import { spawnSync } from "node:child_process";
+import type { PwshNativeConfig } from "./config.ts";
+
+const KNOWN_PWSH_PATH = "C:\\Program Files\\PowerShell\\7\\pwsh.exe";
+const VERSION_PROBE = "[Console]::Out.Write($PSVersionTable.PSVersion.ToString())";
+
+export interface PowerShellRuntime {
+	executable: string;
+	version: string;
+}
+
+export interface RuntimeDependencies {
+	exists: (path: string) => boolean;
+	findOnPath: () => string[];
+	probe: (path: string) => string | null;
+}
+
+export class RuntimeError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "RuntimeError";
+	}
+}
+
+function defaultFindOnPath(): string[] {
+	const result = spawnSync("where.exe", ["pwsh.exe"], {
+		encoding: "utf8",
+		timeout: 5_000,
+		windowsHide: true,
+	});
+	if (result.error || result.status !== 0 || !result.stdout) return [];
+	return result.stdout
+		.split(/\r?\n/)
+		.map((path) => path.trim())
+		.filter(Boolean);
+}
+
+function defaultProbe(path: string): string | null {
+	const result = spawnSync(
+		path,
+		["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", VERSION_PROBE],
+		{
+			encoding: "utf8",
+			timeout: 5_000,
+			windowsHide: true,
+		},
+	);
+	if (result.error || result.status !== 0) return null;
+	const version = result.stdout.trim();
+	return /^\d+(?:\.\d+){1,3}(?:[-+][0-9A-Za-z.-]+)?$/.test(version) ? version : null;
+}
+
+const DEFAULT_DEPENDENCIES: RuntimeDependencies = {
+	exists: existsSync,
+	findOnPath: defaultFindOnPath,
+	probe: defaultProbe,
+};
+
+function majorVersion(version: string): number | null {
+	const match = /^(\d+)/.exec(version);
+	return match ? Number(match[1]) : null;
+}
+
+function uniquePaths(paths: string[]): string[] {
+	const seen = new Set<string>();
+	const result: string[] = [];
+	for (const path of paths) {
+		const normalized = win32.normalize(path);
+		const key = normalized.toLowerCase();
+		if (seen.has(key)) continue;
+		seen.add(key);
+		result.push(normalized);
+	}
+	return result;
+}
+
+export function resolvePowerShellRuntime(
+	config: PwshNativeConfig,
+	dependencies: RuntimeDependencies = DEFAULT_DEPENDENCIES,
+): PowerShellRuntime {
+	const explicit = config.executable !== "auto";
+	const candidates = explicit
+		? [config.executable]
+		: uniquePaths([...dependencies.findOnPath(), KNOWN_PWSH_PATH]);
+	const failures: string[] = [];
+
+	for (const candidate of candidates) {
+		const path = win32.normalize(candidate);
+		if (!win32.isAbsolute(path)) {
+			failures.push(`${path}: not an absolute path`);
+			continue;
+		}
+		if (!dependencies.exists(path)) {
+			failures.push(`${path}: file not found`);
+			continue;
+		}
+		const version = dependencies.probe(path);
+		if (!version) {
+			failures.push(`${path}: failed to start or returned an invalid version`);
+			continue;
+		}
+		const major = majorVersion(version);
+		if (major === null || major < 7) {
+			failures.push(`${path}: PowerShell ${version} is unsupported; version 7 or newer is required`);
+			continue;
+		}
+		return { executable: path, version };
+	}
+
+	const prefix = explicit
+		? `Configured PowerShell executable ${JSON.stringify(config.executable)} is unavailable.`
+		: "PowerShell 7 or newer was not found.";
+	const details = failures.length > 0 ? ` Checked: ${failures.join("; ")}.` : "";
+	throw new RuntimeError(`${prefix}${details} Install PowerShell 7 or configure an absolute pwsh.exe path.`);
+}