@akira-tl/forgerelay 1.0.1 → 1.1.1

package/dist/cli/mcp/status.js

@@ -0,0 +1,295 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { loadConfig } from "../../runtime/config/config.js";
+import { ExternalMcpCredentialStore, externalMcpCredentialIdentity, } from "../../runtime/config/external-mcp-auth-store.js";
+import { ExternalMcpConfigRegistry, } from "../../runtime/config/external-mcp-registry.js";
+export function resolveExternalMcpScope(request, dependencies = {}) {
+    if (request.global && request.projectRoot) {
+        throw new Error("--global and --project cannot be used together.");
+    }
+    const env = dependencies.env ?? process.env;
+    const config = loadConfig(env);
+    const cwd = resolve(dependencies.cwd ?? process.cwd());
+    const registry = new ExternalMcpConfigRegistry({
+        configDir: config.configDir,
+        legacyServers: config.mcpServers,
+    });
+    const store = new ExternalMcpCredentialStore({ configDir: config.configDir });
+    if (request.global) {
+        return {
+            mode: "global",
+            projectRoot: cwd,
+            projectSelection: "global",
+            config,
+            registry,
+            snapshot: registry.resolveGlobal(),
+            store,
+        };
+    }
+    const selected = selectProjectRoot(request.projectRoot, cwd, env);
+    return {
+        mode: "project",
+        projectRoot: selected.root,
+        projectSelection: selected.selection,
+        config,
+        registry,
+        snapshot: registry.resolve(selected.root),
+        store,
+    };
+}
+export function inspectExternalMcpStatus(scope) {
+    let credentialStore = "missing";
+    let credentialStoreMessage;
+    try {
+        credentialStore = scope.store.inspect().exists ? "ok" : "missing";
+    }
+    catch (error) {
+        credentialStore = "invalid";
+        credentialStoreMessage = boundedStatusMessage(error);
+    }
+    const effective = Object.entries(scope.snapshot.servers).map(([name, config]) => {
+        const source = scope.snapshot.origins[name];
+        return serverStatus(scope, name, source, config, credentialStore === "invalid");
+    });
+    const disabled = Object.entries(scope.snapshot.masked).map(([name, source]) => ({
+        name,
+        source,
+        enabled: false,
+    }));
+    const servers = [...effective, ...disabled].sort((left, right) => left.name.localeCompare(right.name));
+    return {
+        scope,
+        servers,
+        configIssues: scope.snapshot.sources.filter((source) => source.state === "invalid").length
+            + (credentialStore === "invalid" ? 1 : 0),
+        credentialStore,
+        ...(credentialStoreMessage ? { credentialStoreMessage } : {}),
+    };
+}
+export function findExternalMcpServerStatus(status, name) {
+    return status.servers.find((server) => server.name === name);
+}
+export function formatExternalMcpList(status) {
+    const lines = ["External MCP", ""];
+    if (status.scope.mode === "global") {
+        lines.push("Scope: global");
+    }
+    else {
+        lines.push("Scope: project", `Project: ${status.scope.projectRoot}`);
+    }
+    lines.push("", "Config:");
+    for (const source of status.scope.snapshot.sources) {
+        lines.push(`  ${source.source.padEnd(7)} ${source.path} · ${formatConfigSourceState(source, status)}`);
+    }
+    if (status.credentialStore === "invalid") {
+        lines.push(`  auth    ${status.scope.store.filePath} · invalid`);
+        if (status.credentialStoreMessage)
+            lines.push(`          ${status.credentialStoreMessage}`);
+    }
+    else {
+        lines.push(`  auth    ${status.scope.store.filePath} · ${status.credentialStore}`);
+    }
+    lines.push("", "Servers:");
+    if (status.servers.length === 0) {
+        lines.push("  none");
+    }
+    else {
+        for (const server of status.servers) {
+            lines.push(`  ${server.name}`);
+            lines.push(`    source: ${server.source}`);
+            if (!server.enabled) {
+                lines.push("    status: disabled");
+                continue;
+            }
+            lines.push(`    transport: ${server.transport}`);
+            lines.push(`    auth: ${formatAuth(server)}`);
+            lines.push("    status: configured");
+        }
+    }
+    if (status.scope.snapshot.diagnostics.length > 0) {
+        lines.push("", "Config issues:");
+        for (const diagnostic of status.scope.snapshot.diagnostics) {
+            const source = status.scope.snapshot.sources.find((candidate) => candidate.source === diagnostic.source);
+            lines.push(`  ${diagnostic.source}: ${diagnostic.message}`);
+            if (source?.usingLastKnownGood) {
+                lines.push("    Using this process's last-known-good configuration.");
+            }
+            else {
+                lines.push("    Existing ForgeRelay runtimes that loaded a valid version may continue using last-known-good configuration.");
+            }
+        }
+    }
+    return lines.join("\n");
+}
+export function formatExternalMcpDoctor(status) {
+    const enabled = status.servers.filter((server) => server.enabled);
+    const disabled = status.servers.length - enabled.length;
+    const authenticated = enabled.filter((server) => server.authState === "authenticated").length;
+    const authRequired = enabled.filter((server) => server.authState === "auth-required").length;
+    const reauthRequired = enabled.filter((server) => server.authState === "reauth-required").length;
+    const sourceSummary = status.scope.snapshot.sources
+        .map((source) => `${source.source}=${compactSourceState(source, status)}`)
+        .join(" · ");
+    return [
+        "External MCP:",
+        `  Scope: ${status.scope.mode}${status.scope.mode === "project" ? ` (${status.scope.projectRoot})` : ""}`,
+        `  Config: ${sourceSummary}`,
+        `  Effective servers: ${enabled.length}`,
+        `  Disabled: ${disabled}`,
+        `  OAuth authenticated: ${authenticated}`,
+        `  Auth required: ${authRequired}`,
+        `  Reauthorization required: ${reauthRequired}`,
+        `  Credential store: ${status.credentialStore}`,
+        `  Config issues: ${status.configIssues}`,
+        "  Hot reload: active",
+        "  Active checks: not run (use `forgerelay mcp test <server>`)",
+    ].join("\n");
+}
+export function formatAuth(status) {
+    switch (status.authKind) {
+        case "oauth":
+            if (status.authState === "authenticated")
+                return "oauth · authenticated";
+            if (status.authState === "auth-required")
+                return "oauth · auth required";
+            if (status.authState === "reauth-required")
+                return "oauth · reauthorization required";
+            return "oauth · not authenticated";
+        case "static":
+            return "static · configured";
+        case "config-managed":
+            return "config-managed";
+        case "none-detected":
+        default:
+            return "none detected";
+    }
+}
+function serverStatus(scope, name, source, config, credentialStoreInvalid) {
+    if (config.transport === "stdio") {
+        return {
+            name,
+            source,
+            enabled: true,
+            transport: config.transport,
+            authKind: "config-managed",
+            authState: "configured",
+        };
+    }
+    if (hasStaticAuthorizationHeader(config.headers)) {
+        return {
+            name,
+            source,
+            enabled: true,
+            transport: config.transport,
+            authKind: "static",
+            authState: "configured",
+        };
+    }
+    if (credentialStoreInvalid) {
+        return {
+            name,
+            source,
+            enabled: true,
+            transport: config.transport,
+            authKind: config.oauth ? "oauth" : "none-detected",
+            authState: "not-detected",
+        };
+    }
+    const identity = externalMcpCredentialIdentity(source, name, scope.projectRoot);
+    let record;
+    try {
+        record = scope.store.read(identity);
+    }
+    catch {
+        record = undefined;
+    }
+    const bindingMismatch = record ? !credentialBindingMatches(record, config.url) : false;
+    const authState = bindingMismatch
+        ? "reauth-required"
+        : record?.reauthorization?.reason === "authorization_required" && !record.tokens?.access_token
+            ? "auth-required"
+            : record?.reauthorization
+                ? "reauth-required"
+                : record?.tokens?.access_token
+                    ? "authenticated"
+                    : "not-detected";
+    const authKind = record || config.oauth ? "oauth" : "none-detected";
+    return {
+        name,
+        source,
+        enabled: true,
+        transport: config.transport,
+        authKind,
+        authState,
+    };
+}
+function credentialBindingMatches(record, serverUrl) {
+    try {
+        if (new URL(record.serverUrl).toString() !== new URL(serverUrl).toString())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    const expectedIssuer = record.discoveryState?.authorizationServerMetadata?.issuer
+        ?? record.authorizationServerUrl
+        ?? record.discoveryState?.authorizationServerUrl;
+    if (!expectedIssuer)
+        return true;
+    for (const candidate of [record.tokens?.issuer, record.clientInformation?.issuer]) {
+        if (candidate && candidate !== expectedIssuer)
+            return false;
+    }
+    return true;
+}
+function selectProjectRoot(explicit, cwd, env) {
+    if (explicit)
+        return { root: resolve(explicit), selection: "explicit" };
+    if (env.FORGERELAY_WORKSPACE_ROOT) {
+        return { root: resolve(env.FORGERELAY_WORKSPACE_ROOT), selection: "workspace-env" };
+    }
+    const ancestor = findNearestProjectConfig(cwd);
+    if (ancestor)
+        return { root: ancestor, selection: "ancestor-config" };
+    return { root: cwd, selection: "cwd" };
+}
+function findNearestProjectConfig(start) {
+    let current = resolve(start);
+    while (true) {
+        if (existsSync(join(current, ".forgerelay", "mcp.json")))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+function hasStaticAuthorizationHeader(headers) {
+    return Object.keys(headers ?? {}).some((name) => name.toLowerCase() === "authorization");
+}
+function formatConfigSourceState(source, status) {
+    if (source.source === "legacy") {
+        const legacyCount = status.servers.filter((server) => server.enabled && server.source === "legacy").length;
+        return legacyCount > 0 ? `compatibility · ${legacyCount} server${legacyCount === 1 ? "" : "s"}` : "compatibility · none";
+    }
+    if (source.state === "valid")
+        return "ok";
+    if (source.state === "missing")
+        return "missing";
+    return source.usingLastKnownGood ? "invalid · using last-known-good" : "invalid";
+}
+function compactSourceState(source, status) {
+    if (source.source === "legacy") {
+        return status.servers.some((server) => server.enabled && server.source === "legacy") ? "compat" : "none";
+    }
+    if (source.state === "valid")
+        return "ok";
+    if (source.state === "missing")
+        return "missing";
+    return source.usingLastKnownGood ? "invalid/lkg" : "invalid";
+}
+function boundedStatusMessage(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    const normalized = raw.replace(/\s+/g, " ").trim() || "External MCP status unavailable.";
+    return normalized.length <= 320 ? normalized : `${normalized.slice(0, 317)}...`;
+}

package/dist/cli.js

@@ -12,6 +12,8 @@ import { loadConfig } from "./runtime/config/config.js";
 import { acquireRuntimeLease } from "./runtime/state/runtime-lease.js";
 import { runInit } from "./cli/init.js";
 import { runMaintenanceCommand } from "./cli/maintenance.js";
+import { runExternalMcpCommand } from "./cli/mcp/external-mcp.js";
+import { formatExternalMcpDoctor, inspectExternalMcpStatus, resolveExternalMcpScope, } from "./cli/mcp/status.js";
 import { runHooksCommand } from "./mcp/hooks/hook-cli.js";
 import { executeSubagentSession } from "./subagents/sessions/execution.js";
 import { SubagentDeliveryMailbox } from "./subagents/sessions/delivery-mailbox.js";
@@ -63,6 +65,9 @@ async function main(argv) {
         case "auth":
             await runAuthCommand(args);
             return;
+        case "mcp":
+            await runExternalMcpCommand(args);
+            return;
         case "maintenance":
             runMaintenanceCommand(args);
             return;
@@ -77,7 +82,7 @@ async function main(argv) {
 function normalizeCommand(command) {
     if (!command || command === "serve" || command === "start")
         return "serve";
-    if (command === "init" || command === "doctor" || command === "config" || command === "hooks" || command === "agents" || command === "auth" || command === "maintenance")
+    if (command === "init" || command === "doctor" || command === "config" || command === "hooks" || command === "agents" || command === "auth" || command === "mcp" || command === "maintenance")
         return command;
     if (command === "help" || command === "--help" || command === "-h")
         return "help";
@@ -379,6 +384,10 @@ async function runDoctor() {
         console.log(`Agent-managed Language Server install: ${config.allowAgentLanguageServerInstall ? "enabled" : "disabled"}`);
         console.log(`Allowed roots: ${config.allowedRoots.join(", ")}`);
         console.log(`Allowed hosts: ${config.allowedHosts.join(", ")}`);
+        console.log(formatExternalMcpDoctor(inspectExternalMcpStatus(resolveExternalMcpScope({}, {
+            env: process.env,
+            cwd: process.cwd(),
+        }))));
     }
     catch (error) {
         console.log(`Config status: ${error instanceof Error ? error.message : String(error)}`);
@@ -430,6 +439,10 @@ function printHelp() {
         "  forgerelay auth test <alias>",
         "  forgerelay auth rename <old-alias> <new-alias>",
         "  forgerelay auth remove <alias>",
+        "  forgerelay mcp list [--project <path>|--global]",
+        "  forgerelay mcp test <server> [--project <path>|--global]",
+        "  forgerelay mcp auth <server> [--project <path>|--global]",
+        "  forgerelay mcp logout <server> [--project <path>|--global]",
         "  forgerelay maintenance inspect [--json]",
         "  forgerelay -v, --version   Print the installed version",
         "",

package/dist/lsp/test-support/server-fixture.js

@@ -2,8 +2,7 @@ import assert from "node:assert/strict";
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
 import { ActivityAuditStore } from "../../activity/history/audit-store.js";
 import { BashOutputStore } from "../../activity/history/bash-output-store.js";
 import { HostTurnStore } from "../../activity/history/host-turn-store.js";

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=*";
 }