@akira-tl/forgerelay 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [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/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

@@ -20,10 +20,10 @@ 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.`,
+        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.`,
+        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.`,
         shellCommand: "Shell command to run with the local user's authority.",
     };

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;
+        }
+    }
+}

package/dist/server.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { access, realpath } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
@@ -18,7 +19,7 @@ import { loadConfig } from "./config.js";
 import { attachHookReports, HookRunner, runToolWithHooks } from "./hooks.js";
 import { buildServerInstructions, buildToolDescriptions, toolNames, } from "./mcp/server-instructions.js";
 import { createOpenAIIncomingArtifactAdapter, } from "./incoming-artifacts.js";
-import { logEvent, requestIp, requestPath, commandPreview, sessionIdPrefix, } from "./logger.js";
+import { logEvent, requestIp, requestPath, commandPreview, sessionIdPrefix, workspaceLogLabel, } from "./logger.js";
 import { editFileTool, findFilesTool, grepFilesTool, listDirectoryTool, readFileTool, runShellTool, writeFileTool, } from "./pi-tools.js";
 import { SingleUserOAuthProvider } from "./oauth-provider.js";
 import { McpSessionRegistry, } from "./mcp-sessions.js";
@@ -78,6 +79,13 @@ function toolWidgetDescriptorMeta(config, kind) {
         },
     };
 }
+function workspaceLogContext(workspace, sessionId) {
+    return {
+        workspaceId: workspace.id,
+        workspace: workspaceLogLabel(workspace.root, workspace.id),
+        session: sessionIdPrefix(sessionId),
+    };
+}
 function formatVisibleAgent(agent) {
     const model = agent.model ? `, model ${agent.model}` : "";
     const thinking = agent.thinking ? `, thinking ${agent.thinking}` : "";
@@ -393,7 +401,7 @@ function registerCodexProcessTools(server, config, workspaces, processSessions,
         outputSchema: processOutputSchema(),
         ...toolWidgetDescriptorMeta(config, "shell"),
         annotations: SHELL_TOOL_ANNOTATIONS,
-    }, async ({ workspaceId, cmd, tty, columns, rows, workingDirectory, yieldTimeMs, maxOutputTokens }) => {
+    }, async ({ workspaceId, cmd, tty, columns, rows, workingDirectory, yieldTimeMs, maxOutputTokens }, extra) => {
         const workspace = workspaces.getWorkspace(workspaceId);
         return runToolWithHooks(hooks, {
             tool: "exec_command",
@@ -415,11 +423,14 @@ function registerCodexProcessTools(server, config, workspaces, processSessions,
                 });
                 logToolCall(config, {
                     tool: "exec_command",
-                    workspaceId,
+                    ...workspaceLogContext(workspace, extra.sessionId),
                     workingDirectory: workingDirectory ?? ".",
                     command: cmd,
                     commandLength: cmd.length,
-                    success: true,
+                    exitCode: snapshot.exitCode,
+                    running: snapshot.running,
+                    processSessionId: snapshot.sessionId,
+                    success: snapshot.running || snapshot.exitCode === 0,
                     durationMs: Math.round(performance.now() - startedAt),
                 });
                 return processToolResponse("exec_command", workspaceId, snapshot, {
@@ -459,7 +470,7 @@ function registerCodexProcessTools(server, config, workspaces, processSessions,
         outputSchema: processOutputSchema(),
         ...toolWidgetDescriptorMeta(config, "shell"),
         annotations: SHELL_TOOL_ANNOTATIONS,
-    }, async ({ workspaceId, sessionId, chars, columns, rows, yieldTimeMs, maxOutputTokens }) => {
+    }, async ({ workspaceId, sessionId, chars, columns, rows, yieldTimeMs, maxOutputTokens }, extra) => {
         const workspace = workspaces.getWorkspace(workspaceId);
         return runToolWithHooks(hooks, {
             tool: "write_stdin",
@@ -483,8 +494,11 @@ function registerCodexProcessTools(server, config, workspaces, processSessions,
                 });
                 logToolCall(config, {
                     tool: "write_stdin",
-                    workspaceId,
-                    success: true,
+                    ...workspaceLogContext(workspace, extra.sessionId),
+                    exitCode: snapshot.exitCode,
+                    running: snapshot.running,
+                    processSessionId: snapshot.sessionId,
+                    success: snapshot.running || snapshot.exitCode === 0,
                     durationMs: Math.round(performance.now() - startedAt),
                 });
                 return processToolResponse("write_stdin", workspaceId, snapshot, {
@@ -597,7 +611,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             idempotentHint: false,
             openWorldHint: false,
         },
-    }, async ({ path, mode, baseRef, newWorktree }, { _meta }) => {
+    }, async ({ path, mode, baseRef, newWorktree }, { _meta, sessionId }) => {
         const startedAt = performance.now();
         const { workspace, agentsFiles, availableAgentsFiles, hookReports, workspaceReused, includeBootstrapContext, } = await workspaces.openWorkspace({ path, mode, baseRef, newWorktree }, { conversationScopeId: openAiConversationScopeId(_meta) });
         const knownWorktrees = await workspaces.listKnownWorktrees(workspace);
@@ -692,7 +706,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         ];
         logToolCall(config, {
             tool: "open_workspace",
-            workspaceId: workspace.id,
+            ...workspaceLogContext(workspace, sessionId),
             path: workspace.root,
             success: true,
             durationMs: Math.round(performance.now() - startedAt),
@@ -772,7 +786,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         }),
         _meta: {},
         annotations: WRITE_TOOL_ANNOTATIONS,
-    }, async ({ workspaceId, commitMessage }) => {
+    }, async ({ workspaceId, commitMessage }, extra) => {
         const workspace = workspaces.getWorkspace(workspaceId);
         return runToolWithHooks(hooks, {
             tool: toolNames.closeWorktree,
@@ -793,7 +807,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 ].join("\n");
                 logToolCall(config, {
                     tool: toolNames.closeWorktree,
-                    workspaceId,
+                    ...workspaceLogContext(workspace, extra.sessionId),
                     path: closed.sourceRoot,
                     success: true,
                     durationMs: Math.round(performance.now() - startedAt),
@@ -825,8 +839,8 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             path: z
                 .string()
                 .describe(config.skillsEnabled
-                ? "File path to read, relative to the workspace root. May also be an advertised skill path from open_workspace skills."
-                : "File path to read, relative to the workspace root."),
+                ? "File path to read, relative to the workspace root or absolute inside the OS temp directory. May also be an advertised skill path from open_workspace skills."
+                : "File path to read, relative to the workspace root or absolute inside the OS temp directory."),
             offset: z
                 .number()
                 .int()
@@ -843,7 +857,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         outputSchema: resultOutputSchema(),
         ...toolWidgetDescriptorMeta(config, "read"),
         annotations: { readOnlyHint: true },
-    }, async ({ workspaceId, ...input }) => {
+    }, async ({ workspaceId, ...input }, extra) => {
         const workspace = workspaces.getWorkspace(workspaceId);
         return runToolWithHooks(hooks, {
             tool: toolNames.read,
@@ -861,7 +875,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 if (response.isError) {
                     logFailedToolResponse(config, {
                         tool: toolNames.read,
-                        workspaceId,
+                        ...workspaceLogContext(workspace, extra.sessionId),
                         path: input.path,
                     }, response.content, startedAt);
                     return response;
@@ -874,7 +888,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 };
                 logToolCall(config, {
                     tool: toolNames.read,
-                    workspaceId,
+                    ...workspaceLogContext(workspace, extra.sessionId),
                     path: input.path,
                     success: true,
                     durationMs: Math.round(performance.now() - startedAt),
@@ -907,13 +921,13 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     .describe("Workspace identifier returned by open_workspace."),
                 path: z
                     .string()
-                    .describe("File path to write, relative to the workspace root."),
+                    .describe("File path to write, relative to the workspace root or absolute inside the OS temp directory."),
                 content: z.string().describe("Complete new file content."),
             },
             outputSchema: resultOutputSchema(),
             ...toolWidgetDescriptorMeta(config, "write"),
             annotations: WRITE_TOOL_ANNOTATIONS,
-        }, async ({ workspaceId, ...input }) => {
+        }, async ({ workspaceId, ...input }, extra) => {
             const workspace = workspaces.getWorkspace(workspaceId);
             return runToolWithHooks(hooks, {
                 tool: toolNames.write,
@@ -923,15 +937,15 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 changedPaths: (result) => toolResultIsError(result) ? [] : [input.path],
                 operation: async () => {
                     const startedAt = performance.now();
-                    workspaces.resolvePath(workspace, input.path);
                     const response = await writeFileTool(input, {
                         cwd: workspace.root,
                         root: workspace.root,
+                        fileRoots: workspaces.fileToolRoots(workspace),
                     });
                     if (response.isError) {
                         logFailedToolResponse(config, {
                             tool: toolNames.write,
-                            workspaceId,
+                            ...workspaceLogContext(workspace, extra.sessionId),
                             path: input.path,
                         }, response.content, startedAt);
                         return response;
@@ -945,7 +959,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     };
                     logToolCall(config, {
                         tool: toolNames.write,
-                        workspaceId,
+                        ...workspaceLogContext(workspace, extra.sessionId),
                         path: input.path,
                         success: true,
                         durationMs: Math.round(performance.now() - startedAt),
@@ -980,7 +994,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     .describe("Workspace identifier returned by open_workspace."),
                 path: z
                     .string()
-                    .describe("File path to edit, relative to the workspace root."),
+                    .describe("File path to edit, relative to the workspace root or absolute inside the OS temp directory."),
                 edits: z
                     .array(z.object({
                     oldText: z
@@ -995,7 +1009,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             }),
             ...toolWidgetDescriptorMeta(config, "edit"),
             annotations: EDIT_TOOL_ANNOTATIONS,
-        }, async ({ workspaceId, ...input }) => {
+        }, async ({ workspaceId, ...input }, extra) => {
             const workspace = workspaces.getWorkspace(workspaceId);
             return runToolWithHooks(hooks, {
                 tool: toolNames.edit,
@@ -1005,15 +1019,15 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 changedPaths: (result) => toolResultIsError(result) ? [] : [input.path],
                 operation: async () => {
                     const startedAt = performance.now();
-                    workspaces.resolvePath(workspace, input.path);
                     const response = await editFileTool(input, {
                         cwd: workspace.root,
                         root: workspace.root,
+                        fileRoots: workspaces.fileToolRoots(workspace),
                     });
                     if (response.isError) {
                         logFailedToolResponse(config, {
                             tool: toolNames.edit,
-                            workspaceId,
+                            ...workspaceLogContext(workspace, extra.sessionId),
                             path: input.path,
                         }, response.content, startedAt);
                         return response;
@@ -1027,7 +1041,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     const editContent = [textBlock(editResultText)];
                     logToolCall(config, {
                         tool: toolNames.edit,
-                        workspaceId,
+                        ...workspaceLogContext(workspace, extra.sessionId),
                         path: input.path,
                         success: true,
                         durationMs: Math.round(performance.now() - startedAt),
@@ -1078,7 +1092,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             }),
             ...toolWidgetDescriptorMeta(config, "edit"),
             annotations: EDIT_TOOL_ANNOTATIONS,
-        }, async ({ workspaceId, patch }) => {
+        }, async ({ workspaceId, patch }, extra) => {
             const workspace = workspaces.getWorkspace(workspaceId);
             return runToolWithHooks(hooks, {
                 tool: "apply_patch",
@@ -1088,7 +1102,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     .filter((path) => Boolean(path)))),
                 operation: async () => {
                     const startedAt = performance.now();
-                    const applied = await applyPatch(workspace.root, patch);
+                    const applied = await applyPatch(workspace.root, patch, [tmpdir()]);
                     const paths = applied.files.map((file) => file.path).join(", ");
                     const result = `Applied patch to ${applied.files.length} file(s): ${paths}`;
                     const content = [textBlock(result)];
@@ -1097,7 +1111,8 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                         : `${applied.files.length} files`;
                     logToolCall(config, {
                         tool: "apply_patch",
-                        workspaceId,
+                        ...workspaceLogContext(workspace, extra.sessionId),
+                        path: displayPath,
                         success: true,
                         durationMs: Math.round(performance.now() - startedAt),
                     });
@@ -1140,7 +1155,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             outputSchema: resultOutputSchema(),
             ...toolWidgetDescriptorMeta(config, "show_changes"),
             annotations: { readOnlyHint: true },
-        }, async ({ workspaceId }) => {
+        }, async ({ workspaceId }, extra) => {
             const workspace = workspaces.getWorkspace(workspaceId);
             return runToolWithHooks(hooks, {
                 tool: "show_changes",
@@ -1155,7 +1170,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     const content = [textBlock(review.result)];
                     logToolCall(config, {
                         tool: "show_changes",
-                        workspaceId,
+                        ...workspaceLogContext(workspace, extra.sessionId),
                         success: true,
                         durationMs: Math.round(performance.now() - startedAt),
                     });
@@ -1183,7 +1198,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     if (config.toolMode === "full") {
         registerAppTool(server, toolNames.grep, {
             title: "Grep",
-            description: "Search file contents inside an open workspace. Use this before broad reads when looking for symbols, text, or usage sites. Respects project ignore rules. Call open_workspace first and pass workspaceId.",
+            description: "Search file contents inside an open workspace or the OS temp directory. Use this before broad reads when looking for symbols, text, or usage sites. Respects project ignore rules. Call open_workspace first and pass workspaceId.",
             inputSchema: {
                 workspaceId: z
                     .string()
@@ -1192,13 +1207,13 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 path: z
                     .string()
                     .optional()
-                    .describe("Optional path or glob scope relative to the workspace root."),
+                    .describe("Optional path or glob scope relative to the workspace root, or an absolute path inside the OS temp directory."),
                 include: z.string().optional().describe("Optional include glob."),
             },
             outputSchema: resultOutputSchema(),
             ...toolWidgetDescriptorMeta(config, "search"),
             annotations: { readOnlyHint: true },
-        }, async ({ workspaceId, ...input }) => {
+        }, async ({ workspaceId, ...input }, extra) => {
             const workspace = workspaces.getWorkspace(workspaceId);
             return runToolWithHooks(hooks, {
                 tool: toolNames.grep,
@@ -1207,16 +1222,15 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 isFailure: toolResultIsError,
                 operation: async () => {
                     const startedAt = performance.now();
-                    if (input.path)
-                        workspaces.resolvePath(workspace, input.path);
                     const response = await grepFilesTool(input, {
                         cwd: workspace.root,
                         root: workspace.root,
+                        fileRoots: workspaces.fileToolRoots(workspace),
                     });
                     if (response.isError) {
                         logFailedToolResponse(config, {
                             tool: toolNames.grep,
-                            workspaceId,
+                            ...workspaceLogContext(workspace, extra.sessionId),
                             path: input.path,
                         }, response.content, startedAt);
                         return response;
@@ -1228,7 +1242,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     };
                     logToolCall(config, {
                         tool: toolNames.grep,
-                        workspaceId,
+                        ...workspaceLogContext(workspace, extra.sessionId),
                         path: input.path,
                         success: true,
                         durationMs: Math.round(performance.now() - startedAt),
@@ -1253,7 +1267,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         });
         registerAppTool(server, toolNames.glob, {
             title: "Glob",
-            description: "Find files by glob pattern inside an open workspace. Use this to discover filenames or narrow file sets before reading. Respects project ignore rules. Call open_workspace first and pass workspaceId.",
+            description: "Find files by glob pattern inside an open workspace or the OS temp directory. Use this to discover filenames or narrow file sets before reading. Respects project ignore rules. Call open_workspace first and pass workspaceId.",
             inputSchema: {
                 workspaceId: z
                     .string()
@@ -1262,12 +1276,12 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 path: z
                     .string()
                     .optional()
-                    .describe("Optional path scope relative to the workspace root."),
+                    .describe("Optional path scope relative to the workspace root, or an absolute path inside the OS temp directory."),
             },
             outputSchema: resultOutputSchema(),
             ...toolWidgetDescriptorMeta(config, "search"),
             annotations: { readOnlyHint: true },
-        }, async ({ workspaceId, ...input }) => {
+        }, async ({ workspaceId, ...input }, extra) => {
             const workspace = workspaces.getWorkspace(workspaceId);
             return runToolWithHooks(hooks, {
                 tool: toolNames.glob,
@@ -1276,16 +1290,15 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 isFailure: toolResultIsError,
                 operation: async () => {
                     const startedAt = performance.now();
-                    if (input.path)
-                        workspaces.resolvePath(workspace, input.path);
                     const response = await findFilesTool(input, {
                         cwd: workspace.root,
                         root: workspace.root,
+                        fileRoots: workspaces.fileToolRoots(workspace),
                     });
                     if (response.isError) {
                         logFailedToolResponse(config, {
                             tool: toolNames.glob,
-                            workspaceId,
+                            ...workspaceLogContext(workspace, extra.sessionId),
                             path: input.path,
                         }, response.content, startedAt);
                         return response;
@@ -1297,7 +1310,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     };
                     logToolCall(config, {
                         tool: toolNames.glob,
-                        workspaceId,
+                        ...workspaceLogContext(workspace, extra.sessionId),
                         path: input.path,
                         success: true,
                         durationMs: Math.round(performance.now() - startedAt),
@@ -1322,19 +1335,19 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         });
         registerAppTool(server, toolNames.ls, {
             title: "Ls",
-            description: "List a directory inside an open workspace. Use this for directory inspection before reading files. Call open_workspace first and pass workspaceId.",
+            description: "List a directory inside an open workspace or the OS temp directory. Use this for directory inspection before reading files. Call open_workspace first and pass workspaceId.",
             inputSchema: {
                 workspaceId: z
                     .string()
                     .describe("Workspace identifier returned by open_workspace."),
                 path: z
                     .string()
-                    .describe("Directory path to list, relative to the workspace root."),
+                    .describe("Directory path to list, relative to the workspace root or absolute inside the OS temp directory."),
             },
             outputSchema: resultOutputSchema(),
             ...toolWidgetDescriptorMeta(config, "directory"),
             annotations: { readOnlyHint: true },
-        }, async ({ workspaceId, ...input }) => {
+        }, async ({ workspaceId, ...input }, extra) => {
             const workspace = workspaces.getWorkspace(workspaceId);
             return runToolWithHooks(hooks, {
                 tool: toolNames.ls,
@@ -1343,15 +1356,15 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 isFailure: toolResultIsError,
                 operation: async () => {
                     const startedAt = performance.now();
-                    workspaces.resolvePath(workspace, input.path);
                     const response = await listDirectoryTool(input, {
                         cwd: workspace.root,
                         root: workspace.root,
+                        fileRoots: workspaces.fileToolRoots(workspace),
                     });
                     if (response.isError) {
                         logFailedToolResponse(config, {
                             tool: toolNames.ls,
-                            workspaceId,
+                            ...workspaceLogContext(workspace, extra.sessionId),
                             path: input.path,
                         }, response.content, startedAt);
                         return response;
@@ -1359,7 +1372,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     const summary = textSummary(response.content);
                     logToolCall(config, {
                         tool: toolNames.ls,
-                        workspaceId,
+                        ...workspaceLogContext(workspace, extra.sessionId),
                         path: input.path,
                         success: true,
                         durationMs: Math.round(performance.now() - startedAt),
@@ -1408,7 +1421,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             outputSchema: resultOutputSchema(),
             ...toolWidgetDescriptorMeta(config, "shell"),
             annotations: SHELL_TOOL_ANNOTATIONS,
-        }, async ({ workspaceId, workingDirectory, ...input }) => {
+        }, async ({ workspaceId, workingDirectory, ...input }, extra) => {
             const workspace = workspaces.getWorkspace(workspaceId);
             return runToolWithHooks(hooks, {
                 tool: toolNames.shell,
@@ -1429,7 +1442,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     if (response.isError) {
                         logFailedToolResponse(config, {
                             tool: toolNames.shell,
-                            workspaceId,
+                            ...workspaceLogContext(workspace, extra.sessionId),
                             workingDirectory: workingDirectory ?? ".",
                             command: input.command,
                             commandLength: input.command.length,
@@ -1443,7 +1456,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     };
                     logToolCall(config, {
                         tool: toolNames.shell,
-                        workspaceId,
+                        ...workspaceLogContext(workspace, extra.sessionId),
                         workingDirectory: workingDirectory ?? ".",
                         command: input.command,
                         commandLength: input.command.length,

package/dist/workspaces.js

@@ -1,5 +1,6 @@
 import { randomBytes } from "node:crypto";
 import { mkdir, opendir, readFile, realpath, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { HookRunner } from "./hooks.js";
 import { closeManagedWorktree, createManagedWorktree, resolveManagedWorktreeBase, } from "./git-worktrees.js";
@@ -305,6 +306,9 @@ export class WorkspaceRegistry {
         this.workspaces.set(restoredWorkspace.id, restoredWorkspace);
         return restoredWorkspace;
     }
+    fileToolRoots(workspace) {
+        return [workspace.root, tmpdir()];
+    }
     resolvePath(workspace, inputPath) {
         const absolutePath = resolveAllowedPath(inputPath, workspace.root, [workspace.root]);
         if (!isPathInsideRoot(absolutePath, workspace.root)) {
@@ -321,13 +325,22 @@ export class WorkspaceRegistry {
         }
         catch (workspaceError) {
             const skillRead = resolveSkillReadPath(workspace.skills, workspace.activatedSkillDirs, inputPath);
-            if (!skillRead)
+            if (skillRead) {
+                return {
+                    absolutePath: skillRead.absolutePath,
+                    readRoots: [workspace.root, skillRead.skill.baseDir],
+                    skillRead,
+                };
+            }
+            try {
+                return {
+                    absolutePath: resolveAllowedPath(inputPath, workspace.root, [tmpdir()]),
+                    readRoots: this.fileToolRoots(workspace),
+                };
+            }
+            catch {
                 throw workspaceError;
-            return {
-                absolutePath: skillRead.absolutePath,
-                readRoots: [workspace.root, skillRead.skill.baseDir],
-                skillRead,
-            };
+            }
         }
     }
     markReadPathLoaded(workspace, readPath) {

package/docs/configuration.md

@@ -310,15 +310,23 @@ forgerelay agents show <id>
 | Variable | Default |
 | --- | --- |
 | `FORGERELAY_LOG_LEVEL` | `info` |
-| `FORGERELAY_LOG_FORMAT` | `json` |
-| `FORGERELAY_LOG_REQUESTS` | `1` |
+| `FORGERELAY_LOG_FORMAT` | `pretty` |
+| `FORGERELAY_LOG_REQUESTS` | `0` in `pretty`, `1` in `json` |
 | `FORGERELAY_LOG_ASSETS` | `0` |
 | `FORGERELAY_LOG_TOOL_CALLS` | `1` |
-| `FORGERELAY_LOG_SHELL_COMMANDS` | `0` |
+| `FORGERELAY_LOG_SHELL_COMMANDS` | `1` in `pretty`, `0` in `json` |
 | `FORGERELAY_TRUST_PROXY` | `0` |
 
-Set `FORGERELAY_LOG_FORMAT=pretty` for local debugging. Enable shell command
-previews only when intentionally needed; they can reveal sensitive arguments.
+`pretty` is the human-facing local console format. It uses terminal-aware color,
+short timestamps, workspace/session context, and compact operation results while
+keeping HTTP request records off by default. Shell command previews are enabled
+in this mode and truncated to 120 characters; set
+`FORGERELAY_LOG_SHELL_COMMANDS=0` when command arguments may contain secrets.
+
+Set `FORGERELAY_LOG_FORMAT=json` for machine collection. Unless explicitly
+overridden, JSON mode preserves request logging and omits shell command previews.
+`FORGERELAY_LOG_REQUESTS` and `FORGERELAY_LOG_SHELL_COMMANDS` always override
+these format-specific defaults when set.
 
 ## Environment-only example
 

package/docs/debugging.md

@@ -61,10 +61,11 @@ The acceptance checks:
 5. MCP `initialize`, including package/server version consistency;
 6. `tools/list` for the full debug tool surface;
 7. a real checkout workspace with `write`, `read`, `bash`, and a deliberate failed `edit`;
-8. a temporary Git repository with managed worktree creation, file modification, and `close_worktree`;
-9. 本地 bare remote 上的 release-tag-push Hook：成功 Hook 必须先运行再允许 `v0.2.0` push，失败 Hook 必须在 remote mutation 前阻断 `v0.2.1`；
-10. deterministic local subagent error path，不联系任何模型 provider；
-11. debug hook recorder 覆盖全部九个 Hooks v1 lifecycle events。
+8. OS temp-directory `write` → `read` → `edit` 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`;
+10. 本地 bare remote 上的 release-tag-push Hook：成功 Hook 必须先运行再允许 `v0.2.0` push，失败 Hook 必须在 remote mutation 前阻断 `v0.2.1`；
+11. deterministic local subagent error path，不联系任何模型 provider；
+12. debug hook recorder 覆盖全部九个 Hooks v1 lifecycle events。
 
 `curl` must be available on `PATH` for this acceptance command. Node and Git are
 already normal ForgeRelay development prerequisites.

package/docs/security.md

@@ -17,8 +17,16 @@ Example:
 Do not use your entire home directory unless that is intentionally the access
 boundary you want.
 
-Filesystem-oriented tools validate workspace-relative paths and reject paths
-that escape the opened workspace or configured roots.
+Opening a workspace still requires the path to be inside the configured allowed
+roots. File and search tools additionally accept paths inside the operating
+system temporary directory (for example `/tmp` on Linux) without treating that
+directory as an allowed workspace root. Workspace paths remain confined to the
+opened workspace, and shell working directories are not expanded by this temp
+access.
+
+Filesystem-oriented tools canonicalize existing path segments before access so
+symlinks inside either the workspace or OS temp directory cannot escape to
+arbitrary filesystem locations.
 
 ## Owner-password OAuth
 
@@ -137,15 +145,18 @@ as owner-only files. See [Native File Download](artifact-exchange.md).
 
 ## Logging
 
-ForgeRelay logs requests/tool calls by default. Shell command previews are off
-unless explicitly enabled:
+ForgeRelay's default human-facing `pretty` logs focus on tool and Hook
+operations; HTTP request records are off by default. Pretty mode includes a
+truncated shell command preview so local operators can see what the Agent ran.
+Command arguments can contain secrets, so disable previews when necessary:
 
 ```bash
-FORGERELAY_LOG_SHELL_COMMANDS=1
+FORGERELAY_LOG_SHELL_COMMANDS=0
 ```
 
-Command arguments can contain secrets, so only enable command-preview logging
-when necessary.
+Explicit `json` mode is intended for machine collection. Its default preserves
+HTTP request records and omits shell command previews unless those settings are
+overridden explicitly.
 
 ## Package provenance
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -41,7 +41,7 @@
     "debug:accept": "node scripts/debug/accept.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "tsx src/config.test.ts && tsx src/hooks.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
+    "test": "tsx src/config.test.ts && tsx src/logger.test.ts && tsx src/hooks.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "release:check": "node scripts/release-version.mjs check",
     "release:tag-check": "node scripts/release-version.mjs tag",

package/scripts/debug/accept.mjs

@@ -10,6 +10,7 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
+import { homedir, tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import {
@@ -30,6 +31,7 @@ const gitProject = resolve(acceptanceRoot, "git-project");
 const releaseProject = resolve(acceptanceRoot, "release-project");
 const releaseRemote = resolve(acceptanceRoot, "release-remote.git");
 const ownerToken = randomBytes(32).toString("base64url");
+const tempAcceptanceRoot = resolve(tmpdir(), `forgerelay-debug-acceptance-${randomUUID()}`);
 
 assertCurlAvailable();
 await assertDebugPortFree();
@@ -144,6 +146,37 @@ try {
   assert.equal(failedEdit.isError, true);
   pass("failed tool path", "edit returned isError=true and triggered AfterToolFailure");
 
+  mkdirSync(tempAcceptanceRoot, { recursive: true });
+  const tempFile = join(tempAcceptanceRoot, "mcp-temp.txt");
+  const tempWritten = callTool(oauth.accessToken, sessionId, 70, "write", {
+    workspaceId,
+    path: tempFile,
+    content: "forgerelay temp before edit\n",
+  });
+  assert.equal(tempWritten.isError, undefined);
+
+  const tempRead = callTool(oauth.accessToken, sessionId, 71, "read", {
+    workspaceId,
+    path: tempFile,
+  });
+  assert.match(tempRead.structuredContent.result, /forgerelay temp before edit/);
+
+  const tempEdited = callTool(oauth.accessToken, sessionId, 72, "edit", {
+    workspaceId,
+    path: tempFile,
+    edits: [{ oldText: "before edit", newText: "after edit" }],
+  });
+  assert.equal(tempEdited.isError, undefined);
+  assert.equal(readFileSync(tempFile, "utf8"), "forgerelay temp after edit\n");
+
+  const outsideRoots = callTool(oauth.accessToken, sessionId, 73, "read", {
+    workspaceId,
+    path: join(homedir(), "forgerelay-debug-outside-roots.txt"),
+  });
+  assert.equal(outsideRoots.isError, true);
+  assert.match(toolText(outsideRoots), /outside allowed roots/i);
+  pass("OS temp file tools", "write + read + edit passed; arbitrary home path rejected");
+
   setupGitProject(gitProject);
   const worktreeOpened = callTool(oauth.accessToken, sessionId, 8, "open_workspace", {
     path: gitProject,
@@ -211,6 +244,7 @@ try {
   console.error("\nForgeRelay 7677 acceptance failed.");
   throw error;
 } finally {
+  rmSync(tempAcceptanceRoot, { recursive: true, force: true });
   await stopServer(server);
 }