@akira-tl/forgerelay 0.9.4 → 0.10.1

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.10.1] - 2026-09-05
+
+### Added
+
+- Added native PowerShell 7 (`pwsh`) execution for Agent commands, Hooks, and PTY sessions with one versioned Command Shell Runtime, no-profile invocation, PowerShell-native command semantics, and Windows packaged-shim acceptance in cloud CI.
+- Added an exact-release-tag PowerShell guidance Skill seeded into the ForgeRelay config Skills directory without bundling prompt templates into the npm package or overwriting user edits.
+
+## [0.10.0] - 2026-09-05
+
+### Added
+
+- Added a first-class Command Shell Runtime identity with launch-shell/fallback selection, explicit pinned shell executable support, owner-visible diagnostics, and one shared shell contract for Agent commands and Hooks.
+- Added editable ForgeRelay shell Instructions for PowerShell 7, Windows PowerShell 5.1, cmd, zsh, and fish. `forgerelay init` seeds exact-release-tag templates into the user config directory, preserves user edits, and projects loaded/disabled/unavailable state through the existing Workspace Instructions UI and context-delta path.
+
+### Security
+
+- ForgeRelay now refuses elevated root/Administrator/SYSTEM-equivalent runtime authority by default across supported platforms. Intentional elevated startup requires the invocation-scoped `--allow-elevated` acknowledgement and always exposes a mandatory Agent safety notice.
+
 ## [0.9.4] - 2026-09-04
 
 ### Added

package/README.md

