@akira-tl/forgerelay 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.3.3] - 2026-08-10
+
+### Added
+
+- Added `review.changes` and `artifact.download` as registered Capability Gateway actions. Review preserves the existing Git-backed checkpoint and diff-card metadata; native artifact ingress preserves Host-native file transport, workspace-relative no-overwrite publication, size limits, and `AfterFileChange` lifecycle reporting.
+
+### Changed
+
+- The Capability catalog now advertises only capabilities that are actually available in the current runtime. Explicit calls to known-but-disabled capabilities still return stable `capability_unavailable` diagnostics.
+- `show_changes` and `download_artifact` remain compatibility aliases for the 0.3.3 migration window, but the artifacts/review guide now treats the Capability Gateway as the canonical Agent workflow.
+
+## [0.3.2] - 2026-08-10
+
+### Added
+
+- Added a ForgeRelay-owned Capability Registry and the single `capability` MCP gateway with `describe` / `run`, stable dotted names, runtime availability, validated input contracts, guide metadata, and stable diagnostic error codes.
+- `open_workspace` now returns a lightweight Capability catalog on every open. The first tracer capability, `hooks.check`, validates active global/project Hook configuration without requiring Agents to route through shell or the CLI.
+
+### Changed
+
+- Server instructions now direct Agents to use the Capability catalog for low-frequency actions, describing and reading only an unfamiliar capability's advertised guide before first use instead of preloading all low-frequency instructions.
+
 ## [0.3.1] - 2026-08-10
 
 ### Changed

package/capabilities/artifacts-review/GUIDE.md

@@ -4,15 +4,17 @@
 
 ## Native artifact transfer
 
-Native artifact download 默认关闭。只有 `tools/list` 实际暴露 `download_artifact` 时才调用它；当前安全发布实现主要面向 Linux。
+Native artifact download 默认关闭，且当前安全发布实现主要面向 Linux。只有 `open_workspace` 的 Capability catalog 广告 `artifact.download` 时才执行它；不熟悉 contract 时先 `capability(action="describe")`，其中会明确 native file 通过 Gateway 顶层 `file` transport slot 传入。
 
 典型流程：
 
 1. 先用 `open_workspace` 打开目标项目；
-2. 调用 `download_artifact`，传入 Host 原样提供的 native `file` 值、现有 `workspaceId` 和 workspace-relative `path`；
+2. 调用 `capability`，`name="artifact.download"`、`action="run"`，把 Host 原样提供的 native `file` 值放在 Gateway 顶层 `file`，并在 `arguments.path` 传 workspace-relative 目标路径；
 3. 成功后使用返回的 normalized relative path 配合普通 `read` / `rename` / `delete` / shell 等工具继续处理。
 
-`download_artifact` 会创建缺失的父目录，但拒绝覆盖已有目标。不要把 native file 值改造成：
+0.3.3 仍保留 `download_artifact` 作为迁移期 compatibility alias，但新的 Agent workflow 不应把它视为长期 public surface。
+
+`artifact.download` 会创建缺失的父目录，但拒绝覆盖已有目标。不要把 native file 值改造成：
 
 - 任意 URL 字符串；
 - 猜测的本地主机路径；
