@akira-tl/forgerelay 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -4,6 +4,29 @@ 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
+
+- Release-tag Hooks now treat `commandRegex` as a command extractor as well as a filter: a matching substring becomes Hook `payload.command`, while a different full shell request is preserved as `payload.originalCommand`. This lets stable tag pushes trigger local release gates even when an Agent wraps them in a compound shell command.
+- GitHub Release pages now use the matching `CHANGELOG.md` version section as their release notes instead of relying only on generated compare notes.
+
+### Fixed
+
+- MCP App resources now advertise a unique `_meta.ui.domain` derived from the resolved public deployment origin while preserving existing CSP, content-hashed template identity, and legacy/historical compatibility resources.
+- `forgerelay doctor` now reports the resolved MCP runtime shape, including public base URL, tool/widget modes, proxy trust, and optional artifact/subagent/Skill capability switches.
+
 ## [0.3.0] - 2026-08-10
 
 ### Added

package/capabilities/host-integration/GUIDE.md

@@ -53,7 +53,7 @@ ForgeRelay 正常会广告 content-hashed：
 ui://forgerelay/workspace-app-<hash>.html
 ```
 
-`resources/read` 应返回 `text/html;profile=mcp-app`，并且 HTML 引用的 `/mcp-app-assets/` 资源必须可达。ForgeRelay 还保留 legacy `ui://forgerelay/workspace-app.html` 和历史 `workspace-app-*.html` 兼容指针，以容忍 Host 暂时持有旧 metadata snapshot。
+`resources/list` 与 `resources/read` 的 MCP App metadata 都应包含唯一 `_meta.ui.domain`，其值来自 resolved `publicBaseUrl` 的 origin；CSP 仍使用完整 public base URL 约束资源与连接域。`resources/read` 应返回 `text/html;profile=mcp-app`，并且 HTML 引用的 `/mcp-app-assets/` 资源必须可达。ForgeRelay 还保留 legacy `ui://forgerelay/workspace-app.html` 和历史 `workspace-app-*.html` 兼容指针，以容忍 Host 暂时持有旧 metadata snapshot。
 
 需要 live trace 时，可用：
 

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/cli.js

