@akira-tl/forgerelay 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-09-09
+
+### Added
+
+- Added first-class image transport to the existing `read` tool for PNG, JPEG, WebP, and GIF, with magic-byte detection, unchanged image bytes, mixed bulk Read support, and explicit rejection of text ranges on image targets.
+- Added registered external MCP servers through the existing workspace-scoped `capability` surface, including direct upstream `ImageContent` forwarding without expanding the always-visible core tool list.
+- Added opt-in `ExternalMcpBeforeForward` and `ExternalMcpAfterForward` transform Hooks for server/tool-specific request or result adaptation while keeping path/URL/resource references pass-through by default.
+
+### Changed
+
+- Workspace Relay now preserves MCP image content opaquely through Execution → Gateway routing and re-applies the Gateway media budget before Host delivery.
+- Media payloads are transient MCP content rather than Artifacts: the default decoded-media budget is 20 MiB per tool result, aggregate media is bounded, and structured output, Activity/Audit, UI state, and logs retain metadata instead of image base64.
+
+### Security
+
+- External MCP errors, Hook transforms, Relay ingress, and image Reads now enforce bounded media validation without persisting raw image payloads or credentials, and external path/URL/resource results are never implicitly dereferenced by ForgeRelay.
+
+## [1.0.1] - 2026-09-09
+
+### Fixed
+
+- Preserved Capability names/actions and Workspace lifecycle actions in default pretty tool-call logs instead of collapsing multiplexed operations to generic `ok` lines.
+- Completed attributable tool-call logging for Composite member mutations, checkout/Composite close and delete paths, and Composite-owned `workspace.tasks` success/failure results without logging arbitrary capability arguments.
+- Preserved deletion of closed checkout Workspaces through historical aliases while adding lifecycle logging, avoiding a regression in the existing close/reopen/delete contract.
+
 ## [1.0.0] - 2026-09-07
 
 ### Changed

package/README.md

@@ -108,6 +108,7 @@ ForgeRelay 不会默认为每个任务创建 worktree。只有你明确要求隔
 - 项目里的 `AGENTS.md`、`CLAUDE.md` 和 Agent Skills 按需加载，不会每次都把整套说明重新塞进上下文。
 - 需要并行开发时可以创建真实 Git worktree；集成回主分支时只接受安全的 fast-forward，不自动制造 merge conflict。
 - Workspace Relay 可以把执行放到另一台 ForgeRelay；Composite Workspace 可以同时协调几个独立环境。