@@ -222,7 +222,7 @@ Hook 是 ForgeRelay 的自动生命周期规则。首选方式是一个 Hook 一
 }
 ```
 
-命中 `BeforeTool` 后，Hook 只快速验证 clean working tree（含 untracked）、tag 与 package version 一致，以及本地 tag 指向当前 HEAD；成功才继续原始 `git push`，失败则直接阻断。Hook 不运行、也不要求本地 CI。tag 推送后由 GitHub Actions 的 Linux/macOS/Windows 矩阵执行权威验证，全部通过后才进入发布。`npm run release:verify` 仅作为可选的本地云端复现工具。Hook 结果会回到 Agent，Agent 应向用户说明重要 Hook 是否通过或阻断了操作。`report:false` 可以隐藏不重要的成功报告，但阻断失败始终可见。
+命中 `BeforeTool` 后，普通 tag push 的 Hook 只快速验证 clean working tree（含 untracked）、tag 与 package version 一致，以及本地 tag 指向当前 HEAD；成功才继续原始 `git push`，失败则直接阻断。force release-tag push 始终拒绝。对于失败发布后显式执行的 `git push --delete origin vX.Y.Z`，Hook 仅在当前 HEAD 有有效 `release:verify` proof，且联网确认 npm 对应版本与 GitHub Release 都不存在时允许删除；任一不可撤回产物存在或远端状态无法确认都会拒绝。因此仅有 tag 时可以重建同版本，一旦 GitHub Release 或包仓库版本存在就进入不可变状态。tag 推送后由 GitHub Actions 的 Linux/macOS/Windows 矩阵执行权威验证，全部通过后才进入发布。Hook 结果会回到 Agent，Agent 应向用户说明重要 Hook 是否通过或阻断了操作。`report:false` 可以隐藏不重要的成功报告，但阻断失败始终可见。
 
 旧的 inline `hooks` 和聚合 `hooks.json` 仍兼容；新配置建议都用独立 `hooks/*.json` 文件。
 
@@ -295,8 +295,9 @@ See [Security Model](docs/security.md) for the full boundary and threat model.
 | --- | --- | --- |
 | Linux | Supported | Requires Node, npm, Git, and Bash. |
 | macOS | Supported | Requires Node, npm, Git, and Bash. |
-| Windows with Git Bash, WSL, MSYS2, or Cygwin Bash | Supported | Git Bash is the simplest native Windows setup. |
-| Windows PowerShell or `cmd.exe` only | Not supported yet | Install Git Bash or use WSL. |
+| Windows with PowerShell 7 (`pwsh`) | Supported | Agent commands and Hooks use one native `pwsh` runtime without loading the user profile. |
+| Windows with Git Bash, WSL, MSYS2, or Cygwin Bash | Supported | Bash remains available as a compatibility path. |
+| Windows PowerShell 5.1 (`powershell.exe`) or `cmd.exe` only | Not supported yet | These runtimes are separate follow-up stages. |
 
 You can check the local runtime with:
 

package/capabilities/shell-processes/GUIDE.md

@@ -48,6 +48,6 @@ PTY 依赖 optional `node-pty`。缺少该依赖时 ForgeRelay 会明确报错
 
 ## Platform notes
 
-ForgeRelay shell runtime 需要 Bash。Windows 上原生 PowerShell 和 `cmd.exe` 当前不是该 runtime 的执行 shell；使用 Git Bash、WSL、MSYS2 或 Cygwin Bash，并用 `forgerelay doctor` 检查环境。
+ForgeRelay 在 Windows 上支持 PowerShell 7 (`pwsh`) 作为原生 Command Shell Runtime；非 TTY Agent 命令与 Hooks 使用同一个 `pwsh`，禁止加载用户 profile，PTY 也复用同一 executable。公共工具名仍保留为 `bash` 以兼容 Host contract，实际命令语言以 ForgeRelay 报告的 Command Shell Runtime 为准。Windows PowerShell 5.1 (`powershell.exe`) 与 `cmd.exe` 仍属于后续 runtime 阶段；Git Bash、WSL、MSYS2 或 Cygwin Bash 仍可作为 Bash 兼容路径。用 `forgerelay doctor` 检查当前 shell identity、version 与 executable。
 
 Shell 可以作为用户开发任务的一部分修改普通项目文件，但始终受 ForgeRelay core mutation/safety contract 约束。涉及 privileged OS files、credentials、configuration 或外部硬件持久写入时，不要用本指南替代 core authorization/safety 规则。

package/dist/cli/init.js

@@ -2,10 +2,14 @@ import { resolve } from "node:path";
 import * as prompts from "@clack/prompts";
 import { publicEndpointUrl } from "../mcp/oauth/public-url.js";
 import { expandHomePath } from "../mcp/filesystem/roots.js";
+import { detectLauncherCommandShell, } from "../runtime/shell/command-shell-runtime.js";
+import { seedShellInstructionFiles, shellInstructionFamiliesToSeed, } from "../runtime/instructions/shell-instructions.js";
+import { seedPowerShellSkill, } from "../runtime/instructions/powershell-skill.js";
 import { installManagedLanguageServers, installedManagedLanguageServers, managedLanguageServerOptions, } from "../lsp/runtime/managed-language-servers.js";
 import { generateInstanceId, generateOwnerToken, loadForgeRelayFiles, resolveSubagentsFlag, writeForgeRelayAuth, writeForgeRelayConfig, } from "../runtime/config/user-config.js";
 import { classifyClientFacingBaseUrl, compactPublicBaseUrlConfig, hasInsecureLanBaseUrl, isLoopbackBindAddress, normalizePublicBaseUrlsInput, setupBindAddress, SetupCancelledError, textPrompt, validateHttpsProxyBaseUrls, validateLanClientFacingBaseUrls, validatePort, } from "./setup-support.js";
-export async function runInit({ force }) {
+import { commandShellCompatibilityWarning, commandShellSetupOptions, customPinnedPreference, defaultCommandShellSetupChoice, followLauncherPreference, pinnedFamilyPreference, preservePinnedPreference, shellFamiliesForCustomSelection, } from "./shell/setup.js";
+export async function runInit({ force, version }) {
     const files = loadForgeRelayFiles();
     if (!force && files.configExists && files.authExists) {
         prompts.log.info(`ForgeRelay is already configured at ${files.dir}`);
@@ -116,6 +120,74 @@ export async function runInit({ force }) {
             }
             publicBaseUrl = compactPublicBaseUrlConfig(clientFacingBaseUrls);
         }
+        const launcherShell = detectLauncherCommandShell();
+        const selectedShellChoice = await prompts.select({
+            message: "Which command shell should Agent commands and Hooks use?",
+            initialValue: defaultCommandShellSetupChoice(files.config.commandShell),
+            options: commandShellSetupOptions(process.platform, files.config.commandShell, launcherShell),
+        });
+        if (prompts.isCancel(selectedShellChoice))
+            throw new SetupCancelledError();
+        let commandShell;
+        const shellChoice = selectedShellChoice;
+        if (shellChoice === "follow-launcher") {
+            commandShell = followLauncherPreference(files.config.commandShell, launcherShell);
+        }
+        else if (shellChoice === "keep-pinned") {
+            commandShell = preservePinnedPreference(files.config.commandShell);
+        }
+        else if (shellChoice === "custom") {
+            const customFamily = await prompts.select({
+                message: "Which command language does the custom executable implement?",
+                options: shellFamiliesForCustomSelection(),
+            });
+            if (prompts.isCancel(customFamily))
+                throw new SetupCancelledError();
+            const executable = await textPrompt({
+                message: "What is the command-shell executable path?",
+                placeholder: process.platform === "win32" ? "D:\\Portable\\PowerShell\\pwsh.exe" : "/opt/custom/bin/zsh",
+                defaultValue: "",
+                validate: (value) => value?.trim() ? undefined : "Enter an executable path.",
+            });
+            commandShell = customPinnedPreference(customFamily, executable);
+        }
+        else {
+            commandShell = pinnedFamilyPreference(shellChoice);
+        }
+        const shellWarning = commandShellCompatibilityWarning(commandShell.family);
+        if (shellWarning)
+            prompts.note(shellWarning, "Command shell compatibility");
+        const shellInstructionFamilies = shellInstructionFamiliesToSeed(process.platform, commandShell.family);
+        let shellInstructions = files.config.shellInstructions;
+        let shellInstructionSeedResults = [];
+        let powerShellSkillSeedResult;
+        if (shellInstructionFamilies.length > 0) {
+            const shellInstructionsAnswer = await prompts.confirm({
+                message: "Load ForgeRelay-provided extra Instructions for this command shell?",
+                initialValue: files.config.shellInstructions !== false,
+            });
+            if (prompts.isCancel(shellInstructionsAnswer))
+                throw new SetupCancelledError();
+            shellInstructions = shellInstructionsAnswer === true;
+            shellInstructionSeedResults = await seedShellInstructionFiles({
+                configDir: files.dir,
+                version,
+                families: shellInstructionFamilies,
+            });
+            const failedShellInstructions = shellInstructionSeedResults.filter((result) => result.status === "failed");
+            if (failedShellInstructions.length > 0) {
+                prompts.note(failedShellInstructions.map((result) => `${result.family}: ${result.error ?? "download failed"}\n${result.sourceUrl}`).join("\n\n"), "Shell Instructions unavailable");
+            }
+        }
+        if (commandShell.family === "pwsh") {
+            powerShellSkillSeedResult = await seedPowerShellSkill({
+                configDir: files.dir,
+                version,
+            });
+            if (powerShellSkillSeedResult.status === "failed") {
+                prompts.note(`${powerShellSkillSeedResult.error ?? "download failed"}\n${powerShellSkillSeedResult.sourceUrl}`, "PowerShell Skill unavailable");
+            }
+        }
         const installedManaged = installedManagedLanguageServers(files.dir);
         const selectedManaged = await prompts.multiselect({
             message: "Which Language Servers should ForgeRelay manage with npm?",
@@ -150,6 +222,7 @@ export async function runInit({ force }) {
             }
         }
         const config = {
+            ...files.config,
             host,
             port,
             allowedRoots,
@@ -158,6 +231,8 @@ export async function runInit({ force }) {
             trustedProxies,
             workflowInstructions: files.config.workflowInstructions,
             appendInstructions: files.config.appendInstructions,
+            commandShell,
+            shellInstructions,
             subagents: resolveSubagentsFlag(files.config),
             languageServers: files.config.languageServers,
             allowAgentLanguageServerInstall,
@@ -173,6 +248,16 @@ export async function runInit({ force }) {
             `Config: ${configPath}`,
             `Auth: ${authPath}`,
             `Bind: http://${config.host}:${config.port}`,
+            `Command shell: ${commandShell.mode} ${commandShell.family} (${commandShell.executable})`,
+            ...(shellInstructionFamilies.length > 0
+                ? [
+                    `Shell Instructions: ${shellInstructions ? "enabled" : "disabled"}`,
+                    ...shellInstructionSeedResults.map((result) => `Shell Instructions ${result.family}: ${result.status} (${result.path})`),
+                ]
+                : []),
+            ...(powerShellSkillSeedResult
+                ? [`PowerShell Skill: ${powerShellSkillSeedResult.status} (${powerShellSkillSeedResult.path})`]
+                : []),
             ...clientFacingBaseUrls.map((baseUrl, index) => `${index === 0 ? "Client-facing MCP URL" : "Client-facing MCP alias"}: ${publicEndpointUrl(baseUrl, "mcp").toString()}`),
         ];
         if (networkMode === "ssh") {

package/dist/cli/shell/setup.js

@@ -0,0 +1,99 @@
+import { defaultCommandShellSelection, normalizeCommandShellSelection, } from "../../runtime/shell/command-shell-runtime.js";
+export function commandShellSetupOptions(platform, current, launcher) {
+    const options = [];
+    if (current?.mode === "pinned") {
+        options.push({
+            value: "keep-pinned",
+            label: `Keep pinned ${current.family}`,
+            hint: current.executable,
+        });
+    }
+    options.push({
+        value: "follow-launcher",
+        label: "Follow the shell used to launch ForgeRelay",
+        hint: launcher
+            ? `Detected ${launcher.family ?? "shell"}: ${launcher.executable}`
+            : "Use the recorded fallback when no launcher shell can be identified.",
+    });
+    const families = platform === "win32"
+        ? ["pwsh", "powershell", "cmd", "bash"]
+        : ["bash", "zsh", "fish", "sh"];
+    for (const family of families) {
+        options.push({
+            value: family,
+            label: shellFamilyLabel(family),
+            hint: family === "bash" && platform !== "win32"
+                ? "Recommended compatibility path"
+                : undefined,
+        });
+    }
+    options.push({
+        value: "custom",
+        label: "Custom executable path",
+        hint: "Pin a portable/green install or a shell-development test binary.",
+    });
+    return options;
+}
+export function defaultCommandShellSetupChoice(current) {
+    return current?.mode === "pinned" ? "keep-pinned" : "follow-launcher";
+}
+export function followLauncherPreference(current, launcher, platform = process.platform, environment = process.env) {
+    const fallback = launcher
+        ?? (current?.mode === "follow-launcher" ? current : undefined)
+        ?? defaultCommandShellSelection(platform === "win32" ? "cmd" : "bash", platform, environment);
+    const normalized = normalizeCommandShellSelection(fallback, platform, environment, true);
+    const family = normalized.family ?? fallback.family;
+    if (!family)
+        throw new Error(`Unable to identify command-shell family for ${normalized.executable}.`);
+    return {
+        mode: "follow-launcher",
+        family,
+        executable: normalized.executable,
+    };
+}
+export function pinnedFamilyPreference(family, platform = process.platform, environment = process.env) {
+    const normalized = normalizeCommandShellSelection(defaultCommandShellSelection(family, platform, environment), platform, environment, true);
+    return {
+        mode: "pinned",
+        family,
+        executable: normalized.executable,
+    };
+}
+export function customPinnedPreference(family, executable, platform = process.platform, environment = process.env) {
+    const normalized = normalizeCommandShellSelection({ family, executable }, platform, environment, true);
+    return {
+        mode: "pinned",
+        family,
+        executable: normalized.executable,
+    };
+}
+export function preservePinnedPreference(current, platform = process.platform, environment = process.env) {
+    if (!current || current.mode !== "pinned") {
+        throw new Error("No pinned command-shell selection is available to preserve.");
+    }
+    return customPinnedPreference(current.family, current.executable, platform, environment);
+}
+export function commandShellCompatibilityWarning(family) {
+    if (family === "zsh") {
+        return "zsh is supported as an explicit command runtime, but Bash remains ForgeRelay's primary POSIX compatibility target. Agent commands and Hooks must use zsh syntax.";
+    }
+    if (family === "fish") {
+        return "fish may be selected explicitly, but ForgeRelay compatibility is less mature than Bash and native fish execution is not enabled until its runtime adapter is available. Agent commands and Hooks must use fish syntax when enabled.";
+    }
+    return undefined;
+}
+export function shellFamiliesForCustomSelection() {
+    return ["bash", "zsh", "fish", "sh", "pwsh", "powershell", "cmd"]
+        .map((family) => ({ value: family, label: shellFamilyLabel(family) }));
+}
+function shellFamilyLabel(family) {
+    switch (family) {
+        case "bash": return "Bash";
+        case "zsh": return "zsh";
+        case "fish": return "fish";
+        case "sh": return "POSIX sh";
+        case "pwsh": return "PowerShell 7 (pwsh)";
+        case "powershell": return "Windows PowerShell 5.1";
+        case "cmd": return "cmd.exe";
+    }
+}

package/dist/cli.js

@@ -21,21 +21,31 @@ import { parseSubagentRunArgs } from "./subagents/cli-target.js";
 import { ensureForgeRelayInstanceId, loadForgeRelayFiles, removeForgeRelayRemote, renameForgeRelayRemote, writeForgeRelayConfig, writeForgeRelayRemote, } from "./runtime/config/user-config.js";
 import { shutdownHttpServer } from "./mcp/server/transport/server-shutdown.js";
 import { publicEndpointUrl } from "./mcp/oauth/public-url.js";
+import { assertRuntimePrivilegeAllowed, detectRuntimePrivilege, elevatedRuntimeWarning, formatRuntimePrivilege, } from "./runtime/security/runtime-privilege.js";
+import { formatCommandShellRuntime } from "./runtime/shell/command-shell-runtime.js";
 import { authenticateRemote, defaultRemoteAlias, isRemoteMcpUnauthorized, normalizeRemoteServiceTarget, refreshRemoteAuthentication, verifyRemoteMcp, } from "./workspaces/relay/auth/remote-auth.js";
 import { defaultSshRouteAlias, parseSshRoute, readRemoteOwnerToken, withRemoteServiceEndpoint, } from "./workspaces/relay/transport/remote-transport.js";
 import { assertSupportedNode, checkBashShell, checkGitAvailable, checkSqliteNative, nodeVersionStatus, normalizeOptionalPublicBaseUrl, } from "./cli/setup-support.js";
 const require = createRequire(import.meta.url);
 async function main(argv) {
     assertSupportedNode();
-    const [rawCommand, ...args] = argv;
-    const command = normalizeCommand(rawCommand);
+    const [rawCommand, ...rest] = argv;
+    const defaultServeFlag = rawCommand === "--allow-elevated";
+    const command = defaultServeFlag ? "serve" : normalizeCommand(rawCommand);
+    const args = defaultServeFlag ? argv : rest;
     switch (command) {
-        case "serve":
+        case "serve": {
+            const serveOptions = parseServeCommandArgs(args);
+            const runtimePrivilege = detectRuntimePrivilege();
+            assertRuntimePrivilegeAllowed(runtimePrivilege, serveOptions.allowElevated);
+            if (serveOptions.allowElevated)
+                console.warn(elevatedRuntimeWarning(runtimePrivilege));
             await ensureConfigured();
-            await serve();
+            await serve(runtimePrivilege);
             return;
+        }
         case "init":
-            await runInit({ force: args.includes("--force") });
+            await runInit({ force: args.includes("--force"), version: installedForgeRelayVersion() });
             return;
         case "doctor":
             await runDoctor();
@@ -74,6 +84,19 @@ function normalizeCommand(command) {
         return "version";
     throw new Error(`Unknown command: ${command}`);
 }
+function parseServeCommandArgs(args) {
+    let allowElevated = false;
+    for (const arg of args) {
+        if (arg === "--allow-elevated") {
+            if (allowElevated)
+                throw new Error("--allow-elevated may only be supplied once.");
+            allowElevated = true;
+            continue;
+        }
+        throw new Error(`Unknown serve option: ${arg}`);
+    }
+    return { allowElevated };
+}
 async function ensureConfigured() {
     const files = loadForgeRelayFiles();
     if (files.configExists && files.authExists) {
@@ -94,9 +117,9 @@ async function ensureConfigured() {
             "Or provide FORGERELAY_OAUTH_OWNER_TOKEN and FORGERELAY_ALLOWED_ROOTS.",
         ].join("\n"));
     }
-    await runInit({ force: false });
+    await runInit({ force: false, version: installedForgeRelayVersion() });
 }
-async function serve() {
+async function serve(runtimePrivilege) {
     const sqliteStatus = checkSqliteNative();
     if (sqliteStatus !== "ok") {
         throw new Error([
@@ -109,6 +132,7 @@ async function serve() {
     }
     const { createServer } = await import("./server.js");
     const config = loadConfig();
+    config.runtimePrivilege = runtimePrivilege;
     const runtimeLease = acquireRuntimeLease(config.stateDir);
     let server;
     try {
@@ -128,6 +152,8 @@ async function serve() {
             console.warn("warning: Host header allowlist is disabled because FORGERELAY_ALLOWED_HOSTS=*");
         }
         console.log("auth: Owner password approval required");
+        console.log(`command shell: ${formatCommandShellRuntime(config.commandShellRuntime)}`);
+        console.log(`runtime privilege: ${formatRuntimePrivilege(runtimePrivilege)}`);
         console.log(`logging: ${config.logging.level} ${config.logging.format}`);
         if (config.subagents) {
             console.log(`subagent providers: ${formatSubagentProviderAvailabilitySummary(subagentProviders)}`);
@@ -325,6 +351,7 @@ async function runDoctor() {
     console.log(`Node: ${process.version} (${nodeVersionStatus()})`);
     console.log(`Node ABI: ${process.versions.modules}`);
     console.log(`Platform: ${process.platform} ${process.arch}`);
+    console.log(`Runtime privilege: ${formatRuntimePrivilege(detectRuntimePrivilege())}`);
     console.log(`Git: ${checkGitAvailable()}`);
     console.log(`Bash shell: ${checkBashShell()}`);
     console.log(`SQLite native dependency: ${checkSqliteNative()}`);
@@ -334,6 +361,7 @@ async function runDoctor() {
         console.log(`Client-facing base URLs: ${config.publicBaseUrls.join(", ")}`);
         console.log(`Client-facing base URL: ${config.publicBaseUrl}`);
         console.log(`Client-facing MCP URL: ${publicEndpointUrl(config.publicBaseUrl, "mcp").toString()}`);
+        console.log(`Command shell: ${formatCommandShellRuntime(config.commandShellRuntime)}`);
         console.log(`Tool mode: ${config.toolMode}`);
         console.log(`Widgets: ${config.widgets}`);
         console.log(`Trust proxy: ${config.proxyTrust === false ? "off" : config.proxyTrust.join(", ")}`);
@@ -377,6 +405,8 @@ function printHelp() {
         "Usage:",
         "  forgerelay                 Run first-time setup if needed, then start the server",
         "  forgerelay serve           Start the server",
+        "  forgerelay serve --allow-elevated",
+        "                            Explicitly allow this invocation to run with elevated/unknown OS privilege",
         "  forgerelay init            Create or update ~/.forgerelay/config.json and auth.json",
         "  forgerelay doctor          Show config, runtime, and native dependency status",
         "  forgerelay config get      Print persisted config",
@@ -570,12 +600,15 @@ function printAgentsHelp() {
         "  forgerelay agents show <id>",
     ].join("\n"));
 }
-function printVersion() {
+function installedForgeRelayVersion() {
     const packageJson = require("../package.json");
-    if (typeof packageJson.version !== "string") {
+    if (typeof packageJson.version !== "string" || packageJson.version.length === 0) {
         throw new Error("Unable to read ForgeRelay package version.");
     }
-    console.log(packageJson.version);
+    return packageJson.version;
+}
+function printVersion() {
+    console.log(installedForgeRelayVersion());
 }
 main(process.argv.slice(2)).catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));

package/dist/mcp/hooks/hooks.js

@@ -2,7 +2,8 @@ import { readFile, readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { performance } from "node:perf_hooks";
 import { commandPreview, logEvent, workspaceLogLabel } from "../../runtime/logging/logger.js";
-import { resolveShellCommand } from "../process/process-platform.js";
+import { resolveCompatibilityCommandShellRuntime, snapshotCommandShellRuntime, } from "../../runtime/shell/command-shell-runtime.js";
+import { resolveShellCommandForRuntime } from "../process/process-platform.js";
 import { executeHookCommand, hookFailureOutput } from "./command-runner.js";
 export const HOOK_EVENTS = [
     "WorkspaceOpen",
@@ -212,11 +213,13 @@ export class HookRunner {
     logging;
     baseEnv;
     resultDecorator;
-    constructor(hooks, logging, baseEnv = process.env, resultDecorator) {
+    commandShellRuntime;
+    constructor(hooks, logging, baseEnv = process.env, resultDecorator, commandShellRuntime) {
         this.hooks = hooks;
         this.logging = logging;
         this.baseEnv = baseEnv;
         this.resultDecorator = resultDecorator;
+        this.commandShellRuntime = snapshotCommandShellRuntime(commandShellRuntime ?? resolveCompatibilityCommandShellRuntime(process.platform, baseEnv));
     }
     decorateResult(workspaceId, result) {
         return (this.resultDecorator?.(workspaceId, result) ?? result);
@@ -274,7 +277,7 @@ export class HookRunner {
     async runHandler(event, handler, index, invocation, scope, signal) {
         const startedAt = performance.now();
         const name = handler.name ?? `${event} handler ${index + 1}`;
-        const shell = resolveShellCommand(handler.command, process.platform, this.baseEnv);
+        const shell = resolveShellCommandForRuntime(handler.command, this.commandShellRuntime);
         const detached = process.platform !== "win32";
         const env = hookEnvironment(this.baseEnv, event, invocation);
         try {

package/dist/mcp/process/process-platform.js

@@ -1,5 +1,5 @@
-import { basename } from "node:path";
 import { spawnSync } from "node:child_process";
+import { resolveCompatibilityCommandShellRuntime, } from "../../runtime/shell/command-shell-runtime.js";
 const defaultProcessTreeRuntime = {
     platform: process.platform,
     killGroup: (pid, signal) => process.kill(-pid, signal),
@@ -11,37 +11,45 @@ const defaultProcessTreeRuntime = {
         return !result.error && result.status === 0;
     },
 };
-const POSIX_SHELLS = new Set(["ash", "dash", "ksh", "sh"]);
 export function resolveShellCommand(command, platform = process.platform, environment = process.env) {
-    if (platform === "win32") {
-        return {
-            executable: environment.ComSpec ?? environment.COMSPEC ?? "cmd.exe",
-            // Match Node's native `spawn(command, { shell: cmd.exe })` quoting.
-            // cmd.exe /S applies special quote stripping, so the whole command must
-            // be wrapped even when the executable inside it is already quoted.
-            args: ["/d", "/s", "/c", `"${command}"`],
-            windowsVerbatimArguments: true,
-        };
-    }
+    return resolveShellCommandForRuntime(command, resolveCompatibilityCommandShellRuntime(platform, environment));
+}
+export function resolveShellCommandForRuntime(command, runtime, options = {}) {
     // Agent and Hook commands must not source the user's interactive/login shell
     // configuration. ForgeRelay already inherits PATH and other environment from
     // the process that launched the server; re-running zsh/bash as a login shell
     // can inject prompts, banners, aliases, plugins, or other user-only behavior.
-    const configuredShell = environment.FORGERELAY_COMMAND_SHELL?.trim();
-    const executable = configuredShell || (platform === "linux" || platform === "darwin"
-        ? "/bin/bash"
-        : "/bin/sh");
-    const shellName = basename(executable);
-    if (shellName === "bash") {
-        return { executable, args: ["--noprofile", "--norc", "-c", command] };
-    }
-    if (shellName === "zsh") {
-        return { executable, args: ["-f", "-c", command] };
-    }
-    if (POSIX_SHELLS.has(shellName)) {
-        return { executable, args: ["-c", command] };
+    switch (runtime.family) {
+        case "cmd":
+            return {
+                executable: runtime.executable,
+                // Match Node's native `spawn(command, { shell: cmd.exe })` quoting.
+                // cmd.exe /S applies special quote stripping, so the whole command must
+                // be wrapped even when the executable inside it is already quoted.
+                args: ["/d", "/s", "/c", `"${command}"`],
+                windowsVerbatimArguments: true,
+            };
+        case "bash":
+            return { executable: runtime.executable, args: ["--noprofile", "--norc", "-c", command] };
+        case "zsh":
+            return { executable: runtime.executable, args: ["-f", "-c", command] };
+        case "sh":
+            return { executable: runtime.executable, args: ["-c", command] };
+        case "pwsh":
+            return {
+                executable: runtime.executable,
+                args: [
+                    "-NoLogo",
+                    "-NoProfile",
+                    ...(options.interactive ? [] : ["-NonInteractive"]),
+                    "-Command",
+                    command,
+                ],
+            };
+        case "fish":
+        case "powershell":
+            throw new Error(`Command shell runtime ${runtime.family} is identified but native execution support is not enabled in this release stage. ForgeRelay will not silently execute the command through another shell.`);
     }
-    return { executable: "/bin/sh", args: ["-c", command] };
 }
 export function terminateProcessTree(child, signal, detached, runtime = defaultProcessTreeRuntime) {
     if (runtime.platform === "win32" && child.pid) {

package/dist/mcp/process/process-sessions.js

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
-import { resolveShellCommand, terminateProcessTree } from "./process-platform.js";
+import { resolveShellCommandForRuntime, terminateProcessTree } from "./process-platform.js";
+import { resolveCompatibilityCommandShellRuntime, snapshotCommandShellRuntime } from "../../runtime/shell/command-shell-runtime.js";
 const DEFAULT_EXEC_YIELD_MS = 10_000;
 const DEFAULT_INTERACTIVE_YIELD_MS = 250;
 export const DEFAULT_POLL_YIELD_MS = 60_000;
@@ -210,6 +211,7 @@ export class ProcessManager {
     maxStartYieldMs;
     monotonicNow;
     outputAudit;
+    commandShellRuntime;
     nextProcessId = 1;
     constructor(options = {}) {
         this.maxBufferCharacters = options.maxBufferCharacters ?? DEFAULT_BUFFER_CHARACTERS;
@@ -227,6 +229,7 @@ export class ProcessManager {
         this.maxStartYieldMs = options.maxStartYieldMs ?? MAX_START_YIELD_MS;
         this.monotonicNow = options.monotonicNow ?? (() => performance.now());
         this.outputAudit = options.outputAudit;
+        this.commandShellRuntime = snapshotCommandShellRuntime(options.commandShellRuntime ?? resolveCompatibilityCommandShellRuntime());
     }
     async start(input) {
         input.signal?.throwIfAborted();
@@ -435,7 +438,7 @@ export class ProcessManager {
         };
     }
     startPipe(processEntry, input) {
-        const shell = resolveShellCommand(input.command);
+        const shell = resolveShellCommandForRuntime(input.command, this.commandShellRuntime);
         const detached = process.platform !== "win32";
         const child = spawn(shell.executable, shell.args, {
             cwd: input.cwd,
@@ -467,7 +470,7 @@ export class ProcessManager {
         catch {
             throw new Error("PTY support requires the optional node-pty dependency.");
         }
-        const shell = resolveShellCommand(input.command);
+        const shell = resolveShellCommandForRuntime(input.command, this.commandShellRuntime, { interactive: true });
         let pty;
         try {
             pty = nodePty.spawn(shell.executable, shell.args, {

package/dist/mcp/server/transport/http-server.js

@@ -71,7 +71,10 @@ export function createHttpServer(config, options, createMcpServer) {
         turnIdForConversation: (conversationScopeId, workspaceId) => activityQueries.currentTurnId(conversationScopeId, workspaceId),
     });
     const reviewCheckpoints = createReviewCheckpointManager();
-    const processSessions = new ProcessManager({ outputAudit: bashOutputStore });
+    const processSessions = new ProcessManager({
+        outputAudit: bashOutputStore,
+        commandShellRuntime: config.commandShellRuntime,
+    });
     const codeIntelligence = new CodeIntelligenceManager(config);
     const subagentProviders = config.subagents
         ? getSubagentProviderAvailabilitySnapshot()

package/dist/mcp/server/workspace/runtime/workspace-open-presentation.js

@@ -71,6 +71,10 @@ export async function presentLocalWorkspaceOpen(options, input, contextData) {
     const cardAvailableAgentsFiles = availableAgentsFiles.map((file) => ({
         path: formatAgentsPath(file.path, workspace.root),
     }));
+    const cardWorkspaceInstructions = workspace.workspaceInstructions.map((instruction) => ({
+        path: formatAgentsPath(instruction.path, workspace.root),
+        status: instruction.status,
+    }));
     const bootstrapComponents = new Set(effectiveBootstrapContextComponents);
     const visibleSkills = bootstrapComponents.has("skills") ? cardSkills : [];
     const visibleSkillDiagnostics = bootstrapComponents.has("skillDiagnostics")
@@ -185,6 +189,7 @@ export async function presentLocalWorkspaceOpen(options, input, contextData) {
         capabilityCatalog,
         agentsFiles: cardAgentsFiles,
         availableAgentsFiles: cardAvailableAgentsFiles,
+        workspaceInstructions: cardWorkspaceInstructions,
         skills: cardSkills,
         agentProviders: cardAgentProviders,
         agents: cardAgents,
@@ -193,6 +198,7 @@ export async function presentLocalWorkspaceOpen(options, input, contextData) {
             mode: workspace.mode,
             agentsFiles: cardAgentsFiles.length,
             availableAgentsFiles: cardAvailableAgentsFiles.length,
+            workspaceInstructions: cardWorkspaceInstructions.length,
             skills: cardSkills.length,
             capabilities: capabilityCatalog.length,
             agentProviders: cardAgentProviders.length,

package/dist/mcp/server/workspace/runtime/workspace-tools.js

@@ -26,7 +26,7 @@ export function registerWorkspaceAuxiliaryTools(options) {
         outputSchema: {
             path: z.string(),
             content: z.string(),
-            status: z.enum(["loaded", "available"]),
+            status: z.enum(["loaded", "available", "disabled"]),
         },
         _meta: { ui: { visibility: ["app"] } },
         annotations: {