@@ -222,7 +222,14 @@ async function runDoctor() {
     try {
         const config = loadConfig();
         console.log(`Local MCP URL: http://${config.host}:${config.port}/mcp`);
+        console.log(`Public base URL: ${config.publicBaseUrl}`);
         console.log(`Public MCP URL: ${new URL("/mcp", config.publicBaseUrl).toString()}`);
+        console.log(`Tool mode: ${config.toolMode}`);
+        console.log(`Widgets: ${config.widgets}`);
+        console.log(`Trust proxy: ${config.logging.trustProxy ? "one hop" : "off"}`);
+        console.log(`Artifacts: ${config.artifactsEnabled ? "enabled" : "disabled"}`);
+        console.log(`Subagents: ${config.subagents ? "enabled" : "disabled"}`);
+        console.log(`Skills: ${config.skillsEnabled ? "enabled" : "disabled"}`);
         console.log(`Allowed roots: ${config.allowedRoots.join(", ")}`);
         console.log(`Allowed hosts: ${config.allowedHosts.join(", ")}`);
     }

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/hooks.js

@@ -215,9 +215,12 @@ export class HookRunner {
         const handlers = [
             ...(this.hooks[event] ?? []).map((rule) => ({ scope: "global", rule })),
             ...(project.hooks[event] ?? []).map((rule) => ({ scope: "project", rule })),
-        ]
-            .filter(({ rule }) => hookRuleMatches(rule.matcher, invocation))
-            .flatMap(({ scope, rule }) => rule.handlers.map((handler) => ({ scope, handler })));
+        ].flatMap(({ scope, rule }) => {
+            const matchedInvocation = matchHookRule(rule.matcher, invocation);
+            if (!matchedInvocation)
+                return [];
+            return rule.handlers.map((handler) => ({ scope, handler, invocation: matchedInvocation }));
+        });
         const blocking = BLOCKING_EVENTS.has(event);
         const executions = project.diagnostic
             ? [{
@@ -230,8 +233,8 @@ export class HookRunner {
                     error: project.diagnostic,
                 }]
             : [];
-        for (const [index, { scope, handler }] of handlers.entries()) {
-            const execution = await this.runHandler(event, handler, index, invocation, scope);
+        for (const [index, { scope, handler, invocation: matchedInvocation }] of handlers.entries()) {
+            const execution = await this.runHandler(event, handler, index, matchedInvocation, scope);
             executions.push(execution);
             logEvent(this.logging, execution.status === "passed" ? "info" : "warn", "hook_call", {
                 hookEvent: event,
@@ -447,20 +450,33 @@ export async function loadProjectHookConfig(workspaceRoot) {
         ...(diagnostics.length > 0 ? { diagnostic: diagnostics.join(" | ") } : {}),
     };
 }
-function hookRuleMatches(matcher, invocation) {
+function matchHookRule(matcher, invocation) {
     if (!matcher)
-        return true;
+        return invocation;
     if (matcher.workspaceMode && invocation.workspaceMode !== matcher.workspaceMode)
-        return false;
+        return undefined;
     if (matcher.tool) {
         if (typeof invocation.payload?.tool !== "string" || invocation.payload.tool !== matcher.tool) {
-            return false;
+            return undefined;
         }
     }
+    let matchedInvocation = invocation;
     if (matcher.commandRegex) {
         const command = invocation.payload?.command;
-        if (typeof command !== "string" || !new RegExp(matcher.commandRegex).test(command)) {
-            return false;
+        if (typeof command !== "string")
+            return undefined;
+        const commandMatch = new RegExp(matcher.commandRegex).exec(command);
+        if (!commandMatch)
+            return undefined;
+        if (commandMatch[0] !== command) {
+            matchedInvocation = {
+                ...invocation,
+                payload: {
+                    ...invocation.payload,
+                    command: commandMatch[0],
+                    originalCommand: command,
+                },
+            };
         }
     }
     if (matcher.pathRegex) {
@@ -471,15 +487,15 @@ function hookRuleMatches(matcher, invocation) {
         const matchesPath = typeof path === "string" && pathPattern.test(path);
         const matchesPaths = Array.isArray(paths) && paths.some((entry) => typeof entry === "string" && new RegExp(pathRegex).test(entry));
         if (!matchesPath && !matchesPaths)
-            return false;
+            return undefined;
     }
     if (matcher.provider) {
         if (typeof invocation.payload?.provider !== "string" ||
             invocation.payload.provider !== matcher.provider) {
-            return false;
+            return undefined;
         }
     }
-    return true;
+    return matchedInvocation;
 }
 function hookEnvironment(baseEnv, event, invocation) {
     return {

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(),
@@ -317,6 +335,9 @@ ${stylesheets}
   </body>
 </html>`;
 }
+function appDomain(config) {
+    return new URL(config.publicBaseUrl).origin;
+}
 function appCsp(config) {
     const publicBaseUrl = config.publicBaseUrl.replace(/\/+$/, "");
     return {
@@ -360,6 +381,7 @@ async function readWorkspaceAppResource(config, requestedUri, transportSessionId
                     text: workspaceAppHtml(config),
                     _meta: {
                         ui: {
+                            domain: appDomain(config),
                             csp: appCsp(config),
                         },
                     },
@@ -488,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;
 }
@@ -645,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",
@@ -658,6 +695,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         description: "Interactive card for viewing ForgeRelay file diffs.",
         _meta: {
             ui: {
+                domain: appDomain(config),
                 csp: appCsp(config),
             },
         },
@@ -735,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(),
@@ -781,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);
@@ -842,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,
@@ -888,6 +931,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     worktrees: knownWorktrees,
                     staleWorkspaces,
                     capabilityFingerprint,
+                    capabilityCatalog,
                     agentsFiles: cardAgentsFiles,
                     availableAgentsFiles: cardAvailableAgentsFiles,
                     skills: cardSkills,
@@ -899,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,
                     },
@@ -913,6 +958,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 worktrees: knownWorktrees,
                 staleWorkspaces,
                 capabilityFingerprint,
+                capabilityCatalog,
                 ...(includeBootstrapContext
                     ? {
                         capabilityGuides: visibleCapabilityGuides,
@@ -928,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/docs/configuration.md

@@ -211,7 +211,7 @@ Hooks v1 是自动生命周期规则。规则由用户或 Agent 主动写入；
   "event": "BeforeTool",
   "matcher": {
     "tool": "bash",
-    "commandRegex": "^git\\s+push\\s+origin\\s+v\\d+\\.\\d+\\.\\d+$"
+    "commandRegex": "git\\s+push\\s+origin\\s+v\\d+\\.\\d+\\.\\d+"
   },
   "command": "npm run release:verify",
   "timeoutSeconds": 300,
@@ -255,7 +255,7 @@ forgerelay hooks check --project /path/to/project
 | 字段 | 匹配方式 |
 | --- | --- |
 | `tool` | 精确匹配 MCP tool 名称。 |
-| `commandRegex` | 对 tool payload 中的 `command` 做 JavaScript 正则匹配。 |
+| `commandRegex` | 对 tool payload 中的 `command` 做 JavaScript 正则匹配；命中后 Hook 收到的 `payload.command` 是实际匹配片段，完整原命令在片段不等于整串命令时保留为 `payload.originalCommand`。 |
 | `pathRegex` | 对 payload 中的 `path` 或 `paths` 做正则匹配。 |
 | `provider` | 精确匹配 subagent provider。 |
 | `workspaceMode` | `checkout` 或 `worktree`。 |

package/docs/debugging.md

@@ -60,7 +60,7 @@ The acceptance checks:
 4. dynamic OAuth client registration, PKCE Owner-password approval, and access-token exchange;
 5. MCP `initialize`, including package/server version consistency and the shell mutation safety contract;
 6. `tools/list` for the full debug tool surface, including `close_workspace`, `write_stdin`, canonical `processId` plus the deprecated `sessionId` compatibility alias, the non-blanket `bash` mutation policy, no kill-timeout input, the 300-second foreground-wait contract, workspace resume/stale-workspace schema, and MCP App tool metadata;
-7. the full MCP App template chain: `resources/list`, `resources/templates/list`, current content-hashed `resources/read`, legacy/historical template compatibility reads, `text/html;profile=mcp-app`, CSP resource domains, and an HTTP fetch of the JavaScript asset referenced by the template;
+7. the full MCP App template chain: `resources/list`, `resources/templates/list`, current content-hashed `resources/read`, legacy/historical template compatibility reads, `text/html;profile=mcp-app`, the unique app domain plus CSP resource domains, and an HTTP fetch of the JavaScript asset referenced by the template;
 8. a real checkout workspace with `write`, `read`, `rename`, `delete`, foreground `bash` through `ProcessManager`, and a deliberate failed `edit`;
 9. OS temp-directory `write` → `read` → `edit` → `rename` → `delete` over the same real MCP transport session, plus rejection of an arbitrary path outside the workspace/temp roots;
 10. a temporary Git repository with managed worktree creation, file modification, and `close_worktree`;

package/docs/roadmap.md

@@ -104,29 +104,75 @@ Hooks v1 的目标是给用户和 Agent 一个很小、自动、可组合的生
 
 ## 0.3 — MCP loading 与渐进式能力披露
 
-0.3 的目标是缩小 MCP 首次加载时注入给 Agent 的上下文，同时保持工具可调用性、安全边界和 Host 编排权不变。ForgeRelay 不再把所有低频能力说明都塞进 server instructions 或工具 description，而是把模型接口拆成三层：
+0.3 的目标是把 ForgeRelay 的 MCP interface 做成一个深而稳定的模型接口：普通编码 primitive 始终直接可见，低频知识与低频 action 都按需披露，新增 ForgeRelay 能力不再线性扩大 Host 首次加载的 `tools/list` 与 instructions。
 
-- `tools/list` 继续暴露真实可调用 primitive，并只携带调用该工具所必需的简洁语义；
-- `open_workspace` 返回紧凑的 server/capability 摘要与版本指纹，帮助 Agent 发现能力，并识别 Host 持有旧 tool schema snapshot 的情况；
-- ForgeRelay-owned capability guide 提供低频能力的完整说明，由 Agent 在任务相关时显式 `read`，而不是首次连接时自动注入。
+0.3.0 已完成第一阶段：压缩 server instructions、由 `open_workspace` 返回 version/capability fingerprint、通过 advertised path + `read` 按需加载 ForgeRelay-owned capability guide，并用 fingerprint 与 Host `tools/list` 的差异诊断 stale Host metadata。Capability guide 与 Skill 的语义所有权保持区分：Skill 描述用户、项目或生态工作流；Capability guide 描述 ForgeRelay 自身、与版本绑定的产品能力。
 
-首版优先复用现有 Skill-style 的 advertised path / `read` 授权机制，而不是新增第二套文档加载协议。Capability guide 与 Skill 的语义所有权保持区分：Skill 描述用户、项目或生态工作流；capability guide 描述 ForgeRelay 自身、与版本绑定的产品能力。
+0.3 后续阶段采用 ADR-0002 的接口形状。Canonical Core tool surface 最终固定为：
 
-Core Capability Contract 必须始终内联保留至少这些信息：
+```text
+open_workspace
+close_workspace
+read
+write
+edit
+rename
+delete
+bash
+capability
+```
+
+其中 `open_workspace` 负责 Workspace 生命周期入口与轻量 Capability catalog；`capability` 是唯一低频 Capability gateway；`bash` 同时承担命令启动与后续 process interaction；Managed worktree 是 Workspace 的 backing mode，由 `close_workspace` 统一完成关闭/finalize lifecycle。Capability registry 只能暴露显式注册、带输入约束、可用性和 guide metadata 的 ForgeRelay capability，不能退化成任意 RPC、URL dispatcher 或 shell 后门。
+
+### 0.3.1 — MCP App 与诊断补丁
+
+在不改变主 tool surface 的前提下先修 0.3.0 发布后真实 Host 暴露的问题：
+
+- 为 MCP App resource 补齐 Host submission 所需的 widget/app domain metadata，并保持现有 CSP、content-hash URI 与 compatibility resource contract；
+- `forgerelay doctor` 显示解析后的 MCP 运行形态，例如 tool mode、widgets、public URL、proxy trust 与可选 capability 开关，避免“功能代码存在但当前实例未启用”只能靠源码排查；
+- 补齐 release/Host integration 的诊断与验收用例，但不在这一版重塑 tool schema。
+
+### 0.3.2 — Capability Registry 与 Gateway
+
+建立新的低频 action seam，但保留现有公开工具作为迁移兼容：
+
+- 新建 ForgeRelay-owned Capability registry，每项至少声明稳定 name、简短 description、availability、input contract、guide metadata 与 handler；
+- 新增唯一 MCP tool `capability`，提供紧凑的 `describe` / `run` 语义；
+- `open_workspace` 返回轻量 Capability catalog，只做发现，不复制完整 schema、示例或 guide 正文；
+- Agent 已熟悉某项 capability 时可以直接执行；不熟悉时先 `describe`，再按返回的 guide path 使用 `read` 获取详细说明；
+- 选择一组低风险、当前主要依赖 CLI 的检查型能力作为 tracer bullet，验证 registry、Hooks、日志、错误和 Host card contract，而不是一开始迁移所有功能。
+
+### 0.3.3 — 低频 Action 迁入 Gateway
+
+用真实现有能力验证 Gateway 能承载持续扩展，而不是只做一层转发：
+
+- 将 change review 收口为如 `review.changes` 的 registered capability；
+- 将 native artifact ingress 收口为如 `artifact.download` 的 registered capability；
+- 适合 Agent 主动调用的 Hook inspection/check 等低频操作进入同一 namespace model；
+- Capability guide 与 catalog/registry 建立一一可追踪关系，availability 由运行时条件决定；
+- `show_changes`、`download_artifact` 等旧 dedicated MCP tools 在迁移窗口内只作为兼容入口，不再作为长期接口设计。
 
-- `workspaceId` 生命周期与 workspace 复用规则；
-- 常用文件读写改、`rename` 同时承担 move/rename、删除的核心语义；
-- shell 以本地用户权限执行且不是 OS sandbox；
-- `processId` / `write_stdin` 的基本长进程语义；
-- Hook 阻断结果必须对 Agent 可见；
-- 关键 mutation/safety invariant；
-- `close_workspace` 与 `close_worktree` 的区别。
+### 0.3.4 — Workspace 与 Process 生命周期收敛
 
-适合按需读取的首批领域包括：生命周期 Hooks、managed worktree 高级流程、subagents、artifact/review 工作流、debug/MCP App、OAuth/deployment，以及 shell/PTTY/process 的低频边界情况。首个实现切片迁移 Hooks 与 managed worktree 高级说明；第二切片继续覆盖 subagents、artifact/review、Host/OAuth/MCP App integration 与 shell/PTTY/process，并把历史 bundled `subagent-delegation` Skill 的默认自动发现迁回 ForgeRelay-owned capability guide。必要安全语义始终保留在 core contract 或真实 tool schema/description 中。
+移除两个泄漏内部实现的 public lifecycle tool：
 
-Capability/version fingerprint 必须是轻量、语义化、稳定的摘要，不复制完整 `tools/list`。当 server 报告的能力与 Host 当前暴露的 tool snapshot 明显不一致时，Agent 应能判断为 Host metadata stale，并建议刷新 MCP 或开启新会话，而不是错误断言 ForgeRelay 缺少能力。
+- `bash` 成为 Process Manager 的唯一公开 interface；`action="run"` 启动命令，`action="process"` 使用 `processId` 查看、等待、输入、调整 PTY 或中断已有进程；内部 ProcessManager 可以继续保留更细的方法，但 Host 不再需要学习 `write_stdin`；
+- `close_workspace` 成为唯一 workspace 关闭入口；checkout 直接释放，managed-worktree-backed Workspace 在同一接口内执行 BeforeWorktreeClose、commit/integrate/cleanup、AfterWorktreeClose 并关闭 Workspace；
+- 从 canonical MCP surface 删除 `write_stdin` 与 `close_worktree`，同时清理对应 server instructions、fingerprint 和 capability guide 中的旧心智模型；
+- 保留 `processId` 作为运行中进程的 opaque handle，保留 worktree 作为 Workspace 的可观察 backing metadata，而不是第二套 Host lifecycle。
 
-0.3 不隐藏 callable tool，不增加隐式 autonomous workflow，也不把 Host Refresh/session 行为归到 ForgeRelay。`rename` 继续作为文件和目录 move/rename 的统一 primitive。
+### 0.3.5 — Canonical MCP Surface 收口
+
+完成 0.3 的接口稳定化与真实 Host 验收：
+
+- regular ForgeRelay MCP surface 收口为 9 个 canonical tools；`minimal/full` 不再通过增减 `grep/glob/ls` 改变主产品心智模型，搜索与目录检查可由 `bash` 承担；
+- 评估并隔离 `codex` compatibility surface，使其作为明确 adapter 存在，而不是反向定义 ForgeRelay canonical interface；
+- 删除已经完成迁移的 dedicated low-frequency tool aliases，确保新增 Capability 不再扩大常驻 tool count；
+- 简化 fingerprint，使其用于版本/运行时能力摘要与 stale-Host 诊断，而不是重新枚举 tool implementation；
+- 对 `open_workspace → catalog → capability describe/read/run`、managed worktree close、长进程 interaction、review/artifact capability、MCP App 与 stale-schema 情况做 7677 acceptance 和新 Host 会话验收；
+- 0.3.5 通过后，0.3 的 MCP progressive-disclosure 主题视为完成，0.4 回到原定 LSP code intelligence v1。
+
+必要安全语义始终留在 Core tool interface、Capability contract 或自动 Hook report 中；渐进式披露不能成为隐藏权限、隐式 autonomous workflow 或绕过 allowed roots/auth 的机制。`rename` 继续作为文件和目录 move/rename 的统一 primitive。
 
 ## 0.4 — LSP code intelligence v1
 
@@ -151,20 +197,7 @@ Initial operations:
 - workspace symbols;
 - hover/type information.
 
-Prefer one deep MCP capability such as:
-
-```text
-code_intelligence({
-  workspaceId,
-  operation,
-  path,
-  line,
-  column,
-  query
-})
-```
-
-rather than one MCP tool per language or language-server method.
+Expose code intelligence through the Capability Gateway established in 0.3 rather than adding another top-level MCP tool. A representative registered capability may look like `code.intelligence`, with its language-server operation/path/position/query fields carried inside the capability arguments. The exact LSP contract remains 0.4 work; the stable Core tool surface does not change per language or language-server method.
 
 Candidate servers include `typescript-language-server`/tsserver, Pyright,
 `rust-analyzer`, `gopls`, and `clangd`, but ForgeRelay should treat server
@@ -176,22 +209,7 @@ ForgeRelay already owns provider adapters and resumable local agent sessions.
 The next step is to remove the current `bash -> forgerelay agents ...` indirection
 for MCP hosts.
 
-A compact interface should reuse the existing provider adapter registry:
-
-```text
-subagent({
-  action: "run" | "list" | "show" | "cancel",
-  workspaceId,
-  profile,
-  provider,
-  prompt,
-  agentId
-})
-```
-
-The parent agent chooses an available provider/profile such as Codex or Claude.
-ForgeRelay launches, tracks, resumes, and cancels the provider-backed worker when
-the underlying provider supports those operations.
+First-class subagent operations should reuse the Capability Gateway established in 0.3 rather than add another top-level MCP tool. The exact registered names, action semantics and provider/session contract remain 0.5 design work. The parent agent will continue choosing from available provider/profile metadata while ForgeRelay owns provider-backed worker lifecycle state.
 
 This is intentionally provider-backed delegation, not an attempt to emulate a
 host-native subagent implementation.

package/docs/setup.md

@@ -120,7 +120,9 @@ npx @akira-tl/forgerelay doctor
 ```
 
 The doctor command reports the resolved config, Node runtime, platform, Git,
-Bash, public URL, allowed hosts, and native SQLite dependency status.
+Bash, public URL, allowed hosts, native SQLite dependency status, and the MCP
+shape ForgeRelay will expose: tool mode, widget mode, one-hop proxy trust, and
+whether optional artifact, subagent, and Skill capabilities are enabled.
 
 ## Running from a local checkout
 

package/docs/versioning.md

@@ -168,7 +168,9 @@ npm publishing token.
    git push origin v0.2.0
    ```
 
-The tag push is the publication action.
+The tag push is the publication action. The release workflow publishes npm only after cloud CI passes, then extracts the matching `CHANGELOG.md` release section as the GitHub Release body. Keep `Unreleased` user-facing and structured (`Added`, `Changed`, `Fixed`, `Security`) because those notes are what users see on the Release page.
+
+Project release Hooks match the stable tag-push command as a substring of the ForgeRelay shell request. A compound command is allowed: when `commandRegex` matches `git push origin vX.Y.Z`, the Hook receives that matched command as `FORGERELAY_HOOK_PAYLOAD.command` and retains the complete shell request as `originalCommand` when they differ.
 
 ## Attribution guardrails
 

package/package.json

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

@@ -45,6 +45,18 @@ const { env } = createDebugEnvironment({
   hookLog,
   widgets: "full",
 });
+const doctor = spawnSync(process.execPath, ["--import", "tsx", "src/cli.ts", "doctor"], {
+  cwd: repoRoot,
+  env,
+  encoding: "utf8",
+});
+assert.equal(doctor.status, 0, doctor.stderr);
+assert.match(doctor.stdout, /Public base URL: http:\/\/127\.0\.0\.1:7677/);
+assert.match(doctor.stdout, /Tool mode: full/);
+assert.match(doctor.stdout, /Widgets: full/);
+assert.match(doctor.stdout, /Trust proxy: off/);
+pass("doctor resolved MCP shape", "public URL + tool/widgets/proxy state");
+
 const server = spawn(process.execPath, ["--import", "tsx", "src/cli.ts", "serve"], {
   cwd: repoRoot,
   env,
@@ -117,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");
@@ -144,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(
@@ -161,7 +174,9 @@ try {
     method: "resources/list",
     params: {},
   }).message.result.resources;
-  assert.ok(resources.some((resource) => resource.uri === templateUri));
+  const currentResource = resources.find((resource) => resource.uri === templateUri);
+  assert.ok(currentResource);
+  assert.equal(currentResource._meta?.ui?.domain, debugBaseUrl);
   assert.ok(resources.some((resource) => resource.uri === "ui://forgerelay/workspace-app.html"));
 
   const resourceTemplates = mcpRequest(oauth.accessToken, sessionId, {
@@ -185,6 +200,7 @@ try {
   assert.equal(template.uri, templateUri);
   assert.equal(template.mimeType, "text/html;profile=mcp-app");
   assert.match(template.text ?? "", /<script type="module" crossorigin src="[^"]+\/mcp-app-assets\//);
+  assert.equal(template._meta?.ui?.domain, debugBaseUrl);
   assert.ok(template._meta?.ui?.csp?.resourceDomains?.includes(debugBaseUrl));
   const scriptUrl = template.text?.match(/<script type="module" crossorigin src="([^"]+)"/)?.[1];
   assert.ok(scriptUrl);
@@ -225,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",
@@ -238,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,
@@ -655,8 +699,9 @@ function exerciseReleaseTagHooks(accessToken, sessionId) {
     [
       'import { writeFileSync } from "node:fs";',
       'const payload = process.env.FORGERELAY_HOOK_PAYLOAD ?? "{}";',
+      'const parsed = JSON.parse(payload);',
       'writeFileSync("release-ci-ran.txt", payload);',
-      'if (JSON.parse(payload).command === "git push origin v0.2.1") process.exit(17);',
+      'if (parsed.command === "git push origin v0.2.1") process.exit(17);',
       "",
     ].join("\n"),
   );
@@ -664,7 +709,7 @@ function exerciseReleaseTagHooks(accessToken, sessionId) {
     join(releaseProject, ".forgerelay", "hooks", "release-tag-local-ci.json"),
     JSON.stringify({
       event: "BeforeTool",
-      matcher: { tool: "bash", commandRegex: "^git push origin v0\\.2\\.[01]$" },
+      matcher: { tool: "bash", commandRegex: "git push origin v0\\.2\\.[01]" },
       command: "node .forgerelay/release-check.mjs",
       timeoutSeconds: 30,
       report: true,
@@ -682,11 +727,17 @@ function exerciseReleaseTagHooks(accessToken, sessionId) {
 
   const pushed = callTool(accessToken, sessionId, 12, "bash", {
     workspaceId: releaseWorkspaceId,
-    command: "git push origin v0.2.0",
+    command: "git status --short && git push origin v0.2.0 && echo release-pushed",
   });
   assert.equal(pushed.isError, undefined);
   assert.match(toolText(pushed), /release-tag-local-ci \(BeforeTool, project\) passed/);
   assert.ok(existsSync(join(releaseProject, "release-ci-ran.txt")));
+  assert.deepEqual(JSON.parse(readFileSync(join(releaseProject, "release-ci-ran.txt"), "utf8")), {
+    tool: "bash",
+    command: "git push origin v0.2.0",
+    workingDirectory: ".",
+    originalCommand: "git status --short && git push origin v0.2.0 && echo release-pushed",
+  });
   assert.equal(
     gitOutput(releaseRemote, ["rev-parse", "refs/tags/v0.2.0"], { gitDir: true }),
     gitOutput(releaseProject, ["rev-parse", "v0.2.0"]),
@@ -694,7 +745,7 @@ function exerciseReleaseTagHooks(accessToken, sessionId) {
 
   const blocked = callTool(accessToken, sessionId, 13, "bash", {
     workspaceId: releaseWorkspaceId,
-    command: "git push origin v0.2.1",
+    command: "git status --short && git push origin v0.2.1 && echo should-not-run",
   });
   assert.equal(blocked.isError, true);
   assert.match(toolText(blocked), /release-tag-local-ci.*failed/);

package/scripts/release-version.mjs

@@ -46,8 +46,20 @@ switch (command) {
     await prepareRelease(state, incrementVersion(state.pkg.version, bump), dryRun);
     break;
   }
+  case "notes": {
+    checkState(state);
+    if (!value) fail("usage: node scripts/release-version.mjs notes vX.Y.Z");
+    const version = value.startsWith("v") ? value.slice(1) : value;
+    if (!stableVersionPattern.test(version)) {
+      fail(`release notes version ${JSON.stringify(value)} must be vX.Y.Z or X.Y.Z`);
+    }
+    const body = getReleaseBody(state.changelog, version);
+    if (!body) fail(`CHANGELOG.md has no release notes for ${version}`);
+    process.stdout.write(`${body}\n`);
+    break;
+  }
   default:
-    fail(`unknown release command ${JSON.stringify(command)}; expected check, tag, or next`);
+    fail(`unknown release command ${JSON.stringify(command)}; expected check, tag, next, or notes`);
 }
 
 async function readState() {
@@ -182,6 +194,17 @@ function getUnreleasedBody(changelog) {
   return changelog.slice(bodyStart, bodyEnd).trim();
 }
 
+function getReleaseBody(changelog, version) {
+  const heading = `## [${version}]`;
+  const headingIndex = changelog.indexOf(heading);
+  if (headingIndex < 0) return "";
+  const headingEnd = changelog.indexOf("\n", headingIndex);
+  const bodyStart = headingEnd < 0 ? changelog.length : headingEnd + 1;
+  const nextHeadingIndex = changelog.indexOf("\n## [", bodyStart);
+  const bodyEnd = nextHeadingIndex < 0 ? changelog.length : nextHeadingIndex;
+  return changelog.slice(bodyStart, bodyEnd).trim();
+}
+
 function incrementVersion(version, bump) {
   const match = version.match(stableVersionPattern);
   if (!match) fail(`cannot increment invalid stable version ${JSON.stringify(version)}`);