@akira-tl/forgerelay 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [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
+
+- Local console logging now defaults to a compact Loguru-style `pretty` format focused on Agent operations: short timestamps, workspace/session context, tool or Hook action, target, and `ok`/`error` or shell exit status. HTTP request logging is off by default in human mode, while explicit `json` mode keeps the previous request-on and shell-command-off machine defaults.
+
+### Fixed
+
+- File and search tools can access and modify files in the operating system temporary directory without making that directory an implicit workspace root; Codex `apply_patch` supports absolute OS-temp paths while workspace patch paths remain relative.
+
+### Security
+
+- 文件工具在 workspace 与 OS temp 边界内都会校验 canonical path，阻止通过 symlink 跳转到任意文件系统位置；shell cwd 与 workspace-open allowed roots 不随 temp 文件访问而扩大。
+
 ## [0.2.0] - 2026-08-09
 
 ### Added

package/dist/apply-patch.js

@@ -4,6 +4,7 @@ import { access, lstat, mkdir, readFile, realpath, rename, rm, stat, writeFile }
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { TextDecoder } from "node:util";
 import { createTwoFilesPatch, FILE_HEADERS_ONLY } from "diff";
+import { AccessDeniedError, resolveCanonicalAllowedPath } from "./roots.js";
 function patchError(message) {
     return new Error(`Invalid patch: ${message}`);
 }
@@ -137,10 +138,24 @@ function isInside(root, path) {
     const rel = relative(root, path);
     return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
 }
-async function resolveConfinedPath(root, input) {
-    if (!input || input.includes("\0") || isAbsolute(input)) {
+async function resolveConfinedPath(root, input, auxiliaryRoots = []) {
+    if (!input || input.includes("\0")) {
         throw patchError(`path must be relative to the workspace: ${input}`);
     }
+    if (isAbsolute(input)) {
+        if (auxiliaryRoots.length === 0) {
+            throw patchError(`path must be relative to the workspace: ${input}`);
+        }
+        try {
+            return await resolveCanonicalAllowedPath(input, root, auxiliaryRoots);
+        }
+        catch (error) {
+            if (error instanceof AccessDeniedError) {
+                throw patchError(`path is outside allowed auxiliary roots: ${input}`);
+            }
+            throw error;
+        }
+    }
     const rootPath = await realpath(root);
     const target = resolve(rootPath, input);
     if (!isInside(rootPath, target)) {
@@ -269,7 +284,7 @@ export async function isSamePatchFile(source, destination, readIdentity = lstat)
         throw error;
     }
 }
-export async function applyPatch(root, patch) {
+export async function applyPatch(root, patch, auxiliaryRoots = []) {
     const actions = parsePatch(patch);
     const results = [];
     const patches = [];
@@ -289,14 +304,14 @@ export async function applyPatch(root, patch) {
     };
     for (const action of actions) {
         if (action.kind === "add") {
-            const absolute = await resolveConfinedPath(root, action.path);
+            const absolute = await resolveConfinedPath(root, action.path, auxiliaryRoots);
             const original = await readStagedOptional(absolute, action.path);
             staged.set(absolute, { content: action.content, mode: original?.mode });
             patches.push(unifiedFilePatch(action.path, action.path, original?.content ?? null, action.content));
             results.push({ path: action.path, operation: original ? "update" : "add" });
             continue;
         }
-        const absolute = await resolveConfinedPath(root, action.path);
+        const absolute = await resolveConfinedPath(root, action.path, auxiliaryRoots);
         const file = await readStagedRequired(absolute, action.path);
         if (action.kind === "delete") {
             staged.set(absolute, null);
@@ -306,7 +321,7 @@ export async function applyPatch(root, patch) {
         }
         const updated = applyHunks(action.path, file.content, action.hunks);
         if (action.moveTo) {
-            const destination = await resolveConfinedPath(root, action.moveTo);
+            const destination = await resolveConfinedPath(root, action.moveTo, auxiliaryRoots);
             const samePatchFile = await isSamePatchFile(absolute, destination);
             if (!samePatchFile)
                 await readStagedOptional(destination, action.moveTo);

package/dist/artifact-tools.js

@@ -7,7 +7,7 @@ import * as z from "zod/v4";
 import { ArtifactError } from "./artifact-error.js";
 import { runToolWithHooks } from "./hooks.js";
 import { describeIncomingArtifactValue, IncomingArtifactAdapterRegistry, } from "./incoming-artifacts.js";
-import { logEvent } from "./logger.js";
+import { logEvent, sessionIdPrefix, workspaceLogLabel } from "./logger.js";
 const ARTIFACT_WRITE_ANNOTATIONS = {
     readOnlyHint: false,
     destructiveHint: false,
@@ -47,7 +47,7 @@ export function registerArtifactTools(server, { config, workspaces, hooks, incom
         },
         _meta: { "openai/fileParams": ["file"] },
         annotations: ARTIFACT_WRITE_ANNOTATIONS,
-    }, async (input) => {
+    }, async (input, extra) => {
         const workspace = workspaces.getWorkspace(input.workspaceId);
         return runToolWithHooks(hooks, {
             tool: "download_artifact",
@@ -59,7 +59,10 @@ export function registerArtifactTools(server, { config, workspaces, hooks, incom
             },
             payload: { path: input.path },
             changedPaths: (result) => [result.structuredContent.path],
-            operation: () => executeArtifactTool(config, input, async () => {
+            operation: () => executeArtifactTool(config, input, {
+                workspace: workspaceLogLabel(workspace.root, workspace.id),
+                session: sessionIdPrefix(extra?.sessionId),
+            }, async () => {
                 const downloaded = await downloadIncomingArtifact({
                     registry: incomingRegistry,
                     workspaceId: workspace.id,
@@ -165,7 +168,7 @@ export function artifactToolLogFields(input) {
         path: input.path,
     };
 }
-async function executeArtifactTool(config, input, operation) {
+async function executeArtifactTool(config, input, logContext, operation) {
     const startedAt = performance.now();
     try {
         const { publicResult, logResult } = await operation();
@@ -173,6 +176,7 @@ async function executeArtifactTool(config, input, operation) {
             logEvent(config.logging, "info", "artifact_tool_call", {
                 tool: "download_artifact",
                 ...artifactToolLogFields(input),
+                ...logContext,
                 path: logResult.path,
                 size: logResult.size,
                 sha256: logResult.sha256,
@@ -187,6 +191,7 @@ async function executeArtifactTool(config, input, operation) {
             logEvent(config.logging, "warn", "artifact_tool_call", {
                 tool: "download_artifact",
                 ...artifactToolLogFields(input),
+                ...logContext,
                 success: false,
                 errorCode: error instanceof ArtifactError ? error.code : "internal_error",
                 durationMs: Math.round(performance.now() - startedAt),

package/dist/config.js

@@ -81,10 +81,10 @@ function parseLogLevel(value) {
     throw new Error(`Invalid FORGERELAY_LOG_LEVEL: ${value}`);
 }
 function parseLogFormat(value) {
-    if (!value || value === "json")
-        return "json";
-    if (value === "pretty")
+    if (!value || value === "pretty")
         return "pretty";
+    if (value === "json")
+        return "json";
     throw new Error(`Invalid FORGERELAY_LOG_FORMAT: ${value}`);
 }
 function parsePathList(value) {
@@ -110,15 +110,17 @@ function parsePositiveInteger(value, fallback, name, max = Number.MAX_SAFE_INTEG
     return parsed;
 }
 function parseLoggingConfig(env) {
+    const format = parseLogFormat(productEnv(env, "LOG_FORMAT"));
     const requests = productEnv(env, "LOG_REQUESTS");
     const toolCalls = productEnv(env, "LOG_TOOL_CALLS");
+    const shellCommands = productEnv(env, "LOG_SHELL_COMMANDS");
     return {
         level: parseLogLevel(productEnv(env, "LOG_LEVEL")),
-        format: parseLogFormat(productEnv(env, "LOG_FORMAT")),
-        requests: requests === undefined ? true : parseBoolean(requests),
+        format,
+        requests: requests === undefined ? format === "json" : parseBoolean(requests),
         assets: parseBoolean(productEnv(env, "LOG_ASSETS")),
         toolCalls: toolCalls === undefined ? true : parseBoolean(toolCalls),
-        shellCommands: parseBoolean(productEnv(env, "LOG_SHELL_COMMANDS")),
+        shellCommands: shellCommands === undefined ? format === "pretty" : parseBoolean(shellCommands),
         trustProxy: parseBoolean(productEnv(env, "TRUST_PROXY")),
     };
 }

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/hooks.js

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { readFile, readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { performance } from "node:perf_hooks";
-import { commandPreview, logEvent } from "./logger.js";
+import { commandPreview, logEvent, workspaceLogLabel } from "./logger.js";
 import { resolveShellCommand, terminateProcessTree } from "./process-platform.js";
 export const HOOK_EVENTS = [
     "WorkspaceOpen",
@@ -224,6 +224,9 @@ export class HookRunner {
                 hookName: execution.name,
                 hookScope: execution.scope,
                 workspaceId: invocation.workspaceId,
+                workspace: invocation.workspaceId
+                    ? workspaceLogLabel(invocation.workspaceRoot, invocation.workspaceId)
+                    : invocation.workspaceRoot,
                 success: execution.status === "passed",
                 durationMs: execution.durationMs,
                 error: execution.error,

package/dist/logger.js

@@ -1,3 +1,5 @@
+import { basename } from "node:path";
+import { styleText } from "node:util";
 const LEVEL_WEIGHT = {
     silent: 0,
     error: 1,
@@ -5,6 +7,12 @@ const LEVEL_WEIGHT = {
     info: 3,
     debug: 4,
 };
+const LEVEL_STYLE = {
+    error: "red",
+    warn: "yellow",
+    info: "green",
+    debug: "gray",
+};
 export function shouldLog(config, level) {
     return LEVEL_WEIGHT[config.level] >= LEVEL_WEIGHT[level];
 }
@@ -17,7 +25,10 @@ export function logEvent(config, level, event, fields = {}) {
         event,
         ...fields,
     };
-    const line = config.format === "pretty" ? formatPretty(entry) : JSON.stringify(entry);
+    const stream = level === "error" || level === "warn" ? process.stderr : process.stdout;
+    const line = config.format === "pretty"
+        ? formatPrettyLogEntry(entry, { colorize: true, stream })
+        : JSON.stringify(entry);
     if (level === "error") {
         console.error(line);
     }
@@ -45,25 +56,156 @@ export function requestPath(req) {
 export function sessionIdPrefix(sessionId) {
     return sessionId ? sessionId.slice(0, 8) : undefined;
 }
+export function workspaceLogLabel(root, workspaceId) {
+    const shortWorkspaceId = workspaceId.startsWith("ws_")
+        ? `ws_${workspaceId.slice(3, 11)}`
+        : workspaceId.slice(0, 8);
+    return `${basename(root)}/${shortWorkspaceId}`;
+}
 export function commandPreview(command) {
     const normalized = command.replace(/\s+/g, " ").trim();
     return normalized.length > 120 ? `${normalized.slice(0, 117)}...` : normalized;
 }
+export function formatPrettyLogEntry(entry, options = {}) {
+    const level = logLevel(entry.level);
+    const time = formatTimestamp(entry.ts);
+    const source = stringField(entry.workspace) ?? stringField(entry.workspaceId) ?? "forgerelay";
+    const session = stringField(entry.session) ?? stringField(entry.sessionIdPrefix);
+    const prefix = [
+        style("gray", time, options),
+        `[${style(LEVEL_STYLE[level], level.toUpperCase(), options)}]`,
+        style(["cyan", "underline"], source, options),
+        session ? style("gray", `session:${session}`, options) : undefined,
+        style("gray", "|", options),
+    ].filter((value) => Boolean(value)).join(" ");
+    return `${prefix} ${formatPrettyMessage(entry, options)}`;
+}
 function firstHeaderValue(value) {
     return value?.split(",")[0]?.trim() || undefined;
 }
-function formatPretty(entry) {
-    const ts = String(entry.ts);
-    const level = String(entry.level).toUpperCase();
-    const event = String(entry.event);
-    const rest = Object.entries(entry)
-        .filter(([key, value]) => !["ts", "level", "event"].includes(key) && value !== undefined)
-        .map(([key, value]) => `${key}=${formatPrettyValue(value)}`)
-        .join(" ");
-    return rest ? `${ts} ${level} ${event} ${rest}` : `${ts} ${level} ${event}`;
-}
-function formatPrettyValue(value) {
-    if (typeof value === "string")
-        return JSON.stringify(value);
-    return JSON.stringify(value);
+function formatPrettyMessage(entry, options) {
+    switch (String(entry.event)) {
+        case "tool_call":
+        case "artifact_tool_call":
+            return formatToolMessage(entry, options);
+        case "hook_call":
+            return formatHookMessage(entry, options);
+        case "http_request":
+            return formatHttpMessage(entry, options);
+        case "mcp_session_created":
+            return `session ${stringField(entry.sessionIdPrefix) ?? "unknown"} created`;
+        case "mcp_session_closed":
+            return `session ${stringField(entry.sessionIdPrefix) ?? "unknown"} closed`;
+        case "mcp_session_close_failed":
+            return `session ${stringField(entry.sessionIdPrefix) ?? "unknown"} close -> ${style("red", "error", options)}`;
+        case "auth_denied":
+            return `auth denied${entry.reason ? `: ${String(entry.reason)}` : ""}`;
+        case "mcp_request_error":
+            return `mcp request -> ${style("red", `error${entry.error ? `: ${String(entry.error)}` : ""}`, options)}`;
+        default:
+            return formatGenericMessage(entry);
+    }
+}
+function formatToolMessage(entry, options) {
+    const tool = stringField(entry.tool) ?? String(entry.event ?? "tool");
+    const target = toolTarget(entry, tool);
+    const operation = target ? `${tool} ${target}` : tool;
+    const result = toolResult(entry, tool, options);
+    return `${operation} -> ${result}`;
+}
+function toolTarget(entry, tool) {
+    if (isShellTool(tool)) {
+        return stringField(entry.commandPreview) ?? stringField(entry.workingDirectory);
+    }
+    return stringField(entry.path) ?? stringField(entry.workingDirectory);
+}
+function toolResult(entry, tool, options) {
+    if (entry.running === true) {
+        const processSessionId = entry.processSessionId;
+        return style("yellow", processSessionId === undefined ? "running" : `running process:${String(processSessionId)}`, options);
+    }
+    const exitCode = numberField(entry.exitCode) ?? exitCodeFromError(entry.error);
+    if (isShellTool(tool)) {
+        if (exitCode !== undefined) {
+            return style(exitCode === 0 ? "green" : "red", `exit=${exitCode}`, options);
+        }
+        if (entry.success === true)
+            return style("green", "exit=0", options);
+    }
+    if (entry.success === false) {
+        const error = stringField(entry.error);
+        return style("red", error ? `error: ${error}` : "error", options);
+    }
+    if (entry.success === true)
+        return style("green", "ok", options);
+    return "done";
+}
+function formatHookMessage(entry, options) {
+    const name = stringField(entry.hookName) ?? "hook";
+    const event = stringField(entry.hookEvent);
+    const operation = event ? `hook ${name} ${event}` : `hook ${name}`;
+    const exitCode = exitCodeFromHookError(entry.error);
+    if (entry.success === false) {
+        if (exitCode !== undefined)
+            return `${operation} -> ${style("red", `exit=${exitCode}`, options)}`;
+        const error = stringField(entry.error);
+        return `${operation} -> ${style("red", error ? `error: ${error}` : "error", options)}`;
+    }
+    return `${operation} -> ${style("green", "exit=0", options)}`;
+}
+function formatHttpMessage(entry, options) {
+    const method = stringField(entry.method) ?? "HTTP";
+    const path = stringField(entry.path) ?? "/";
+    const status = numberField(entry.status);
+    const statusText = status === undefined ? "done" : String(status);
+    const statusStyle = status !== undefined && status >= 400 ? "red" : "green";
+    return `http ${method} ${path} -> ${style(statusStyle, statusText, options)}`;
+}
+function formatGenericMessage(entry) {
+    const event = String(entry.event ?? "log");
+    const detail = [entry.reason, entry.error]
+        .map((value) => stringField(value))
+        .find((value) => value !== undefined);
+    return detail ? `${event}: ${detail}` : event;
+}
+function formatTimestamp(value) {
+    const date = new Date(String(value));
+    if (Number.isNaN(date.getTime()))
+        return String(value ?? "");
+    const two = (part) => String(part).padStart(2, "0");
+    return `${two(date.getMonth() + 1)}-${two(date.getDate())} ${two(date.getHours())}:${two(date.getMinutes())}:${two(date.getSeconds())}`;
+}
+function logLevel(value) {
+    return value === "error" || value === "warn" || value === "debug" ? value : "info";
+}
+function stringField(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function numberField(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function exitCodeFromError(value) {
+    const error = stringField(value);
+    if (!error)
+        return undefined;
+    const match = error.match(/Command exited with code (-?\d+)/i);
+    return match ? Number(match[1]) : undefined;
+}
+function exitCodeFromHookError(value) {
+    const error = stringField(value);
+    if (!error)
+        return undefined;
+    const match = error.match(/exited with code (-?\d+)/i);
+    return match ? Number(match[1]) : undefined;
+}
+function isShellTool(tool) {
+    return tool === "bash" || tool === "exec_command" || tool === "write_stdin";
+}
+function style(format, text, options) {
+    if (options.colorize !== true)
+        return text;
+    return styleText(format, text, {
+        validateStream: options.validateStream ?? true,
+        stream: options.stream ?? process.stdout,
+    });
 }

package/dist/mcp/server-instructions.js

@@ -4,6 +4,8 @@ export const toolNames = {
     read: "read",
     write: "write",
     edit: "edit",
+    rename: "rename",
+    delete: "delete",
     grep: "grep",
     glob: "glob",
     ls: "ls",
@@ -20,18 +22,20 @@ export function buildToolDescriptions(config) {
         ? ` 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.`
         : "";
     return {
-        read: `Read a file inside an open workspace. 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. The path is resolved within the workspace filesystem boundary. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
-        edit: `Edit one file inside an open workspace by replacing exact text blocks. Each oldText must match a unique, non-overlapping region of the original file. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
-        applyPatch: `Apply one Codex-style patch inside an open workspace. Supports adding, overwriting, updating, deleting, and moving files. Paths must be relative to the workspace. 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.`,
+        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, 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.`,
         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.`
@@ -48,7 +52,7 @@ function capabilityContractInstructions(config, context) {
 }
 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 +68,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, 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.`);
 }
 function joinInstructions(...parts) {
     return parts

package/dist/pi-tools.js

@@ -1,5 +1,5 @@
 import { createBashTool, createEditTool, createFindTool, createGrepTool, createLsTool, createReadTool, createWriteTool, } from "@earendil-works/pi-coding-agent";
-import { resolveAllowedPath } from "./roots.js";
+import { resolveCanonicalAllowedPath } from "./roots.js";
 function toMcpContent(result) {
     return result.content.map((content) => {
         if (content.type === "text") {
@@ -29,7 +29,7 @@ async function runTool(execute, input, context) {
     }
 }
 export async function readFileTool(input, context) {
-    const path = resolveAllowedPath(input.path, context.cwd, context.readRoots ?? [context.root]);
+    const path = await resolveCanonicalAllowedPath(input.path, context.cwd, context.readRoots ?? [context.root]);
     const tool = createReadTool(context.cwd);
     return runTool((params) => tool.execute("read_file", params), {
         path,
@@ -38,7 +38,7 @@ export async function readFileTool(input, context) {
     }, context);
 }
 export async function writeFileTool(input, context) {
-    const path = resolveAllowedPath(input.path, context.cwd, [context.root]);
+    const path = await resolveCanonicalAllowedPath(input.path, context.cwd, context.fileRoots ?? [context.root]);
     const tool = createWriteTool(context.cwd);
     return runTool((params) => tool.execute("write_file", params), {
         path,
@@ -46,7 +46,7 @@ export async function writeFileTool(input, context) {
     }, context);
 }
 export async function editFileTool(input, context) {
-    const path = resolveAllowedPath(input.path, context.cwd, [context.root]);
+    const path = await resolveCanonicalAllowedPath(input.path, context.cwd, context.fileRoots ?? [context.root]);
     const tool = createEditTool(context.cwd);
     return runTool((params) => tool.execute("edit_file", params), {
         path,
@@ -54,22 +54,23 @@ export async function editFileTool(input, context) {
     }, context);
 }
 export async function grepFilesTool(input, context) {
-    if (input.path)
-        resolveAllowedPath(input.path, context.cwd, [context.root]);
+    const path = input.path
+        ? await resolveCanonicalAllowedPath(input.path, context.cwd, context.fileRoots ?? [context.root])
+        : undefined;
     const tool = createGrepTool(context.cwd);
-    return runTool((params) => tool.execute("grep_files", params), input, context);
+    return runTool((params) => tool.execute("grep_files", params), { ...input, path }, context);
 }
 export async function findFilesTool(input, context) {
-    if (input.path)
-        resolveAllowedPath(input.path, context.cwd, [context.root]);
+    const path = input.path
+        ? await resolveCanonicalAllowedPath(input.path, context.cwd, context.fileRoots ?? [context.root])
+        : undefined;
     const tool = createFindTool(context.cwd);
-    return runTool((params) => tool.execute("find_files", params), input, context);
+    return runTool((params) => tool.execute("find_files", params), { ...input, path }, context);
 }
 export async function listDirectoryTool(input, context) {
-    if (input.path)
-        resolveAllowedPath(input.path, context.cwd, [context.root]);
+    const path = await resolveCanonicalAllowedPath(input.path ?? ".", context.cwd, context.fileRoots ?? [context.root]);
     const tool = createLsTool(context.cwd);
-    return runTool((params) => tool.execute("list_directory", params), input, context);
+    return runTool((params) => tool.execute("list_directory", params), { ...input, path }, context);
 }
 export async function runShellTool(input, context) {
     const tool = createBashTool(context.cwd);

package/dist/roots.js

@@ -1,5 +1,6 @@
+import { realpath } from "node:fs/promises";
 import { homedir } from "node:os";
-import { isAbsolute, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
 export class AccessDeniedError extends Error {
     constructor(message) {
         super(message);
@@ -35,3 +36,31 @@ export function resolveAllowedPath(inputPath, cwd, allowedRoots) {
     const absolutePath = resolve(cwd, inputPath);
     return assertAllowedPath(absolutePath, allowedRoots);
 }
+export async function resolveCanonicalAllowedPath(inputPath, cwd, allowedRoots) {
+    const absolutePath = resolveAllowedPath(inputPath, cwd, allowedRoots);
+    const canonicalPath = await canonicalizePath(absolutePath);
+    const canonicalRoots = await Promise.all(allowedRoots.map((root) => canonicalizePath(resolve(expandHomePath(root)))));
+    if (canonicalRoots.some((root) => isPathInsideRoot(canonicalPath, root))) {
+        return absolutePath;
+    }
+    throw new AccessDeniedError(`Path is outside allowed roots: ${inputPath}`);
+}
+async function canonicalizePath(path) {
+    const missingSegments = [];
+    let candidate = path;
+    while (true) {
+        try {
+            return resolve(await realpath(candidate), ...missingSegments.slice().reverse());
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                throw error;
+            const parent = dirname(candidate);
+            if (parent === candidate)
+                return resolve(path);
+            missingSegments.push(basename(candidate));
+            candidate = parent;
+        }
+    }
+}