@akira-tl/forgerelay 0.9.4 → 0.10.0

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [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` 文件。
 

package/dist/cli/init.js

@@ -2,10 +2,13 @@ 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 { 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 +119,64 @@ 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 = [];
+        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");
+            }
+        }
         const installedManaged = installedManagedLanguageServers(files.dir);
         const selectedManaged = await prompts.multiselect({
             message: "Which Language Servers should ForgeRelay manage with npm?",
@@ -150,6 +211,7 @@ export async function runInit({ force }) {
             }
         }
         const config = {
+            ...files.config,
             host,
             port,
             allowedRoots,
@@ -158,6 +220,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 +237,13 @@ 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})`),
+                ]
+                : []),
             ...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,35 @@ 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) {
     // 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 "fish":
+        case "pwsh":
+        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);
         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: {

package/dist/mcp/server-instructions.js

@@ -1,3 +1,4 @@
+import { commandShellAgentInstruction } from "../runtime/shell/command-shell-runtime.js";
 export const toolNames = {
     openWorkspace: "open_workspace",
     closeWorkspace: "close_workspace",
@@ -14,7 +15,7 @@ export function buildShellMutationPolicy() {
     return "Shell commands may modify ordinary project files when that is a natural part of the user's requested development task. They may also perform external device or hardware mutations when the user's current request explicitly asks for the actual device-changing operation, including firmware flashing or equivalent persistent device updates; do not infer such authorization from a check, audit, probe, backup, verification, dry-run, or build-only request. Never use shell commands to modify security- or privilege-sensitive operating-system files or credential material such as /etc/sudoers, /etc/passwd, /etc/shadow, PAM or authentication policy, SSH private keys, or equivalent privileged system files. Modify configuration files through shell only when the user's request explicitly calls for that configuration change; do not infer permission merely because changing configuration would be convenient.";
 }
 export function buildServerInstructions(config) {
-    return joinInstructions(capabilityContractInstructions(config), selectedWorkflowInstructions(config), config.appendInstructions);
+    return joinInstructions(runtimePrivilegeInstructions(config), commandShellAgentInstruction(config.commandShellRuntime), capabilityContractInstructions(config), selectedWorkflowInstructions(config), config.appendInstructions);
 }
 export function buildToolDescriptions(config) {
     const skillCapability = config.skillsEnabled
@@ -34,6 +35,14 @@ export function buildToolDescriptions(config) {
         shellCommand: "Shell command to run with the local user's authority.",
     };
 }
+function runtimePrivilegeInstructions(config) {
+    if (!config.runtimePrivilege || config.runtimePrivilege.level === "standard")
+        return "";
+    const status = config.runtimePrivilege.level === "elevated"
+        ? "elevated operating-system privileges"
+        : "an unverified operating-system privilege level accepted through --allow-elevated";
+    return `Runtime security: ForgeRelay is running with ${status}. Agent and Hook shell commands inherit this authority. Do not perform system-wide, privileged, security-sensitive, or irreversible mutations unless the user's current request explicitly authorizes that exact change. This safety notice is mandatory and is not disabled by shell-guidance settings.`;
+}
 function capabilityContractInstructions(config) {
     const staleWorkspacePolicy = config.toolMode === "codex"
         ? ""

package/dist/runtime/config/config.js

@@ -4,6 +4,8 @@ import { join, resolve } from "node:path";
 import { expandHomePath } from "../../mcp/filesystem/roots.js";
 import { mergeHookConfigs, parseHookConfig } from "../../mcp/hooks/hooks.js";
 import { forgerelayAgentsDir, forgerelaySkillsDir, generateInstanceId, loadForgeRelayFiles, } from "./user-config.js";
+import { shellInstructionPath } from "../instructions/shell-instructions.js";
+import { resolveConfiguredCommandShellRuntime, } from "../shell/command-shell-runtime.js";
 const DEFAULT_OAUTH_ACCESS_TOKEN_TTL_SECONDS = 60 * 60;
 const DEFAULT_OAUTH_REFRESH_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60;
 const DEFAULT_ARTIFACT_MAX_FILE_BYTES = 100 * 1024 * 1024;
@@ -268,6 +270,7 @@ export function loadConfig(env = process.env) {
     const publicDeployment = resolvePublicDeployment(env, files.config, host, port);
     const publicBaseUrl = publicDeployment.canonicalBaseUrl;
     const proxyTrust = resolveProxyTrust(env, files.config, host, publicBaseUrl);
+    const commandShellRuntime = resolveConfiguredCommandShellRuntime(files.config.commandShell, process.platform, env);
     const derivedAllowedHosts = [
         "localhost",
         "127.0.0.1",
@@ -314,6 +317,9 @@ export function loadConfig(env = process.env) {
         systemInstructionsPath: parseSystemInstructionsPath(productEnv(env, "SYSTEM_INSTRUCTIONS_PATH") ?? files.config.systemInstructionsPath),
         hooks: mergeHookConfigs(parseHookConfig(files.config.hooks), parseHookConfig(files.hooks), files.hookFiles),
         logging: parseLoggingConfig(env, proxyTrust !== false),
+        commandShellRuntime,
+        shellInstructionsEnabled: files.config.shellInstructions !== false,
+        shellInstructionPath: shellInstructionPath(files.dir, commandShellRuntime.family),
     };
 }
 function numberConfigValue(value) {