@akira-tl/forgerelay 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.2.3] - 2026-08-09
+
+### Changed
+
+- Shell tools no longer carry a blanket prohibition against commands that modify files. `bash` and Codex `exec_command` may update ordinary project files when that is a natural part of the user's requested development task, including package managers, generators, and formatters.
+
+### Security
+
+- The Agent shell contract continues to prohibit mutation of security- or privilege-sensitive operating-system files and credential material such as `/etc/sudoers`, `/etc/passwd`, `/etc/shadow`, authentication policy, and SSH private keys; configuration-file changes through shell require an explicit user request.
+
 ## [0.2.2] - 2026-08-09
 
 ### Added

package/dist/mcp/server-instructions.js

@@ -11,6 +11,9 @@ export const toolNames = {
     ls: "ls",
     shell: "bash",
 };
+export function buildShellMutationPolicy() {
+    return "Shell commands may modify ordinary project files when that is a natural part of the user's requested development task. 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, context = {}) {
     return joinInstructions(capabilityContractInstructions(config, context), selectedWorkflowInstructions(config), config.appendInstructions);
 }
@@ -21,6 +24,7 @@ export function buildToolDescriptions(config) {
     const shellSurface = config.toolMode === "minimal"
         ? ` In minimal tool mode, ${toolNames.grep}, ${toolNames.glob}, and ${toolNames.ls} are disabled, so shell commands may be used for equivalent search and directory inspection.`
         : "";
+    const shellMutationPolicy = buildShellMutationPolicy();
     return {
         read: `Read a file inside an open workspace or the OS temp directory. Instruction files returned by ${toolNames.openWorkspace} and advertised skill files are also readable when applicable.${skillCapability} Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         write: `Create or completely overwrite a file inside an open workspace or the OS temp directory. Workspace paths may be relative; OS temp paths may be absolute. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
@@ -28,7 +32,7 @@ export function buildToolDescriptions(config) {
         rename: `Rename or move one file or directory inside an open workspace or the OS temp directory without overwriting an existing destination. Source and destination must both remain inside the permitted file roots. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         delete: `Delete one file or directory inside an open workspace or the OS temp directory. Non-empty directories require recursive=true. An allowed root itself cannot be deleted. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         applyPatch: `Apply one Codex-style patch inside an open workspace or the OS temp directory. Supports adding, overwriting, updating, deleting, and moving files. Workspace paths must remain relative; absolute paths are accepted only inside the OS temp directory. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
-        shell: `Run a shell command inside an open workspace.${shellSurface} Commands execute with the local user's authority; workspace filesystem containment does not make shell execution a sandbox. Do not use ${toolNames.shell} to create, move, rename, or delete project files; use ${toolNames.edit}, ${toolNames.write}, ${toolNames.rename}, or ${toolNames.delete} for file changes. Call ${toolNames.openWorkspace} first and pass workspaceId. This capability should only be exposed behind strong authentication.`,
+        shell: `Run a shell command inside an open workspace.${shellSurface} Commands execute with the local user's authority; workspace filesystem containment does not make shell execution a sandbox. ${shellMutationPolicy} Call ${toolNames.openWorkspace} first and pass workspaceId. This capability should only be exposed behind strong authentication.`,
         shellCommand: "Shell command to run with the local user's authority.",
     };
 }
@@ -41,6 +45,7 @@ function capabilityContractInstructions(config, context) {
         ? `When ${toolNames.openWorkspace} returns available skills and a task matches a skill, use ${toolNames.read} to read that skill's path before proceeding. Skill paths may be outside the workspace, but ${toolNames.read} only permits advertised SKILL.md files and files under already-loaded skill directories.`
         : "";
     const toolSurface = toolSurfaceInstructions(config);
+    const shellMutationPolicy = buildShellMutationPolicy();
     const hooks = "When a ForgeRelay tool result reports Hook results, tell the user which meaningful hooks ran and whether they passed or blocked the operation. Do not claim the requested operation succeeded when a blocking hook prevented it.";
     const artifact = config.artifactsEnabled && context.artifactDownloadSupported
         ? "When the user supplies or generates a file that is not present on the ForgeRelay host, use download_artifact with its native file value, the existing workspace ID, and a suitable relative destination path chosen from the user's request and project structure. The tool refuses to overwrite an existing destination and returns the normalized workspace-relative path. Use normal workspace tools when explicit inspection, replacement, movement, renaming, or deletion is needed. Do not recreate binary files with write/edit calls or place signed URLs, native file objects, base64 content, or invented host paths in shell commands or logs."
@@ -48,7 +53,7 @@ function capabilityContractInstructions(config, context) {
     const showChanges = config.widgets === "changes"
         ? "If the turn successfully modifies files by creating, editing, overwriting, deleting, moving, or applying patches, call show_changes exactly once for that workspace after the final related file change and before your final response so the user can inspect the aggregate diff for that turn. Do not call it after every individual file change; do not skip it because individual file-change tools already returned diffs."
         : "";
-    return joinInstructions(workspaceLifecycle, agents, skills, toolSurface, hooks, artifact, showChanges);
+    return joinInstructions(workspaceLifecycle, agents, skills, toolSurface, shellMutationPolicy, hooks, artifact, showChanges);
 }
 function toolSurfaceInstructions(config) {
     if (config.toolMode === "codex") {
@@ -73,7 +78,7 @@ function defaultWorkflowInstructions(config) {
     const inspection = config.toolMode === "full"
         ? `Prefer ${toolNames.read}, ${toolNames.grep}, ${toolNames.glob}, and ${toolNames.ls} for file inspection.`
         : `Use ${toolNames.shell} with command-line tools such as grep, rg, find, ls, and tree for search and directory inspection.`;
-    return joinInstructions(inspection, `Prefer ${toolNames.edit} for targeted content modifications, ${toolNames.write} only for new files or complete rewrites, ${toolNames.rename} for path moves, ${toolNames.delete} for removals, and ${toolNames.shell} for tests, builds, git inspection, package scripts, and commands that are better executed by the shell.`, `Do not create or modify files with ${toolNames.shell}; avoid shell redirection, heredocs, tee, sed -i, perl -i, node/python/ruby scripts, or any command whose purpose is to write project files.`);
+    return joinInstructions(inspection, `Prefer ${toolNames.edit} for targeted content modifications, ${toolNames.write} only for new files or complete rewrites, ${toolNames.rename} for path moves, ${toolNames.delete} for removals, and ${toolNames.shell} for tests, builds, git inspection, package scripts, generators, formatters, and commands that are better executed by the shell.`);
 }
 function joinInstructions(...parts) {
     return parts

package/dist/server.js

@@ -18,7 +18,7 @@ import { deletePath, renamePath } from "./file-mutations.js";
 import { isArtifactDownloadSupportedPlatform, registerArtifactTools, } from "./artifact-tools.js";
 import { loadConfig } from "./config.js";
 import { attachHookReports, HookRunner, runToolWithHooks } from "./hooks.js";
-import { buildServerInstructions, buildToolDescriptions, toolNames, } from "./mcp/server-instructions.js";
+import { buildServerInstructions, buildShellMutationPolicy, buildToolDescriptions, toolNames, } from "./mcp/server-instructions.js";
 import { createOpenAIIncomingArtifactAdapter, } from "./incoming-artifacts.js";
 import { logEvent, requestIp, requestPath, commandPreview, sessionIdPrefix, workspaceLogLabel, } from "./logger.js";
 import { editFileTool, findFilesTool, grepFilesTool, listDirectoryTool, readFileTool, runShellTool, writeFileTool, } from "./pi-tools.js";
@@ -370,7 +370,7 @@ function toolResultIsError(result) {
 function registerCodexProcessTools(server, config, workspaces, processSessions, hooks) {
     registerAppTool(server, "exec_command", {
         title: "Execute command",
-        description: "Run a command inside an open workspace. Returns its result when it exits during the yield window, otherwise returns a sessionId for write_stdin. Use this for file inspection, tests, builds, package scripts, and long-running processes. Call open_workspace first and pass workspaceId.",
+        description: `Run a command inside an open workspace. Returns its result when it exits during the yield window, otherwise returns a sessionId for write_stdin. Use this for file inspection, tests, builds, package scripts, generators, formatters, and long-running processes. ${buildShellMutationPolicy()} Call open_workspace first and pass workspaceId.`,
         inputSchema: {
             workspaceId: z.string().describe("Workspace identifier returned by open_workspace."),
             cmd: z.string().min(1).describe("Shell command to execute."),

package/docs/chatgpt-coding-workflow.md

@@ -172,6 +172,14 @@ Experimental `FORGERELAY_TOOL_MODE=codex` provides a smaller Codex-shaped
 surface including direct `rename`/`delete` path mutations alongside `apply_patch`,
 `exec_command`, and `write_stdin`.
 
+Shell commands are allowed to modify ordinary project files when that is a
+natural part of the user's requested development task; ForgeRelay does not apply
+a blanket ban to package managers, generators, formatters, or similar commands
+that write files. The Agent contract still prohibits shell mutation of
+security- or privilege-sensitive operating-system files and credential material,
+and requires an explicit user request before changing configuration files
+through `bash` or `exec_command`.
+
 ## Change review UI
 
 By default `FORGERELAY_WIDGETS=full` attaches ChatGPT Apps-compatible UI to the

package/docs/debugging.md

@@ -58,8 +58,8 @@ The acceptance checks:
 2. OAuth protected-resource and authorization-server discovery;
 3. unauthenticated `/mcp` rejection;
 4. dynamic OAuth client registration, PKCE Owner-password approval, and access-token exchange;
-5. MCP `initialize`, including package/server version consistency;
-6. `tools/list` for the full debug tool surface;
+5. MCP `initialize`, including package/server version consistency and the shell mutation safety contract;
+6. `tools/list` for the full debug tool surface, including the non-blanket `bash` mutation policy;
 7. a real checkout workspace with `write`, `read`, `rename`, `delete`, `bash`, and a deliberate failed `edit`;
 8. OS temp-directory `write` → `read` → `edit` → `rename` → `delete` over the same real MCP session, plus rejection of an arbitrary path outside the workspace/temp roots;
 9. a temporary Git repository with managed worktree creation, file modification, and `close_worktree`;

package/docs/security.md

@@ -97,6 +97,21 @@ repositories, local services, and other resources outside a narrow workspace
 sandbox, and MCP currently does not provide a clean universal interaction model
 for dynamically crossing such a boundary.
 
+The Agent-facing shell contract therefore does not ban every command that can
+change files. Commands may modify ordinary project files when that is a natural
+part of the user's requested development task, including package managers,
+generators, formatters, and similar tooling. The contract does prohibit shell
+mutation of security- or privilege-sensitive operating-system files and
+credential material such as `/etc/sudoers`, `/etc/passwd`, `/etc/shadow`, PAM or
+authentication policy, SSH private keys, and equivalent privileged targets.
+Configuration files may be changed through shell only when the user's request
+explicitly calls for that configuration change rather than merely making it a
+convenient implementation detail.
+
+This is an Agent execution policy, not an OS-level sandbox or command parser.
+Operators that need a stronger project-specific runtime gate can use blocking
+`BeforeTool` Hooks around `bash` or `exec_command`.
+
 The security model is therefore based on:
 
 - strong authentication;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",

package/scripts/debug/accept.mjs

@@ -83,6 +83,11 @@ try {
   assert.equal(initialized.message.result.serverInfo.name, "forgerelay");
   assert.equal(initialized.message.result.serverInfo.title, "ForgeRelay");
   assert.equal(initialized.message.result.serverInfo.version, packageJson.version);
+  const serverInstructions = initialized.message.result.instructions ?? "";
+  assert.match(serverInstructions, /Shell commands may modify ordinary project files/);
+  assert.match(serverInstructions, /\/etc\/sudoers/);
+  assert.match(serverInstructions, /configuration files through shell only when the user's request explicitly calls for that configuration change/);
+  assert.doesNotMatch(serverInstructions, /Do not create or modify files with bash/);
   pass(
     "MCP initialize",
     JSON.stringify(initialized.message.result.serverInfo),
@@ -106,6 +111,10 @@ try {
   for (const expected of ["open_workspace", "close_worktree", "read", "write", "edit", "rename", "delete", "grep", "glob", "ls", "bash"]) {
     assert.ok(toolNames.includes(expected), `missing debug tool ${expected}`);
   }
+  const bashTool = tools.find((tool) => tool.name === "bash");
+  assert.match(bashTool?.description ?? "", /may modify ordinary project files/);
+  assert.match(bashTool?.description ?? "", /\/etc\/sudoers/);
+  assert.doesNotMatch(bashTool?.description ?? "", /Do not use bash to create, move, rename, or delete project files/);
   pass("MCP tools/list", `${toolNames.length} tools: ${toolNames.join(", ")}`);
 
   const opened = callTool(oauth.accessToken, sessionId, 3, "open_workspace", {