+- `read` 可以直接把 PNG、JPEG、WebP 和 GIF 作为临时 MCP Media content 返回；配置好的外部 MCP 也通过 `mcp.external` Capability 转发图片，而不会自动打开它返回的路径或 URL。
 
 Lifecycle Hooks、Workspace Tasks、本地 Subagent、Activity/Audit、Checkpoint 和 Recovery 也已经包含在项目里，但第一次安装时不需要先学这些。需要哪个，再去 [Wiki](https://github.com/Akira-TL/forgerelay/wiki) 查哪个。
 
@@ -220,6 +221,7 @@ Long commands do not require tight polling either. Once the current wait window
 - `AGENTS.md`, `CLAUDE.md`, and Agent Skills are loaded as needed instead of being resent in full on every open.
 - Managed worktrees provide real Git isolation when you ask for parallel work, with fast-forward-only finalization.
 - Workspace Relay runs work on another ForgeRelay instance; Composite Workspaces coordinate several independent environments from one Host.
+- `read` can return PNG, JPEG, WebP, and GIF directly as transient MCP Media content; configured external MCP servers can forward images through the `mcp.external` Capability without ForgeRelay automatically opening returned paths or URLs.
 
 Lifecycle Hooks, Workspace Tasks, local Subagents, Activity/Audit, checkpoints, and recovery are included too. They are optional parts of the workflow; the [Wiki](https://github.com/Akira-TL/forgerelay/wiki) documents them when you need them.
 

package/capabilities/host-integration/external-mcp/GUIDE.md

@@ -0,0 +1,29 @@
+# External MCP
+
+Use `mcp.external` only for MCP servers the user has already configured in ForgeRelay. The Host remains the orchestrator: discover the configured server/tool surface, then explicitly choose the server, tool, and arguments for each call.
+
+## Operations
+
+- `servers` — list configured server names and transport kinds. Connection details and credentials are not returned.
+- `tools` — list the tools advertised by one configured server.
+- `call` — invoke one tool that the selected configured server currently advertises.
+
+## Boundaries
+
+- A capability call cannot supply a new MCP command, URL, credential, or connection target. Those belong to user configuration.
+- ForgeRelay forwards the upstream MCP result. A path, URL, resource identifier, or textual file reference stays a reference; ForgeRelay does not automatically fetch it, call `read`, infer that it is an image, or create an Artifact.
+- When an upstream result names an accessible Workspace file and you need its contents, make an explicit ForgeRelay `read` call.
+- Direct upstream `ImageContent` for PNG, JPEG, WebP, and GIF is forwarded as transient Media content after MIME/base64 validation and the configured aggregate media budget. Image base64 exists only in the live MCP result; structured/Activity state keeps bounded MIME/byte metadata.
+- Audio and arbitrary binary-resource forwarding are outside this Media contract. A path, URL, `resource_link`, or other non-media reference is not upgraded into an image automatically.
+- ForgeRelay does not autonomously chain external MCP tools or retry through another configured server.
+- External MCP processes/services keep the operating-system and network authority with which the user configured them. Routing through ForgeRelay does not make them a ForgeRelay filesystem sandbox.
+- Hook policy may inspect or block Capability calls. Server/tool-specific transforms use the explicit `ExternalMcpBeforeForward` / `ExternalMcpAfterForward` contract; ordinary Hook stdout never rewrites MCP data.
+
+## Optional transform Hooks
+
+Transform Hooks are opt-in user policy for one configured external MCP server/tool. Match them with `tool: "capability"`, `capability: "mcp.external"`, `externalServer`, and `externalTool`. ForgeRelay passes the current transform value over stdin as versioned JSON and accepts one structured stdout envelope only.
+
+- Before forward: stdout must be `{"version":1,"request":{"arguments":{...}}}`. Only arguments can change; the configured server/tool target cannot.
+- After forward: stdout must be `{"version":1,"result":{...}}`. The transformed result is revalidated as an MCP result and any ImageContent is rechecked against the normal MIME/base64/media-budget rules.
+- A transform command may deliberately read a renderer-owned path or perform other work using the command's own OS authority. That is explicit Hook behavior, not an implicit ForgeRelay `read`, fetch, or Artifact operation.
+- Activity/log state records only bounded transform identity/status metadata. Transform stdin/stdout, arbitrary upstream payloads, credentials, and image base64 are not persisted by ForgeRelay.

package/capabilities/lifecycle-hooks/GUIDE.md

@@ -22,17 +22,27 @@
 - 可选 timeout；
 - 可选 `report`，默认 `true`。
 
-当前事件包括：`WorkspaceOpen`、`BeforeTool`、`AfterTool`、`AfterToolFailure`、`AfterFileChange`、`BeforeWorktreeClose`、`AfterWorktreeClose`、`SubagentStart`、`SubagentStop`。
+当前事件包括：`WorkspaceOpen`、`BeforeTool`、`AfterTool`、`AfterToolFailure`、`ExternalMcpBeforeForward`、`ExternalMcpAfterForward`、`AfterFileChange`、`BeforeWorktreeClose`、`AfterWorktreeClose`、`SubagentStart`、`SubagentStop`。
+
+External MCP transform 事件只用于 `mcp.external`。matcher 可额外使用 `capability`、`externalServer`、`externalTool`，从而绑定到已配置的 Capability/server/tool；这些字段只是现有目标的匹配条件，不能动态指定新的连接目标。
 
 ## 阻断与报告
 
-`BeforeTool` 和 `BeforeWorktreeClose` 是阻断事件。命中的 Hook 失败或超时后，原操作不会继续。其他 after-event 只观察已经发生的结果，失败不会伪装成能够回滚先前副作用。
+`BeforeTool`、`BeforeWorktreeClose` 以及两个 External MCP transform 事件都会在失败时令当前操作失败。Before-forward transform 失败时 upstream MCP call 不会发生；After-forward transform 失败时 upstream call 已经发生，只会阻止变换后结果继续交付并把 Capability 标成失败，不能声称回滚 upstream 已产生的副作用。其他普通 after-event 只观察已经发生的结果，失败也不会伪装成能够回滚先前副作用。
 
 Hook report 会随工具结果返回给 Host/Agent。`report: false` 只隐藏成功的高频报告；阻断失败始终可见。Agent 看到有意义的 Hook report 时必须告诉用户哪些 Hook 运行了、是否通过，以及操作是否被阻断；不能在 blocking Hook 阻止操作后声称原操作成功。
 
+## External MCP transform 协议
+
+普通 Hook 的 stdout 仍然只是命令输出，**不会**改写工具结果。只有 `ExternalMcpBeforeForward` / `ExternalMcpAfterForward` 使用显式 structured transform 协议：ForgeRelay 将 versioned JSON 写入 Hook stdin，并只接受 stdout 中一个合法 JSON envelope。
+
+- request phase 输入包含当前 `server`、`tool` 与 `request.arguments`；输出必须是 `{"version":1,"request":{"arguments":{...}}}`。server/tool 不能被改写。
+- result phase 输入包含当前 upstream MCP result；输出必须是 `{"version":1,"result":{...}}`。输出随后重新经过标准 MCP result、Media MIME/base64 与 `mediaMaxBytes` 校验。
+- Hook 环境中的 `FORGERELAY_HOOK_PAYLOAD` 只包含 Capability/server/tool/phase 等有界匹配元数据；任意 arguments、upstream payload 和 image base64 只通过 transform stdin/stdout 瞬态传递。
+
 ## 安全边界
 
-项目 Hook 属于项目执行约定，不需要额外审批，但不能扩大 allowed roots、覆盖认证边界或替换机器级全局规则。Hook command 与 shell 一样以运行 ForgeRelay 的本地用户权限执行；工作区文件边界不等于 OS sandbox。
+项目 Hook 属于项目执行约定，不需要额外审批，但不能扩大 allowed roots、覆盖认证边界或替换机器级全局规则。Hook command 与 shell 一样以运行 ForgeRelay 的本地用户权限执行；工作区文件边界不等于 OS sandbox。Transform Hook 如果主动读取文件或访问网络，那是该用户配置命令自身的 OS 权限，不代表 ForgeRelay 自动获得了新的 `read` 或网络权限。
 
 ## 检查入口
 

package/dist/mcp/filesystem/filesystem-tools.js

@@ -2,6 +2,7 @@ import { constants } from "node:fs";
 import { access, mkdir, readFile, realpath, writeFile, } from "node:fs/promises";
 import { dirname } from "node:path";
 import { createPatch } from "diff";
+import { claimMediaBytes } from "../operations/media-content.js";
 import { resolveCanonicalAllowedPath } from "./roots.js";
 const DEFAULT_MAX_LINES = 2_000;
 const DEFAULT_MAX_BYTES = 50 * 1_024;
@@ -22,9 +23,14 @@ export async function readFileTool(input, context) {
         const buffer = await readFile(path);
         const mimeType = supportedImageMimeType(buffer);
         if (mimeType) {
+            if (input.offset !== undefined || input.limit !== undefined) {
+                throw new Error("Image reads do not accept offset or limit.");
+            }
+            if (context.mediaBudget)
+                claimMediaBytes(context.mediaBudget, buffer.byteLength);
             return {
                 content: [
-                    { type: "text", text: `Read image file [${mimeType}]` },
+                    { type: "text", text: `Read image file [${mimeType}; ${buffer.byteLength} bytes]` },
                     { type: "image", data: buffer.toString("base64"), mimeType },
                 ],
             };
@@ -208,8 +214,6 @@ function supportedImageMimeType(buffer) {
         buffer.subarray(0, 4).toString("ascii") === "RIFF" &&
         buffer.subarray(8, 12).toString("ascii") === "WEBP")
         return "image/webp";
-    if (buffer.length >= 2 && buffer.subarray(0, 2).toString("ascii") === "BM")
-        return "image/bmp";
     return undefined;
 }
 async function withMutationQueue(path, operation) {

package/dist/mcp/hooks/command-runner.js

@@ -10,7 +10,7 @@ export function executeHookCommand(input) {
             detached: input.detached,
             windowsHide: true,
             windowsVerbatimArguments: input.windowsVerbatimArguments,
-            stdio: ["ignore", "pipe", "pipe"],
+            stdio: [input.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
         });
         let stdout = "";
         let stderr = "";
@@ -28,12 +28,17 @@ export function executeHookCommand(input) {
             forceKillTimer.unref();
         };
         input.signal?.addEventListener("abort", abort, { once: true });
+        const maxCaptureBytes = input.maxCaptureBytes ?? MAX_CAPTURE_BYTES;
         child.stdout?.on("data", (chunk) => {
-            stdout = appendCaptured(stdout, chunk);
+            stdout = appendCaptured(stdout, chunk, maxCaptureBytes);
         });
         child.stderr?.on("data", (chunk) => {
-            stderr = appendCaptured(stderr, chunk);
+            stderr = appendCaptured(stderr, chunk, maxCaptureBytes);
         });
+        if (input.stdin !== undefined) {
+            child.stdin?.on("error", () => undefined);
+            child.stdin?.end(input.stdin);
+        }
         const timeout = setTimeout(() => {
             timedOut = true;
             terminateProcessTree(child, "SIGTERM", input.detached);
@@ -65,13 +70,13 @@ export function executeHookCommand(input) {
         });
     });
 }
-function appendCaptured(current, chunk) {
-    if (Buffer.byteLength(current) >= MAX_CAPTURE_BYTES)
+function appendCaptured(current, chunk, maxBytes) {
+    if (Buffer.byteLength(current) >= maxBytes)
         return current;
     const next = current + chunk.toString();
-    if (Buffer.byteLength(next) <= MAX_CAPTURE_BYTES)
+    if (Buffer.byteLength(next) <= maxBytes)
         return next;
-    return Buffer.from(next).subarray(0, MAX_CAPTURE_BYTES).toString("utf8");
+    return Buffer.from(next).subarray(0, maxBytes).toString("utf8");
 }
 export function hookFailureOutput(stdout, stderr) {
     const output = (stderr.trim() || stdout.trim()).replace(/\s+/g, " ");

package/dist/mcp/hooks/external-mcp-transform.js

@@ -0,0 +1,224 @@
+import { performance } from "node:perf_hooks";
+import { commandPreview, logEvent, workspaceLogLabel } from "../../runtime/logging/logger.js";
+import { resolveCompatibilityCommandShellRuntime, snapshotCommandShellRuntime, } from "../../runtime/shell/command-shell-runtime.js";
+import { resolveShellCommandForRuntime } from "../process/process-platform.js";
+import { executeHookCommand } from "./command-runner.js";
+import { loadProjectHookConfig, matchHookRule, } from "./hooks.js";
+export class ExternalMcpTransformError extends Error {
+    server;
+    tool;
+    hookName;
+    constructor(server, tool, hookName, message) {
+        super(message);
+        this.server = server;
+        this.tool = tool;
+        this.hookName = hookName;
+        this.name = "ExternalMcpTransformError";
+    }
+}
+const TRANSFORM_PROTOCOL_VERSION = 1;
+const MIN_TRANSFORM_CAPTURE_BYTES = 1024 * 1024;
+const TRANSFORM_CAPTURE_OVERHEAD_BYTES = 256 * 1024;
+export class ExternalMcpTransformRunner {
+    hooks;
+    logging;
+    baseEnv;
+    commandShellRuntime;
+    maxCaptureBytes;
+    constructor(hooks, logging, baseEnv = process.env, commandShellRuntime, mediaMaxBytes = 20 * 1024 * 1024) {
+        this.hooks = hooks;
+        this.logging = logging;
+        this.baseEnv = baseEnv;
+        this.commandShellRuntime = snapshotCommandShellRuntime(commandShellRuntime ?? resolveCompatibilityCommandShellRuntime(process.platform, baseEnv));
+        this.maxCaptureBytes = Math.max(MIN_TRANSFORM_CAPTURE_BYTES, Math.ceil((mediaMaxBytes * 4) / 3) + TRANSFORM_CAPTURE_OVERHEAD_BYTES);
+    }
+    async transformRequest(context, arguments_, signal) {
+        return this.run("request", context, arguments_, signal);
+    }
+    async transformResult(context, result, signal) {
+        return this.run("result", context, result, signal);
+    }
+    async run(phase, context, initialValue, signal) {
+        signal?.throwIfAborted();
+        const event = phase === "request"
+            ? "ExternalMcpBeforeForward"
+            : "ExternalMcpAfterForward";
+        const invocation = {
+            workspaceId: context.workspaceId,
+            workspaceRoot: context.workspaceRoot,
+            workspaceMode: context.workspaceMode,
+            payload: transformMetadata(context, phase),
+        };
+        const project = await loadProjectHookConfig(context.workspaceRoot);
+        const handlers = [
+            ...(this.hooks[event] ?? []).map((rule) => ({ scope: "global", rule })),
+            ...(project.hooks[event] ?? []).map((rule) => ({ scope: "project", rule })),
+        ].flatMap(({ scope, rule }) => {
+            const matched = matchHookRule(rule.matcher, invocation);
+            if (!matched)
+                return [];
+            return rule.handlers.map((handler) => ({ scope, handler }));
+        });
+        let value = initialValue;
+        const transforms = [];
+        for (const [index, entry] of handlers.entries()) {
+            signal?.throwIfAborted();
+            const execution = await this.runHandler(event, phase, context, entry.handler, entry.scope, index, value, signal);
+            value = execution.value;
+            transforms.push({
+                phase,
+                name: execution.report.name,
+                scope: execution.report.scope,
+                status: "passed",
+            });
+        }
+        return { value, transforms };
+    }
+    async runHandler(event, phase, context, handler, scope, index, currentValue, signal) {
+        const startedAt = performance.now();
+        const name = handler.name ?? `${event} handler ${index + 1}`;
+        const shell = resolveShellCommandForRuntime(handler.command, this.commandShellRuntime);
+        const detached = process.platform !== "win32";
+        const metadata = transformMetadata(context, phase);
+        const env = {
+            ...this.baseEnv,
+            FORGERELAY_HOOK_EVENT: event,
+            FORGERELAY_HOOK_PAYLOAD: JSON.stringify(metadata),
+            FORGERELAY_WORKSPACE_ROOT: context.workspaceRoot,
+            FORGERELAY_WORKSPACE_ID: context.workspaceId,
+            FORGERELAY_WORKSPACE_MODE: context.workspaceMode,
+            FORGERELAY_TOOL_NAME: "capability",
+            FORGERELAY_CAPABILITY_NAME: "mcp.external",
+            FORGERELAY_EXTERNAL_MCP_SERVER: context.server,
+            FORGERELAY_EXTERNAL_MCP_TOOL: context.tool,
+            FORGERELAY_TRANSFORM_PHASE: phase,
+        };
+        const stdin = JSON.stringify(transformInput(phase, context, currentValue));
+        try {
+            const result = await executeHookCommand({
+                executable: shell.executable,
+                args: shell.args,
+                windowsVerbatimArguments: shell.windowsVerbatimArguments,
+                cwd: context.workspaceRoot,
+                env,
+                timeoutMs: handler.timeoutSeconds * 1_000,
+                detached,
+                signal,
+                stdin,
+                maxCaptureBytes: this.maxCaptureBytes,
+            });
+            const durationMs = Math.round(performance.now() - startedAt);
+            if (result.exitCode !== 0 || result.timedOut || result.signal) {
+                const reason = result.timedOut
+                    ? `timed out after ${handler.timeoutSeconds}s`
+                    : result.signal
+                        ? `terminated by ${result.signal}`
+                        : `exited with code ${result.exitCode ?? "unknown"}`;
+                this.logTransform(event, name, scope, context, false, durationMs, reason, handler.command);
+                throw this.error(context, name, `transform Hook ${name} ${reason}.`);
+            }
+            let value;
+            try {
+                value = parseTransformOutput(phase, result.stdout);
+            }
+            catch {
+                this.logTransform(event, name, scope, context, false, durationMs, "invalid structured transform output", handler.command);
+                throw this.error(context, name, `transform Hook ${name} returned invalid structured transform output.`);
+            }
+            this.logTransform(event, name, scope, context, true, durationMs, undefined, handler.command);
+            return {
+                value,
+                report: {
+                    event,
+                    name: boundedName(name),
+                    scope,
+                    status: "passed",
+                    durationMs,
+                    report: handler.report,
+                },
+            };
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw error;
+            if (error instanceof ExternalMcpTransformError)
+                throw error;
+            const durationMs = Math.round(performance.now() - startedAt);
+            this.logTransform(event, name, scope, context, false, durationMs, "failed to start", handler.command);
+            throw this.error(context, name, `transform Hook ${name} failed to start.`);
+        }
+    }
+    error(context, name, detail) {
+        return new ExternalMcpTransformError(context.server, context.tool, boundedName(name), `External MCP ${context.server} tool ${context.tool} ${detail}`);
+    }
+    logTransform(event, name, scope, context, success, durationMs, error, command) {
+        logEvent(this.logging, success ? "info" : "warn", "hook_call", {
+            hookEvent: event,
+            hookName: boundedName(name),
+            hookScope: scope,
+            workspaceId: context.workspaceId,
+            workspace: workspaceLogLabel(context.workspaceRoot, context.workspaceId),
+            capability: "mcp.external",
+            externalServer: context.server,
+            externalTool: context.tool,
+            success,
+            durationMs,
+            error,
+            commandPreview: this.logging.shellCommands ? commandPreview(command) : undefined,
+        });
+    }
+}
+function transformMetadata(context, phase) {
+    return {
+        tool: "capability",
+        capability: "mcp.external",
+        externalServer: context.server,
+        externalTool: context.tool,
+        transformPhase: phase,
+    };
+}
+function transformInput(phase, context, value) {
+    const base = {
+        version: TRANSFORM_PROTOCOL_VERSION,
+        phase,
+        capability: "mcp.external",
+        server: context.server,
+        tool: context.tool,
+    };
+    return phase === "request"
+        ? { ...base, request: { arguments: value } }
+        : { ...base, result: value };
+}
+function parseTransformOutput(phase, stdout) {
+    const text = stdout.trim();
+    if (!text)
+        throw new Error("empty transform output");
+    const value = JSON.parse(text);
+    if (!isRecord(value) || value.version !== TRANSFORM_PROTOCOL_VERSION) {
+        throw new Error("invalid transform envelope");
+    }
+    const allowedKeys = phase === "request"
+        ? new Set(["version", "request"])
+        : new Set(["version", "result"]);
+    if (Object.keys(value).some((key) => !allowedKeys.has(key))) {
+        throw new Error("unexpected transform envelope field");
+    }
+    if (phase === "request") {
+        if (!isRecord(value.request) || !isRecord(value.request.arguments)) {
+            throw new Error("invalid request transform output");
+        }
+        if (Object.keys(value.request).some((key) => key !== "arguments")) {
+            throw new Error("unexpected request transform field");
+        }
+        return value.request.arguments;
+    }
+    if (!isRecord(value.result))
+        throw new Error("invalid result transform output");
+    return value.result;
+}
+function boundedName(value) {
+    return value.length > 200 ? `${value.slice(0, 197)}...` : value;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/mcp/hooks/hook-cli.js

@@ -98,6 +98,9 @@ function formatMatcher(matcher) {
         matcher.pathRegex ? `pathRegex=${matcher.pathRegex}` : undefined,
         matcher.provider ? `provider=${matcher.provider}` : undefined,
         matcher.workspaceMode ? `workspaceMode=${matcher.workspaceMode}` : undefined,
+        matcher.capability ? `capability=${matcher.capability}` : undefined,
+        matcher.externalServer ? `externalServer=${matcher.externalServer}` : undefined,
+        matcher.externalTool ? `externalTool=${matcher.externalTool}` : undefined,
     ].filter((value) => value !== undefined);
     return parts.length > 0 ? parts.join(" ") : "matcher=*";
 }

package/dist/mcp/hooks/hooks.js

@@ -10,6 +10,8 @@ export const HOOK_EVENTS = [
     "BeforeTool",
     "AfterTool",
     "AfterToolFailure",
+    "ExternalMcpBeforeForward",
+    "ExternalMcpAfterForward",
     "AfterFileChange",
     "BeforeWorktreeClose",
     "AfterWorktreeClose",
@@ -20,7 +22,12 @@ const DEFAULT_HOOK_TIMEOUT_SECONDS = 30;
 const MAX_HOOK_TIMEOUT_SECONDS = 300;
 const PROJECT_HOOKS_PATH = join(".forgerelay", "hooks.json");
 const PROJECT_HOOKS_DIR = join(".forgerelay", "hooks");
-const BLOCKING_EVENTS = new Set(["BeforeTool", "BeforeWorktreeClose"]);
+const BLOCKING_EVENTS = new Set([
+    "BeforeTool",
+    "ExternalMcpBeforeForward",
+    "ExternalMcpAfterForward",
+    "BeforeWorktreeClose",
+]);
 const EVENT_SET = new Set(HOOK_EVENTS);
 export class HookExecutionError extends Error {
     event;
@@ -389,7 +396,34 @@ function parseHookMatcher(event, value, index) {
         }
         matcher.workspaceMode = value.workspaceMode;
     }
-    const knownKeys = new Set(["tool", "commandRegex", "pathRegex", "provider", "workspaceMode"]);
+    if (value.capability !== undefined) {
+        if (typeof value.capability !== "string" || value.capability.trim().length === 0) {
+            throw new Error(`Hook ${event} matcher capability must be a non-empty string`);
+        }
+        matcher.capability = value.capability.trim();
+    }
+    if (value.externalServer !== undefined) {
+        if (typeof value.externalServer !== "string" || value.externalServer.trim().length === 0) {
+            throw new Error(`Hook ${event} matcher externalServer must be a non-empty string`);
+        }
+        matcher.externalServer = value.externalServer.trim();
+    }
+    if (value.externalTool !== undefined) {
+        if (typeof value.externalTool !== "string" || value.externalTool.trim().length === 0) {
+            throw new Error(`Hook ${event} matcher externalTool must be a non-empty string`);
+        }
+        matcher.externalTool = value.externalTool.trim();
+    }
+    const knownKeys = new Set([
+        "tool",
+        "commandRegex",
+        "pathRegex",
+        "provider",
+        "workspaceMode",
+        "capability",
+        "externalServer",
+        "externalTool",
+    ]);
     const unknownKey = Object.keys(value).find((key) => !knownKeys.has(key));
     if (unknownKey) {
         throw new Error(`Unknown Hook ${event} matcher field: ${unknownKey}`);
@@ -472,7 +506,7 @@ export async function loadProjectHookConfig(workspaceRoot) {
         ...(diagnostics.length > 0 ? { diagnostic: diagnostics.join(" | ") } : {}),
     };
 }
-function matchHookRule(matcher, invocation) {
+export function matchHookRule(matcher, invocation) {
     if (!matcher)
         return invocation;
     if (matcher.workspaceMode && invocation.workspaceMode !== matcher.workspaceMode)
@@ -517,6 +551,18 @@ function matchHookRule(matcher, invocation) {
             return undefined;
         }
     }
+    if (matcher.capability) {
+        if (invocation.payload?.capability !== matcher.capability)
+            return undefined;
+    }
+    if (matcher.externalServer) {
+        if (invocation.payload?.externalServer !== matcher.externalServer)
+            return undefined;
+    }
+    if (matcher.externalTool) {
+        if (invocation.payload?.externalTool !== matcher.externalTool)
+            return undefined;
+    }
     return matchedInvocation;
 }
 function hookEnvironment(baseEnv, event, invocation) {

package/dist/mcp/operations/bulk-read.js

@@ -1,24 +1,25 @@
 export async function executeBulkRead(options) {
-    const children = await Promise.all(options.paths.map(async (path) => {
+    const children = [];
+    for (const path of options.paths) {
         try {
             const response = await options.run(path);
-            return {
+            children.push({
                 path,
                 status: options.isError(response) ? "error" : "done",
                 result: options.resultText(response),
                 response,
-            };
+            });
         }
         catch (error) {
             if (options.signal?.aborted)
                 throw error;
-            return {
+            children.push({
                 path,
                 status: "error",
                 result: error instanceof Error ? error.message : String(error),
-            };
+            });
         }
-    }));
+    }
     const failed = children.filter((child) => child.status === "error").length;
     return {
         children,

package/dist/mcp/operations/external-mcp/external-mcp-runtime.js

@@ -0,0 +1,42 @@
+import { CapabilityError } from "../../server/core/capability-registry.js";
+import { requireCapabilityWorkspaceRoot } from "../../server/core/capability-support.js";
+import { ExternalMcpTransformError, ExternalMcpTransformRunner, } from "../../hooks/external-mcp-transform.js";
+import { ExternalMcpError, ExternalMcpGateway } from "./external-mcp.js";
+export function createExternalMcpCapabilityRuntime(config) {
+    const externalMcp = new ExternalMcpGateway(config.mcpServers, config.mediaMaxBytes);
+    const transforms = new ExternalMcpTransformRunner(config.hooks, config.logging, process.env, config.commandShellRuntime, config.mediaMaxBytes);
+    return {
+        available: externalMcp.available,
+        unavailableReason: externalMcp.available ? undefined : "No external MCP servers are configured.",
+        run: async (input, context, runOptions) => {
+            try {
+                const transformContext = (server, tool) => ({
+                    workspaceId: context.workspaceId,
+                    workspaceRoot: requireCapabilityWorkspaceRoot(context),
+                    workspaceMode: context.workspaceMode,
+                    server,
+                    tool,
+                });
+                const result = await externalMcp.run(input, runOptions.signal, input.operation === "call"
+                    ? {
+                        request: (server, tool, arguments_) => transforms.transformRequest(transformContext(server, tool), arguments_, runOptions.signal),
+                        result: (server, tool, externalResult) => transforms.transformResult(transformContext(server, tool), externalResult, runOptions.signal),
+                    }
+                    : undefined);
+                return {
+                    value: result.value,
+                    ...(result.content ? { content: result.content } : {}),
+                };
+            }
+            catch (error) {
+                if (error instanceof ExternalMcpTransformError) {
+                    throw new CapabilityError("mcp.transform_failed", error.message);
+                }
+                if (error instanceof ExternalMcpError) {
+                    throw new CapabilityError(`mcp.${error.code}`, error.message);
+                }
+                throw error;
+            }
+        },
+    };
+}