@@ -28,15 +30,15 @@ Native artifact download 默认关闭。只有 `tools/list` 实际暴露 `downlo
 `FORGERELAY_WIDGETS`：
 
 - `full`：默认，为常用 workspace/file/edit/shell tools 附加 MCP App UI；
-- `changes`：聚焦 `open_workspace` + `show_changes` 聚合 review；
+- `changes`：聚焦 `open_workspace` + `review.changes` 聚合 review；
 - `off`：不附加 widget UI。
 
 Plain MCP Host 可以忽略这些 UI metadata；不要把 UI 是否显示当成文件操作是否成功的判据。
 
-当 `tools/list` 暴露 `show_changes` 时，它自己的 tool description 是调用契约：本轮成功修改文件后，在最后一个相关 file mutation 之后、final response 之前调用一次，让用户看到聚合 diff；不要每改一个文件就调用一次。
+当 Capability catalog 广告 `review.changes` 时，本轮成功修改文件后，在最后一个相关 file mutation 之后、final response 之前通过 `capability` 调用一次，让用户看到聚合 diff；不要每改一个文件就调用一次。0.3.3 仍保留 `show_changes` compatibility alias，但它和 `review.changes` 共用同一套 checkpoint，不是两套 review 状态。
 
-`show_changes` 使用 Git-backed review checkpoint。它按 workspace 跟踪 open/baseline 状态，展示自上次 review checkpoint 以来的 coherent diff，并在成功 review 后推进 baseline。当前版本要求可用的 Git workspace；checkpoint 缺失或 root 不匹配时会明确失败或使用受控 fallback，而不是凭空重建历史。
+`review.changes` 使用 Git-backed review checkpoint。它按 workspace 跟踪 open/baseline 状态，展示自上次 review checkpoint 以来的 coherent diff，并在成功 review 后推进 baseline。当前版本要求可用的 Git workspace；checkpoint 缺失或 root 不匹配时会明确失败或使用受控 fallback，而不是凭空重建历史。
 
 ## Capability ownership
 
-Artifact transfer 和 change review 都属于 ForgeRelay capability，而不是 Agent 自己的文件搬运协议。真实可调用工具仍以 `tools/list` 为准；本指南只提供低频流程和边界，不代表隐藏工具。
+Artifact transfer 和 change review 都属于 ForgeRelay registered capability，而不是 Agent 自己的文件搬运协议。`tools/list` 只负责暴露稳定 Gateway 与当前兼容 aliases；真正可用的低频能力以当前 workspace 的 Capability catalog 为准。本指南提供流程和边界，不额外创造隐藏执行入口。

package/capabilities/lifecycle-hooks/GUIDE.md

@@ -36,4 +36,6 @@ Hook report 会随工具结果返回给 Host/Agent。`report: false` 只隐藏
 
 ## 检查入口
 
-使用 `forgerelay hooks list` 查看已发现规则，使用 `forgerelay hooks check` 做只读校验。排查 Hook 时优先确认配置来源、event/matcher 是否命中、handler 的实际退出状态，以及 tool result 中的 Hook report。
+Agent 打开工作区后会在 Capability catalog 中看到 `hooks.check`。已经熟悉 contract 时可直接通过 `capability` 执行；不熟悉时先 `capability(action="describe")` 查看参数与本指南路径，再按需读取本指南。`hooks.check` 是只读检查，只接受空参数对象，并返回当前生效的全局/项目 Hook 数量；无效项目 Hook 会作为稳定的 capability execution error 返回。
+
+CLI 仍保留给人工终端或兼容工作流：使用 `forgerelay hooks list` 查看已发现规则，使用 `forgerelay hooks check` 做只读校验。排查 Hook 时优先确认配置来源、event/matcher 是否命中、handler 的实际退出状态，以及 tool result 中的 Hook report。

package/dist/artifact-tools.js

@@ -32,8 +32,9 @@ const openAIFileReferenceInputSchema = z.strictObject({
 export function isArtifactDownloadSupportedPlatform(platform = process.platform) {
     return ARTIFACT_DOWNLOAD_PLATFORMS.has(platform);
 }
-export function registerArtifactTools(server, { config, workspaces, hooks, incomingArtifactAdapters = [], }) {
-    const incomingRegistry = new IncomingArtifactAdapterRegistry(incomingArtifactAdapters);
+export function registerArtifactTools(server, { config, workspaces, hooks, incomingArtifactAdapters = [], incomingArtifactRegistry, }) {
+    const incomingRegistry = incomingArtifactRegistry
+        ?? new IncomingArtifactAdapterRegistry(incomingArtifactAdapters);
     registerAppTool(server, "download_artifact", {
         title: "Download attached or generated file",
         description: "Stream one MCP-host-provided native file to a requested relative path inside an already-open workspace. Existing destinations, arbitrary URLs, absolute paths, traversal, symlinked parents, local source paths, and malformed file objects are rejected.",

package/dist/capability-registry.js

@@ -0,0 +1,176 @@
+import { z } from "zod";
+export class CapabilityError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "CapabilityError";
+    }
+}
+export class CapabilityRegistry {
+    definitions;
+    constructor(definitions) {
+        this.definitions = new Map(definitions.map((definition) => [definition.name, definition]));
+    }
+    catalog(context) {
+        return [...this.definitions.values()].map((definition) => {
+            const guide = context.guides.find((candidate) => candidate.name === definition.guideName);
+            const availability = definition.availability(context);
+            const available = Boolean(guide) && availability.available;
+            const unavailableReason = !guide
+                ? `Capability guide ${definition.guideName} is unavailable.`
+                : availability.reason;
+            return {
+                name: definition.name,
+                description: definition.description,
+                available,
+                ...(!available && unavailableReason ? { unavailableReason } : {}),
+                guide: {
+                    name: definition.guideName,
+                    path: guide?.path ?? "",
+                    readBeforeFirstUse: definition.readGuideBeforeFirstUse,
+                },
+            };
+        }).filter((entry) => entry.available);
+    }
+    describe(name, context) {
+        const definition = this.requireDefinition(name);
+        const catalogEntry = this.catalogEntry(definition, context);
+        const guide = context.guides.find((candidate) => candidate.name === definition.guideName);
+        if (!guide) {
+            throw new CapabilityError("capability_unavailable", `Capability ${name} is unavailable: capability guide ${definition.guideName} is unavailable.`);
+        }
+        return {
+            ...catalogEntry,
+            guide: {
+                ...catalogEntry.guide,
+                description: guide.description,
+                whenToRead: guide.whenToRead,
+            },
+            inputSchema: z.toJSONSchema(definition.inputSchema, { target: "draft-7" }),
+            ...(definition.nativeFileArgument
+                ? {
+                    transport: {
+                        nativeFileArgument: definition.nativeFileArgument,
+                        gatewayParameter: "file",
+                    },
+                }
+                : {}),
+        };
+    }
+    async run(name, argumentsValue, context, options = {}) {
+        const definition = this.requireDefinition(name);
+        const catalogEntry = this.catalogEntry(definition, context);
+        if (!catalogEntry.available) {
+            throw new CapabilityError("capability_unavailable", `Capability ${name} is unavailable${catalogEntry.unavailableReason ? `: ${catalogEntry.unavailableReason}` : "."}`);
+        }
+        if (options.nativeFile !== undefined && !definition.nativeFileArgument) {
+            throw new CapabilityError("invalid_arguments", `Capability ${name} does not accept a Host-native file value.`);
+        }
+        const input = definition.nativeFileArgument && options.nativeFile !== undefined
+            ? { ...(isRecord(argumentsValue) ? argumentsValue : {}), [definition.nativeFileArgument]: options.nativeFile }
+            : argumentsValue ?? {};
+        const parsed = definition.inputSchema.safeParse(input);
+        if (!parsed.success) {
+            const details = parsed.error.issues
+                .map((issue) => `${issue.path.length > 0 ? issue.path.join(".") : "arguments"}: ${issue.message}`)
+                .join("; ");
+            throw new CapabilityError("invalid_arguments", `Invalid arguments for capability ${name}: ${details}`);
+        }
+        try {
+            return await definition.run(parsed.data, context);
+        }
+        catch (error) {
+            if (error instanceof CapabilityError)
+                throw error;
+            throw new CapabilityError("execution_failed", `Capability ${name} failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    requireDefinition(name) {
+        const definition = this.definitions.get(name);
+        if (!definition) {
+            throw new CapabilityError("unknown_capability", `Unknown capability: ${name}`);
+        }
+        return definition;
+    }
+    catalogEntry(definition, context) {
+        const guide = context.guides.find((candidate) => candidate.name === definition.guideName);
+        const availability = definition.availability(context);
+        const available = Boolean(guide) && availability.available;
+        const unavailableReason = !guide
+            ? `Capability guide ${definition.guideName} is unavailable.`
+            : availability.reason;
+        return {
+            name: definition.name,
+            description: definition.description,
+            available,
+            ...(!available && unavailableReason ? { unavailableReason } : {}),
+            guide: {
+                name: definition.guideName,
+                path: guide?.path ?? "",
+                readBeforeFirstUse: definition.readGuideBeforeFirstUse,
+            },
+        };
+    }
+}
+export function createCapabilityRegistry(dependencies) {
+    const hooksCheckInput = z.object({}).strict();
+    return new CapabilityRegistry([
+        {
+            name: "hooks.check",
+            description: "Validate the active ForgeRelay Hook configuration for this workspace.",
+            guideName: "lifecycle-hooks",
+            readGuideBeforeFirstUse: true,
+            inputSchema: hooksCheckInput,
+            availability: () => ({ available: true }),
+            run: async (_input, context) => ({
+                value: {
+                    ok: true,
+                    ...await dependencies.inspectHooks(context.workspaceRoot),
+                },
+            }),
+        },
+        ...(dependencies.reviewChanges
+            ? [{
+                    name: "review.changes",
+                    description: "Review accumulated workspace changes from the Git-backed review checkpoint.",
+                    guideName: "artifacts-review",
+                    readGuideBeforeFirstUse: true,
+                    inputSchema: z.object({}).strict(),
+                    availability: () => ({
+                        available: dependencies.reviewChanges?.available ?? false,
+                        reason: dependencies.reviewChanges?.unavailableReason,
+                    }),
+                    run: async (_input, context) => dependencies.reviewChanges.run(context),
+                }]
+            : []),
+        ...(dependencies.downloadArtifact
+            ? [{
+                    name: "artifact.download",
+                    description: "Save one Host-native file into a workspace-relative destination without overwriting.",
+                    guideName: "artifacts-review",
+                    readGuideBeforeFirstUse: true,
+                    inputSchema: z.object({
+                        file: z.strictObject({
+                            download_url: z.string(),
+                            file_id: z.string(),
+                            mime_type: z.string().nullable().optional(),
+                            file_name: z.string().nullable().optional(),
+                            name: z.string().nullable().optional(),
+                            size: z.number().int().nonnegative().nullable().optional(),
+                        }),
+                        path: z.string().min(1),
+                    }).strict(),
+                    nativeFileArgument: "file",
+                    availability: () => ({
+                        available: dependencies.downloadArtifact?.available ?? false,
+                        reason: dependencies.downloadArtifact?.unavailableReason,
+                    }),
+                    run: async (input, context) => dependencies.downloadArtifact.run(input, context),
+                }]
+            : []),
+    ]);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/hook-cli.js

@@ -1,6 +1,18 @@
 import { resolve } from "node:path";
 import { HOOK_EVENTS, loadProjectHookConfig, mergeHookConfigs, parseHookConfig, } from "./hooks.js";
 import { loadForgeRelayFiles } from "./user-config.js";
+export async function checkHookConfiguration(projectRoot, globalHooks = loadGlobalHooks()) {
+    const globalEntries = flattenHooks(globalHooks, "global");
+    const project = await loadProjectHookConfig(projectRoot);
+    if (project.diagnostic) {
+        throw new Error(`Hook check failed: ${project.diagnostic}`);
+    }
+    const projectEntries = flattenHooks(project.hooks, "project");
+    return {
+        globalHooks: globalEntries.length,
+        projectHooks: projectEntries.length,
+    };
+}
 export async function runHooksCommand(args) {
     const [subcommand, ...rest] = args;
     if (!subcommand || ["help", "--help", "-h"].includes(subcommand)) {

package/dist/mcp/server-instructions.js

@@ -12,6 +12,7 @@ export const toolNames = {
     ls: "ls",
     shell: "bash",
     writeStdin: "write_stdin",
+    capability: "capability",
 };
 export function buildShellMutationPolicy() {
     return "Shell commands may modify ordinary project files when that is a natural part of the user's requested development task. They may also perform external device or hardware mutations when the user's current request explicitly asks for the actual device-changing operation, including firmware flashing or equivalent persistent device updates; do not infer such authorization from a check, audit, probe, backup, verification, dry-run, or build-only request. Never use shell commands to modify security- or privilege-sensitive operating-system files or credential material such as /etc/sudoers, /etc/passwd, /etc/shadow, PAM or authentication policy, SSH private keys, or equivalent privileged system files. Modify configuration files through shell only when the user's request explicitly calls for that configuration change; do not infer permission merely because changing configuration would be convenient.";
@@ -43,7 +44,7 @@ function capabilityContractInstructions(config) {
         : ` If ${toolNames.openWorkspace} reports logical workspaces idle for more than two days, let the user choose whether to resume or close them with ${toolNames.closeWorkspace}; never close them automatically.`;
     const workspaceLifecycle = `Use ForgeRelay as a local coding workspace. Default to the user's existing checkout. Reuse the workspaceId returned by ${toolNames.openWorkspace} for this conversation; resume another logical workspaceId only when the user wants that workspace, and request a new logical workspace only when explicitly asked.${staleWorkspacePolicy} Only open mode=\"worktree\" when the user explicitly asks for isolated or parallel Git work. ${toolNames.closeWorkspace} releases a logical workspace; ${toolNames.closeWorktree} finalizes a managed worktree. Read the managed-worktrees capability guide for advanced worktree lifecycle and failure semantics.`;
     const agents = `Follow instructions returned by ${toolNames.openWorkspace}. Read an availableAgentsFiles path before working under it.`;
-    const capabilityGuides = `When ${toolNames.openWorkspace} returns capability guides, use ${toolNames.read} to load only a task-relevant guide; do not preload all guides.`;
+    const capabilityGuides = `For optional capabilities from ${toolNames.openWorkspace}, use ${toolNames.capability}; if unfamiliar, describe first and read its advertised capability guide with ${toolNames.read}.`;
     const skills = config.skillsEnabled
         ? `When a task matches an available skill from ${toolNames.openWorkspace}, read its advertised path before proceeding. Outside normal file roots, ${toolNames.read} permits only advertised entry files and files under already-loaded advertised directories.`
         : "";

package/dist/server.js

@@ -15,12 +15,15 @@ import express from "express";
 import * as z from "zod/v4";
 import { applyPatch } from "./apply-patch.js";
 import { buildCapabilityFingerprint } from "./capabilities.js";
+import { CapabilityError, createCapabilityRegistry, } from "./capability-registry.js";
 import { deletePath, renamePath } from "./file-mutations.js";
-import { isArtifactDownloadSupportedPlatform, registerArtifactTools, } from "./artifact-tools.js";
+import { downloadIncomingArtifact, isArtifactDownloadSupportedPlatform, registerArtifactTools, } from "./artifact-tools.js";
+import { ArtifactError } from "./artifact-error.js";
 import { loadConfig } from "./config.js";
 import { attachHookReports, HookRunner, runToolWithHooks } from "./hooks.js";
+import { checkHookConfiguration } from "./hook-cli.js";
 import { buildServerInstructions, buildShellMutationPolicy, buildToolDescriptions, toolNames, } from "./mcp/server-instructions.js";
-import { createOpenAIIncomingArtifactAdapter, } from "./incoming-artifacts.js";
+import { createOpenAIIncomingArtifactAdapter, IncomingArtifactAdapterRegistry, } from "./incoming-artifacts.js";
 import { logEvent, requestIp, requestPath, commandPreview, transportSessionIdPrefix, workspaceLogLabel, } from "./logger.js";
 import { editFileTool, findFilesTool, grepFilesTool, listDirectoryTool, readFileTool, writeFileTool, } from "./pi-tools.js";
 import { SingleUserOAuthProvider } from "./oauth-provider.js";
@@ -64,7 +67,7 @@ function shouldAttachWidget(mode, kind) {
         case "off":
             return false;
         case "changes":
-            return kind === "workspace" || kind === "show_changes";
+            return kind === "workspace" || kind === "show_changes" || kind === "capability";
         case "full":
             return true;
     }
@@ -124,6 +127,22 @@ const capabilityGuideOutputSchema = z.object({
     whenToRead: z.string(),
     path: z.string(),
 });
+const capabilityCatalogGuideOutputSchema = z.object({
+    name: z.string(),
+    path: z.string(),
+    readBeforeFirstUse: z.boolean(),
+});
+const capabilityCatalogOutputSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    available: z.boolean(),
+    unavailableReason: z.string().optional(),
+    guide: capabilityCatalogGuideOutputSchema,
+});
+const capabilityErrorOutputSchema = z.object({
+    code: z.string(),
+    message: z.string(),
+});
 const workspaceAgentsFileOutputSchema = z.object({
     path: z.string(),
     content: z.string(),
@@ -492,6 +511,25 @@ function workspaceHookInvocation(workspace) {
         sourceRoot: workspace.sourceRoot,
     };
 }
+function capabilityContextFor(workspace) {
+    return {
+        workspaceId: workspace.id,
+        workspaceRoot: workspace.root,
+        guides: workspace.capabilityGuides.map((guide) => ({
+            name: guide.name,
+            description: guide.description,
+            whenToRead: guide.whenToRead,
+            path: formatPathForPrompt(guide.filePath),
+        })),
+    };
+}
+async function reviewWorkspaceChanges(reviewCheckpoints, workspace) {
+    return reviewCheckpoints.reviewChanges({
+        workspaceId: workspace.id,
+        root: workspace.root,
+        markReviewed: true,
+    });
+}
 function toolResultIsError(result) {
     return typeof result === "object" && result !== null && result.isError === true;
 }
@@ -649,6 +687,67 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
 export function createMcpServer(config, workspaces, reviewCheckpoints, processSessions, localAgentProviders, incomingArtifactAdapters) {
     const toolDescriptions = buildToolDescriptions(config);
     const hooks = new HookRunner(config.hooks, config.logging, process.env, (workspaceId, result) => attachCompletedProcessNotices(processSessions, workspaceId, result));
+    const incomingArtifactRegistry = new IncomingArtifactAdapterRegistry(incomingArtifactAdapters);
+    const artifactDownloadAvailable = config.artifactsEnabled && isArtifactDownloadSupportedPlatform();
+    const reviewChangesAvailable = config.widgets === "changes";
+    const capabilityRegistry = createCapabilityRegistry({
+        inspectHooks: (workspaceRoot) => checkHookConfiguration(workspaceRoot, config.hooks),
+        reviewChanges: {
+            available: reviewChangesAvailable,
+            unavailableReason: reviewChangesAvailable
+                ? undefined
+                : "Aggregate change review is disabled; start ForgeRelay with widgets=changes.",
+            run: async (context) => {
+                const review = await reviewWorkspaceChanges(reviewCheckpoints, {
+                    id: context.workspaceId,
+                    root: context.workspaceRoot,
+                });
+                return {
+                    value: {
+                        result: review.result,
+                        summary: review.summary,
+                        files: review.files,
+                    },
+                    card: {
+                        tool: "show_changes",
+                        summary: review.summary,
+                        files: review.files,
+                        payload: { patch: review.patch },
+                    },
+                };
+            },
+        },
+        downloadArtifact: {
+            available: artifactDownloadAvailable,
+            unavailableReason: !config.artifactsEnabled
+                ? "Native artifact ingress is disabled."
+                : !isArtifactDownloadSupportedPlatform()
+                    ? "Native artifact ingress is unsupported on this platform."
+                    : undefined,
+            run: async (input, context) => {
+                try {
+                    const downloaded = await downloadIncomingArtifact({
+                        registry: incomingArtifactRegistry,
+                        workspaceId: context.workspaceId,
+                        workspaceRoot: context.workspaceRoot,
+                        maxFileBytes: config.artifactMaxFileBytes,
+                        file: input.file,
+                        path: input.path,
+                    });
+                    return {
+                        value: { path: downloaded.path },
+                        changedPaths: [downloaded.path],
+                    };
+                }
+                catch (error) {
+                    if (error instanceof ArtifactError) {
+                        throw new CapabilityError(`artifact.${error.code}`, error.message);
+                    }
+                    throw error;
+                }
+            },
+        },
+    });
     const server = new McpServer({
         name: "forgerelay",
         title: "ForgeRelay",
@@ -740,6 +839,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 managed: z.boolean(),
             })),
             capabilityFingerprint: capabilityFingerprintOutputSchema,
+            capabilityCatalog: z.array(capabilityCatalogOutputSchema),
             capabilityGuides: z.array(capabilityGuideOutputSchema).optional(),
             agentsFiles: z.array(workspaceAgentsFileOutputSchema).optional(),
             availableAgentsFiles: z.array(workspaceAvailableAgentsFileOutputSchema).optional(),
@@ -786,6 +886,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             whenToRead: guide.whenToRead,
             path: formatPathForPrompt(guide.filePath),
         }));
+        const capabilityCatalog = capabilityRegistry.catalog(capabilityContextFor(workspace));
         const cardAgentProviders = config.subagents ? localAgentProviders : [];
         const cardAgents = workspace.agentProfiles.map((profile) => {
             const summary = summarizeLocalAgentProfile(profile);
@@ -847,6 +948,9 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     visibleSkills.length > 0
                         ? `Available skills: ${visibleSkills.map((skill) => skill.name).join(", ")}`
                         : undefined,
+                    capabilityCatalog.length > 0
+                        ? `Optional capabilities: ${capabilityCatalog.map((entry) => entry.name).join(", ")}`
+                        : undefined,
                     visibleCapabilityGuides.length > 0
                         ? `Capability guides: ${visibleCapabilityGuides.map((guide) => guide.name).join(", ")}`
                         : undefined,
@@ -893,6 +997,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     worktrees: knownWorktrees,
                     staleWorkspaces,
                     capabilityFingerprint,
+                    capabilityCatalog,
                     agentsFiles: cardAgentsFiles,
                     availableAgentsFiles: cardAvailableAgentsFiles,
                     skills: cardSkills,
@@ -904,6 +1009,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                         agentsFiles: cardAgentsFiles.length,
                         availableAgentsFiles: cardAvailableAgentsFiles.length,
                         skills: cardSkills.length,
+                        capabilities: capabilityCatalog.length,
                         agentProviders: cardAgentProviders.length,
                         agents: cardAgents.length,
                     },
@@ -918,6 +1024,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 worktrees: knownWorktrees,
                 staleWorkspaces,
                 capabilityFingerprint,
+                capabilityCatalog,
                 ...(includeBootstrapContext
                     ? {
                         capabilityGuides: visibleCapabilityGuides,
@@ -933,6 +1040,130 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             },
         }, hookReports));
     });
