@akira-tl/forgerelay 0.3.1 → 0.3.2

package/CHANGELOG.md

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

@@ -0,0 +1,118 @@
+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,
+                },
+            };
+        });
+    }
+    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" }),
+        };
+    }
+    async run(name, argumentsValue, context) {
+        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}` : "."}`);
+        }
+        const parsed = definition.inputSchema.safeParse(argumentsValue ?? {});
+        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) => ({
+                ok: true,
+                ...await dependencies.inspectHooks(context.workspaceRoot),
+            }),
+        },
+    ]);
+}

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,10 +15,12 @@ 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 { 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 { logEvent, requestIp, requestPath, commandPreview, transportSessionIdPrefix, workspaceLogLabel, } from "./logger.js";
@@ -124,6 +126,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 +510,18 @@ 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),
+        })),
+    };
+}
 function toolResultIsError(result) {
     return typeof result === "object" && result !== null && result.isError === true;
 }
@@ -649,6 +679,9 @@ 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 capabilityRegistry = createCapabilityRegistry({
+        inspectHooks: (workspaceRoot) => checkHookConfiguration(workspaceRoot, config.hooks),
+    });
     const server = new McpServer({
         name: "forgerelay",
         title: "ForgeRelay",
@@ -740,6 +773,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 +820,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 +882,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 +931,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     worktrees: knownWorktrees,
                     staleWorkspaces,
                     capabilityFingerprint,
+                    capabilityCatalog,
                     agentsFiles: cardAgentsFiles,
                     availableAgentsFiles: cardAvailableAgentsFiles,
                     skills: cardSkills,
@@ -904,6 +943,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 +958,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 worktrees: knownWorktrees,
                 staleWorkspaces,
                 capabilityFingerprint,
+                capabilityCatalog,
                 ...(includeBootstrapContext
                     ? {
                         capabilityGuides: visibleCapabilityGuides,
@@ -933,6 +974,107 @@ 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 arguments. Omit for describe and for capabilities with no arguments."),
+        },
+        outputSchema: {
+            name: z.string(),
+            action: z.enum(["describe", "run"]),
+            capability: z.unknown().optional(),
+            result: z.unknown().optional(),
+            error: capabilityErrorOutputSchema.optional(),
+        },
+        _meta: {},
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async ({ workspaceId, name, action, arguments: capabilityArguments }) => {
+        const workspace = workspaces.getWorkspace(workspaceId);
+        return runToolWithHooks(hooks, {
+            tool: toolNames.capability,
+            invocation: workspaceHookInvocation(workspace),
+            payload: { name, action },
+            isFailure: toolResultIsError,
+            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 capabilityResult = await capabilityRegistry.run(name, capabilityArguments ?? {}, capabilityContextFor(workspace));
+                    const result = {
+                        content: [textBlock(`Capability ${name} completed.\n${JSON.stringify(capabilityResult, null, 2)}`)],
+                        structuredContent: { name, action, result: capabilityResult },
+                    };
+                    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.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "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,