@akira-tl/forgerelay 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -4,6 +4,26 @@ 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
+
+- First-class `rename` and `delete` MCP tools for files and directories in workspace or OS-temp file roots, including direct availability in minimal, full, and Codex tool modes.
+
+### Security
+
+- `rename` validates both source and destination canonical roots and refuses existing destinations; `delete` refuses allowed roots themselves and requires explicit `recursive: true` for non-empty directory trees.
+
 ## [0.2.1] - 2026-08-09
 
 ### Changed

package/dist/file-mutations.js

@@ -0,0 +1,50 @@
+import { lstat, realpath, rename, rm, rmdir, unlink } from "node:fs/promises";
+import { resolve } from "node:path";
+import { expandHomePath, resolveCanonicalAllowedPath } from "./roots.js";
+export async function renamePath(input, context) {
+    const source = await resolveCanonicalAllowedPath(input.path, context.cwd, context.allowedRoots);
+    await assertNotAllowedRootItself(source, context.allowedRoots, input.path);
+    const destination = await resolveCanonicalAllowedPath(input.newPath, context.cwd, context.allowedRoots);
+    await assertDestinationMissing(destination, input.newPath);
+    await lstat(source);
+    await rename(source, destination);
+    return { path: input.path, newPath: input.newPath };
+}
+export async function deletePath(input, context) {
+    const path = await resolveCanonicalAllowedPath(input.path, context.cwd, context.allowedRoots);
+    await assertNotAllowedRootItself(path, context.allowedRoots, input.path);
+    const entry = await lstat(path);
+    const recursive = input.recursive ?? false;
+    if (entry.isDirectory()) {
+        if (recursive) {
+            await rm(path, { recursive: true, force: false });
+        }
+        else {
+            await rmdir(path);
+        }
+    }
+    else {
+        await unlink(path);
+    }
+    return { path: input.path, recursive };
+}
+async function assertDestinationMissing(path, inputPath) {
+    try {
+        await lstat(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    throw new Error(`Rename destination already exists: ${inputPath}`);
+}
+async function assertNotAllowedRootItself(path, allowedRoots, inputPath) {
+    const canonicalPath = await realpath(path);
+    for (const root of allowedRoots) {
+        const canonicalRoot = await realpath(resolve(expandHomePath(root)));
+        if (canonicalPath === canonicalRoot) {
+            throw new Error(`Cannot rename or delete an allowed root itself: ${inputPath}`);
+        }
+    }
+}

package/dist/mcp/server-instructions.js

@@ -4,11 +4,16 @@ export const toolNames = {
     read: "read",
     write: "write",
     edit: "edit",
+    rename: "rename",
+    delete: "delete",
     grep: "grep",
     glob: "glob",
     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);
 }
@@ -19,24 +24,28 @@ 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.`,
         edit: `Edit one file inside an open workspace or the OS temp directory by replacing exact text blocks. Each oldText must match a unique, non-overlapping region of the original file. Workspace paths may be relative; OS temp paths may be absolute. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
+        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 or modify project files; use ${toolNames.edit} or ${toolNames.write} 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.",
     };
 }
 function capabilityContractInstructions(config, context) {
     const workspaceLifecycle = config.toolMode === "codex"
         ? `Use ForgeRelay as a local coding workspace. Default to the user's existing checkout and reuse its workspaceId. Only open mode=\"worktree\" when the user explicitly asks for isolated or parallel work. Managed worktrees use dedicated forgerelay/* branches, not detached HEADs. When work in a managed worktree is complete and verified, call ${toolNames.closeWorktree}; it commits remaining worktree changes, fast-forwards the original target branch only when safe, then removes the worktree and its branch. If the target branch diverged or the source checkout is dirty, closing is refused and the worktree is preserved.`
-        : `Use ForgeRelay as a local coding workspace. Default to the user's existing checkout and reuse its workspaceId for later file, search, edit, write, show-changes, and shell tools. Only open mode=\"worktree\" when the user explicitly asks for isolated or parallel work. Managed worktrees use dedicated forgerelay/* branches, not detached HEADs. When work in a managed worktree is complete and verified, call ${toolNames.closeWorktree}; it commits remaining worktree changes, fast-forwards the original target branch only when safe, then removes the worktree and its branch. If the target branch diverged or the source checkout is dirty, closing is refused and the worktree is preserved.`;
+        : `Use ForgeRelay as a local coding workspace. Default to the user's existing checkout and reuse its workspaceId for later file, search, edit, write, rename, delete, show-changes, and shell tools. Only open mode=\"worktree\" when the user explicitly asks for isolated or parallel work. Managed worktrees use dedicated forgerelay/* branches, not detached HEADs. When work in a managed worktree is complete and verified, call ${toolNames.closeWorktree}; it commits remaining worktree changes, fast-forwards the original target branch only when safe, then removes the worktree and its branch. If the target branch diverged or the source checkout is dirty, closing is refused and the worktree is preserved.`;
     const agents = `Follow instructions returned by ${toolNames.openWorkspace}. Before working under a path listed in availableAgentsFiles, use ${toolNames.read} to inspect that instruction file and follow it.`;
     const skills = config.skillsEnabled
         ? `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."
@@ -44,11 +53,11 @@ 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") {
-        return `In codex tool mode, workspace file and command operations use ${toolNames.read}, apply_patch, exec_command, and write_stdin.`;
+        return `In codex tool mode, workspace file and command operations use ${toolNames.read}, ${toolNames.rename}, ${toolNames.delete}, apply_patch, exec_command, and write_stdin.`;
     }
     if (config.toolMode === "full") {
         return `In full tool mode, dedicated ${toolNames.grep}, ${toolNames.glob}, and ${toolNames.ls} inspection tools are available alongside the core workspace tools.`;
@@ -64,12 +73,12 @@ function selectedWorkflowInstructions(config) {
 }
 function defaultWorkflowInstructions(config) {
     if (config.toolMode === "codex") {
-        return `Use ${toolNames.read} for direct file reads, apply_patch for all file modifications, exec_command for inspection, tests, builds, and other commands, and write_stdin to poll or interact with running processes.`;
+        return `Use ${toolNames.read} for direct file reads, ${toolNames.rename} and ${toolNames.delete} for direct path moves or removals, apply_patch for content modifications, exec_command for inspection, tests, builds, and other commands, and write_stdin to poll or interact with running processes.`;
     }
     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 modifications, ${toolNames.write} only for new files or complete rewrites, 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

@@ -14,10 +14,11 @@ import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE, } from "@mode
 import express from "express";
 import * as z from "zod/v4";
 import { applyPatch } from "./apply-patch.js";
+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";
@@ -369,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."),
@@ -1069,6 +1070,148 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             });
         });
     }
+    registerAppTool(server, toolNames.rename, {
+        title: "Rename path",
+        description: toolDescriptions.rename,
+        inputSchema: {
+            workspaceId: z.string().describe("Workspace identifier returned by open_workspace."),
+            path: z.string().describe("Source file or directory path relative to the workspace root, or absolute inside the OS temp directory."),
+            newPath: z.string().describe("Destination path relative to the workspace root, or absolute inside the OS temp directory. The destination must not already exist."),
+        },
+        outputSchema: resultOutputSchema({
+            status: z.literal("renamed"),
+            path: z.string(),
+            newPath: z.string(),
+        }),
+        ...toolWidgetDescriptorMeta(config, "edit"),
+        annotations: EDIT_TOOL_ANNOTATIONS,
+    }, async ({ workspaceId, path, newPath }, extra) => {
+        const workspace = workspaces.getWorkspace(workspaceId);
+        return runToolWithHooks(hooks, {
+            tool: toolNames.rename,
+            invocation: workspaceHookInvocation(workspace),
+            payload: { path, newPath, paths: [path, newPath] },
+            changedPaths: () => [path, newPath],
+            operation: async () => {
+                const startedAt = performance.now();
+                try {
+                    await renamePath({ path, newPath }, {
+                        cwd: workspace.root,
+                        allowedRoots: workspaces.fileToolRoots(workspace),
+                    });
+                    const result = `Renamed ${path} to ${newPath}.`;
+                    const content = [textBlock(result)];
+                    logToolCall(config, {
+                        tool: toolNames.rename,
+                        ...workspaceLogContext(workspace, extra.sessionId),
+                        path: `${path} -> ${newPath}`,
+                        success: true,
+                        durationMs: Math.round(performance.now() - startedAt),
+                    });
+                    return {
+                        content,
+                        _meta: {
+                            tool: toolNames.rename,
+                            card: {
+                                workspaceId,
+                                path: newPath,
+                                summary: { previousPath: path },
+                                payload: { content },
+                            },
+                        },
+                        structuredContent: {
+                            result,
+                            status: "renamed",
+                            path,
+                            newPath,
+                        },
+                    };
+                }
+                catch (error) {
+                    logToolCall(config, {
+                        tool: toolNames.rename,
+                        ...workspaceLogContext(workspace, extra.sessionId),
+                        path: `${path} -> ${newPath}`,
+                        success: false,
+                        durationMs: Math.round(performance.now() - startedAt),
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    throw error;
+                }
+            },
+        });
+    });
+    registerAppTool(server, toolNames.delete, {
+        title: "Delete path",
+        description: toolDescriptions.delete,
+        inputSchema: {
+            workspaceId: z.string().describe("Workspace identifier returned by open_workspace."),
+            path: z.string().describe("File or directory path relative to the workspace root, or absolute inside the OS temp directory."),
+            recursive: z.boolean().optional().describe("Delete a non-empty directory tree. Defaults to false."),
+        },
+        outputSchema: resultOutputSchema({
+            status: z.literal("deleted"),
+            path: z.string(),
+            recursive: z.boolean(),
+        }),
+        ...toolWidgetDescriptorMeta(config, "edit"),
+        annotations: EDIT_TOOL_ANNOTATIONS,
+    }, async ({ workspaceId, path, recursive }, extra) => {
+        const workspace = workspaces.getWorkspace(workspaceId);
+        return runToolWithHooks(hooks, {
+            tool: toolNames.delete,
+            invocation: workspaceHookInvocation(workspace),
+            payload: { path, recursive: recursive ?? false },
+            changedPaths: () => [path],
+            operation: async () => {
+                const startedAt = performance.now();
+                try {
+                    const deleted = await deletePath({ path, recursive }, {
+                        cwd: workspace.root,
+                        allowedRoots: workspaces.fileToolRoots(workspace),
+                    });
+                    const result = `Deleted ${path}${deleted.recursive ? " recursively" : ""}.`;
+                    const content = [textBlock(result)];
+                    logToolCall(config, {
+                        tool: toolNames.delete,
+                        ...workspaceLogContext(workspace, extra.sessionId),
+                        path,
+                        success: true,
+                        durationMs: Math.round(performance.now() - startedAt),
+                    });
+                    return {
+                        content,
+                        _meta: {
+                            tool: toolNames.delete,
+                            card: {
+                                workspaceId,
+                                path,
+                                summary: { recursive: deleted.recursive },
+                                payload: { content },
+                            },
+                        },
+                        structuredContent: {
+                            result,
+                            status: "deleted",
+                            path,
+                            recursive: deleted.recursive,
+                        },
+                    };
+                }
+                catch (error) {
+                    logToolCall(config, {
+                        tool: toolNames.delete,
+                        ...workspaceLogContext(workspace, extra.sessionId),
+                        path,
+                        success: false,
+                        durationMs: Math.round(performance.now() - startedAt),
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    throw error;
+                }
+            },
+        });
+    });
     if (config.toolMode === "codex") {
         registerAppTool(server, "apply_patch", {
             title: "Apply patch",