+    registerAppTool(server, toolNames.capability, {
+        title: "Use optional capability",
+        description: "Describe or run one optional ForgeRelay capability advertised by open_workspace. Use describe when the capability contract is unfamiliar, then read its advertised guide if needed. Run dispatches only explicitly registered capabilities; it cannot invoke arbitrary shell commands, URLs, or methods.",
+        inputSchema: {
+            workspaceId: z.string().describe("Workspace identifier returned by open_workspace."),
+            name: z
+                .string()
+                .regex(/^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+$/)
+                .describe("Stable dotted capability name advertised by open_workspace."),
+            action: z.enum(["describe", "run"]),
+            arguments: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Capability-specific JSON arguments. Omit for describe and for capabilities with no arguments."),
+            file: z
+                .unknown()
+                .optional()
+                .describe("Host-native file value. Only capabilities whose describe result advertises native-file transport may consume it."),
+        },
+        outputSchema: {
+            name: z.string(),
+            action: z.enum(["describe", "run"]),
+            capability: z.unknown().optional(),
+            result: z.unknown().optional(),
+            error: capabilityErrorOutputSchema.optional(),
+        },
+        _meta: {
+            ...toolWidgetDescriptorMeta(config, "capability")._meta,
+            "openai/fileParams": ["file"],
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ workspaceId, name, action, arguments: capabilityArguments, file }) => {
+        const workspace = workspaces.getWorkspace(workspaceId);
+        let changedPaths = [];
+        return runToolWithHooks(hooks, {
+            tool: toolNames.capability,
+            invocation: workspaceHookInvocation(workspace),
+            payload: { name, action },
+            isFailure: toolResultIsError,
+            changedPaths: () => changedPaths,
+            operation: async () => {
+                const startedAt = performance.now();
+                try {
+                    if (action === "describe") {
+                        const capability = capabilityRegistry.describe(name, capabilityContextFor(workspace));
+                        const result = {
+                            content: [textBlock([
+                                    `${capability.name}: ${capability.description}`,
+                                    `Available: ${capability.available}`,
+                                    `Guide: ${capability.guide.path}`,
+                                    capability.guide.readBeforeFirstUse
+                                        ? "Read the guide before first use when this contract is unfamiliar."
+                                        : undefined,
+                                ].filter(Boolean).join("\n"))],
+                            structuredContent: { name, action, capability },
+                        };
+                        logToolCall(config, {
+                            tool: toolNames.capability,
+                            ...workspaceLogContext(workspace),
+                            capability: name,
+                            action,
+                            success: true,
+                            durationMs: Math.round(performance.now() - startedAt),
+                        });
+                        return result;
+                    }
+                    const execution = await capabilityRegistry.run(name, capabilityArguments ?? {}, capabilityContextFor(workspace), { nativeFile: file });
+                    changedPaths = execution.changedPaths ?? [];
+                    const result = {
+                        content: [textBlock(`Capability ${name} completed.\n${JSON.stringify(execution.value, null, 2)}`)],
+                        ...(execution.card
+                            ? {
+                                _meta: {
+                                    tool: execution.card.tool ?? toolNames.capability,
+                                    card: {
+                                        workspaceId,
+                                        summary: execution.card.summary ?? {},
+                                        files: execution.card.files,
+                                        payload: execution.card.payload ?? {},
+                                    },
+                                },
+                            }
+                            : {}),
+                        structuredContent: { name, action, result: execution.value },
+                    };
+                    logToolCall(config, {
+                        tool: toolNames.capability,
+                        ...workspaceLogContext(workspace),
+                        capability: name,
+                        action,
+                        success: true,
+                        durationMs: Math.round(performance.now() - startedAt),
+                    });
+                    return result;
+                }
+                catch (error) {
+                    const capabilityError = error instanceof CapabilityError
+                        ? error
+                        : new CapabilityError("execution_failed", error instanceof Error ? error.message : String(error));
+                    const result = {
+                        content: [textBlock(`${capabilityError.code}: ${capabilityError.message}`)],
+                        structuredContent: {
+                            name,
+                            action,
+                            error: { code: capabilityError.code, message: capabilityError.message },
+                        },
+                        isError: true,
+                    };
+                    logFailedToolResponse(config, {
+                        tool: toolNames.capability,
+                        ...workspaceLogContext(workspace),
+                        capability: name,
+                        action,
+                    }, result.content, startedAt);
+                    return result;
+                }
+            },
+        });
+    });
     registerAppTool(server, toolNames.closeWorkspace, {
         title: "Close logical workspace",
         description: "Release one logical workspaceId after the user chooses cleanup. This does not delete checkout files. Use close_worktree to finalize and remove a managed worktree. Running or unconsumed processes prevent closure.",
@@ -1509,11 +1740,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 invocation: workspaceHookInvocation(workspace),
                 operation: async () => {
                     const startedAt = performance.now();
-                    const review = await reviewCheckpoints.reviewChanges({
-                        workspaceId,
-                        root: workspace.root,
-                        markReviewed: true,
-                    });
+                    const review = await reviewWorkspaceChanges(reviewCheckpoints, workspace);
                     const content = [textBlock(review.result)];
                     logToolCall(config, {
                         tool: "show_changes",
@@ -1815,6 +2042,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             workspaces,
             hooks,
             incomingArtifactAdapters,
+            incomingArtifactRegistry,
         });
     }
     return server;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -42,7 +42,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/logger.test.ts && tsx src/proxy-trust.test.ts && tsx src/mcp-app-template.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/file-mutations.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/proxy-trust.test.ts && tsx src/mcp-app-template.test.ts && tsx src/hooks.test.ts && tsx src/capability-registry.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/file-mutations.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

@@ -129,7 +129,7 @@ try {
     params: {},
   }).message.result.tools;
   const toolNames = tools.map((tool) => tool.name);
-  for (const expected of ["open_workspace", "close_workspace", "close_worktree", "read", "write", "edit", "rename", "delete", "grep", "glob", "ls", "bash", "write_stdin"]) {
+  for (const expected of ["open_workspace", "close_workspace", "close_worktree", "read", "write", "edit", "rename", "delete", "grep", "glob", "ls", "bash", "write_stdin", "capability"]) {
     assert.ok(toolNames.includes(expected), `missing debug tool ${expected}`);
   }
   const bashTool = tools.find((tool) => tool.name === "bash");
@@ -156,6 +156,7 @@ try {
   assert.ok(openWorkspaceTool?.inputSchema?.properties?.newWorkspace);
   assert.ok(openWorkspaceTool?.outputSchema?.properties?.staleWorkspaces);
   assert.ok(openWorkspaceTool?.outputSchema?.properties?.capabilityFingerprint);
+  assert.ok(openWorkspaceTool?.outputSchema?.properties?.capabilityCatalog);
   assert.ok(openWorkspaceTool?.outputSchema?.properties?.capabilityGuides);
   const templateUri = bashTool?._meta?.ui?.resourceUri;
   assert.match(
@@ -240,6 +241,34 @@ try {
       "ui.mcp-app",
     ],
   });
+  const capabilityCatalog = opened.structuredContent.capabilityCatalog;
+  assert.deepEqual(capabilityCatalog.map((entry) => entry.name), ["hooks.check"]);
+  assert.equal(capabilityCatalog[0].available, true);
+  assert.equal(capabilityCatalog[0].guide.name, "lifecycle-hooks");
+  const directCapability = callTool(oauth.accessToken, sessionId, 79, "capability", {
+    workspaceId,
+    name: "hooks.check",
+    action: "run",
+    arguments: {},
+  });
+  assert.equal(directCapability.isError, undefined);
+  assert.equal(directCapability.structuredContent.result.ok, true);
+  const describedCapability = callTool(oauth.accessToken, sessionId, 80, "capability", {
+    workspaceId,
+    name: "hooks.check",
+    action: "describe",
+  });
+  assert.equal(describedCapability.isError, undefined);
+  assert.equal(describedCapability.structuredContent.capability.guide.name, "lifecycle-hooks");
+  assert.equal(describedCapability.structuredContent.capability.inputSchema.type, "object");
+  const unknownCapability = callTool(oauth.accessToken, sessionId, 81, "capability", {
+    workspaceId,
+    name: "unknown.capability",
+    action: "run",
+    arguments: {},
+  });
+  assert.equal(unknownCapability.isError, true);
+  assert.equal(unknownCapability.structuredContent.error.code, "unknown_capability");
   const capabilityGuides = opened.structuredContent.capabilityGuides;
   assert.deepEqual(capabilityGuides.map((guide) => guide.name), [
     "lifecycle-hooks",
@@ -253,7 +282,7 @@ try {
   });
   assert.match(hooksGuide.structuredContent.result, /BeforeTool/);
   assert.match(hooksGuide.structuredContent.result, /BeforeWorktreeClose/);
-  pass("open_workspace", `${workspaceId} -> fingerprint + ${capabilityGuides.length} capability guides`);
+  pass("open_workspace", `${workspaceId} -> ${capabilityCatalog.length} capabilities + ${capabilityGuides.length} capability guides`);
 
   const written = callTool(oauth.accessToken, sessionId, 4, "write", {
     workspaceId,