@akira-tl/forgerelay 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.3.4] - 2026-08-10
+
+### Changed
+
+- Regular MCP tool modes now use one `bash` interface for both command start and long-process interaction. `action="run"` preserves normal shell execution while `action="process"` polls/waits, writes input, resizes PTYs, or interrupts an existing workspace-owned `processId`; top-level `write_stdin` is no longer exposed in regular modes.
+- `close_workspace` is now the single public Workspace close operation. Checkout-backed workspaces release their logical handle, while managed-worktree-backed workspaces require `commitMessage` and run the existing Hook/commit/fast-forward/cleanup lifecycle; top-level `close_worktree` is no longer exposed.
+- Shell/process and managed-worktree Capability Guides, Host instructions, configuration docs, debugging acceptance, and workflow docs now use the unified process and Workspace lifecycle model.
+
+## [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

package/README.md

@@ -122,7 +122,7 @@ git worktree list
 git branch
 ```
 
-When `close_worktree` succeeds, ForgeRelay:
+When `close_workspace` succeeds for a managed-worktree-backed workspace, ForgeRelay:
 
 1. checks that the source checkout is clean and still on the expected target branch;
 2. commits any remaining worktree changes;
@@ -145,7 +145,7 @@ Hook 是 ForgeRelay 的自动生命周期规则。首选方式是一个 Hook 一
   "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,

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/managed-worktrees/GUIDE.md

@@ -4,10 +4,10 @@
 
 ## 基本模型
 
-- `workspaceId` 是逻辑工作身份；managed worktree 是物理 Git worktree。二者不要混用。
+- `workspaceId` 是 Agent 的工作身份；managed worktree 是该 Workspace 的一种物理 Git backing mode，不是 Host 需要管理的第二套 lifecycle。
 - managed worktree 使用 ForgeRelay 管理的 `forgerelay/*` 分支，不使用 detached HEAD。
 - 创建时会记录 source checkout、base ref/base SHA、managed branch 和 target branch。
-- 同一个物理 worktree 可以存在多个逻辑 workspace handle；关闭逻辑 handle 与删除物理 worktree 是不同操作。
+- 同一个物理 worktree 可以存在多个逻辑 workspace handle；finalize 一个 managed-worktree-backed Workspace 时，ForgeRelay 会统一处理同一物理 worktree 的 alias/session invalidation。
 
 ## 打开与复用
 
@@ -22,18 +22,23 @@
 
 不要为了“更安全”自动选择 worktree，也不要在用户没有要求时创建额外 Git 分支。
 
-## `close_workspace` 与 `close_worktree`
+## `close_workspace`
 
-`close_workspace` 只释放一个逻辑 `workspaceId`，不会删除 checkout 文件，也不会完成 managed branch 集成。若某个 managed worktree 仍有其他逻辑 handle，释放其中一个 handle 不会移除物理 worktree。
+`close_workspace` 是唯一公开关闭入口，行为由 Workspace backing mode 决定：
 
-`close_worktree` 用于完成一个 managed worktree：
+- checkout-backed Workspace：只释放逻辑 `workspaceId`，不会删除 checkout 文件；
+- managed-worktree-backed Workspace：要求提供 `commitMessage`，并完成下面的安全 finalize lifecycle。
+
+Managed worktree finalize：
 
 1. 要求该 worktree 的工作已经完成并验证；
-2. 若仍有未提交修改，ForgeRelay 使用调用时提供的 commit message 提交；
+2. 若仍有未提交修改，ForgeRelay 使用 `close_workspace` 提供的 commit message 提交；
 3. 只有 source checkout 干净、目标历史没有分叉且能够安全 fast-forward 时，才把 managed branch 集成到原 target branch；
-4. 成功后移除 worktree 目录和 ForgeRelay 管理分支；
+4. 成功后移除 worktree 目录和 ForgeRelay 管理分支，并关闭该物理 worktree 的逻辑 aliases；
 5. 若安全 fast-forward 不成立，不把 source checkout 留在 merge-conflict 状态，而是拒绝关闭并保留 worktree 供用户/Agent 处理。
 
+如果因为缺少 `commitMessage`、dirty source、divergence、Hook blocking 或 busy process 关闭失败，修正对应条件后继续使用**原 workspaceId** 重试；不要另开一个 worktree 来逃避失败状态。
+
 运行中的 process 或尚未消费的 process completion 也会阻止相关逻辑 workspace/worktree 被关闭。
 
 ## 外部变化与恢复

package/capabilities/shell-processes/GUIDE.md

@@ -1,10 +1,10 @@
 # ForgeRelay Shell and Processes
 
-当命令长时间运行、需要交互式 TTY、需要 `write_stdin`，或遇到 shell/process 平台边界问题时读取本指南。
+当命令长时间运行、需要交互式 TTY、需要继续操作已有 `processId`，或遇到 shell/process 平台边界问题时读取本指南。
 
 ## Core process model
 
-`bash`（Codex tool mode 下为 `exec_command`）在 open workspace 内启动命令。命令拥有本地用户权限；workspace path containment 不等于 OS sandbox。
+常规 tool mode 使用一个 `bash` 入口管理命令和后续 process lifecycle；Codex tool mode 仍可使用其兼容 command adapter。命令拥有本地用户权限；workspace path containment 不等于 OS sandbox。
 
 普通 `bash` 最多在前台等待 300 秒。如果进程仍存活，ForgeRelay 不会因为 wait window 到期而杀掉它，而是返回：
 
@@ -15,17 +15,19 @@ processId: <number>
 
 `processId` 是 canonical process handle。旧 `sessionId` 仅为 0.2.x compatibility alias，不应作为新代码或新 Agent workflow 的首选名称。
 
-## write_stdin
+## `bash(action="process")`
 
-使用同一个 `workspaceId` 和 `processId`：
+普通命令使用 `bash(action="run")`，其中 `action` 可省略；如果返回 `running: true` 和 `processId`，后续仍通过同一个 `bash` tool 操作该 process：
 
-- 省略 `chars` 或传空字符串：poll；
-- 传普通字符：向正在运行的进程写入输入；
-- 传 `\u0003`：显式发送 Ctrl-C；
+- 只传 `workspaceId`、`action="process"`、`processId`：poll / wait；
+- `input`：向正在运行的进程写入字符；
+- `interrupt: true`：显式发送 SIGINT / Ctrl-C；
 - `yieldTimeMs`：继续等待，单次最多 300000 ms；
 - `maxOutputTokens`：限制本次返回的近似输出 token；
 - `columns` / `rows`：调整已经分配 PTY 的终端尺寸。
 
+`action="run"` 与 `action="process"` 的参数不要混用。Process ownership 始终绑定原 `workspaceId`；未知或跨 workspace 的 `processId` 会被拒绝。
+
 等待超时不会隐式 kill process。若没有必要立即等待，可以继续其他工作；进程完成后，ForgeRelay 会把 completion notice 一次性附加到同一 logical workspace 的后续 tool result。
 
 不要因为暂时没有输出就重复启动相同长进程；先用返回的 `processId` poll。
@@ -42,7 +44,7 @@ rows: 24
 
 PTY 依赖 optional `node-pty`。缺少该依赖时 ForgeRelay 会明确报错；不要把它误诊成命令本身失败。对非 PTY process 使用 `columns` / `rows` resize 也会失败。
 
-对需要 prompt/REPL 的程序，用 `tty: true` + `write_stdin`；对 tests/builds/formatters 等非交互命令保持默认非 PTY，以获得更稳定的 CI-style 输出。
+对需要 prompt/REPL 的程序，用 `bash(action="run", tty=true)` 启动，再通过 `bash(action="process", processId=...)` 输入或 resize；对 tests/builds/formatters 等非交互命令保持默认非 PTY，以获得更稳定的 CI-style 输出。
 
 ## Platform notes
 

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

@@ -31,7 +31,7 @@ const CAPABILITY_GUIDE_DEFINITIONS = [
     },
     {
         name: "shell-processes",
-        description: "Long-running processes, write_stdin, PTY, and platform edges.",
+        description: "Long-running bash processes, processId interaction, PTY, and platform edges.",
         whenToRead: "Read for running or interactive command issues.",
     },
 ];
@@ -72,7 +72,7 @@ export function buildCapabilityFingerprint(config, version, context = {}) {
         "worktree.managed",
         "filesystem.rename-move",
         "filesystem.delete",
-        "process.write-stdin",
+        "process.lifecycle",
         "hooks.lifecycle",
         "capability-guides.read",
     ];

package/dist/capability-registry.js

@@ -31,7 +31,7 @@ export class CapabilityRegistry {
                     readBeforeFirstUse: definition.readGuideBeforeFirstUse,
                 },
             };
-        });
+        }).filter((entry) => entry.available);
     }
     describe(name, context) {
         const definition = this.requireDefinition(name);
@@ -48,15 +48,29 @@ export class CapabilityRegistry {
                 whenToRead: guide.whenToRead,
             },
             inputSchema: z.toJSONSchema(definition.inputSchema, { target: "draft-7" }),
+            ...(definition.nativeFileArgument
+                ? {
+                    transport: {
+                        nativeFileArgument: definition.nativeFileArgument,
+                        gatewayParameter: "file",
+                    },
+                }
+                : {}),
         };
     }
-    async run(name, argumentsValue, context) {
+    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}` : "."}`);
         }
-        const parsed = definition.inputSchema.safeParse(argumentsValue ?? {});
+        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}`)
@@ -110,9 +124,53 @@ export function createCapabilityRegistry(dependencies) {
             inputSchema: hooksCheckInput,
             availability: () => ({ available: true }),
             run: async (_input, context) => ({
-                ok: true,
-                ...await dependencies.inspectHooks(context.workspaceRoot),
+                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/mcp/server-instructions.js

@@ -1,7 +1,6 @@
 export const toolNames = {
     openWorkspace: "open_workspace",
     closeWorkspace: "close_workspace",
-    closeWorktree: "close_worktree",
     read: "read",
     write: "write",
     edit: "edit",
@@ -34,7 +33,7 @@ export function buildToolDescriptions(config) {
         rename: `Rename or move one file or directory inside an open workspace or the OS temp directory without overwriting an existing destination. Source and destination must both remain inside the permitted file roots. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         delete: `Delete one file or directory inside an open workspace or the OS temp directory. Non-empty directories require recursive=true. An allowed root itself cannot be deleted. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         applyPatch: `Apply one Codex-style patch inside an open workspace or the OS temp directory. Supports adding, overwriting, updating, deleting, and moving files. Workspace paths must remain relative; absolute paths are accepted only inside the OS temp directory. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
-        shell: `Run a shell command inside an open workspace.${shellSurface} Commands execute with the local user's authority; workspace filesystem containment does not make shell execution a sandbox. ForgeRelay waits up to 300 seconds, then returns a processId for a still-running command; use ${toolNames.writeStdin} to poll, interact, wait, or send Ctrl-C. Completed background commands may be reported later for the same workspaceId. Call ${toolNames.openWorkspace} first and pass workspaceId. Expose this capability only behind strong authentication.`,
+        shell: `Run or manage a shell process inside an open workspace.${shellSurface} Commands execute with the local user's authority; workspace filesystem containment does not make shell execution a sandbox. action=run (default) starts a command and waits up to 300 seconds; action=process uses its processId to poll, wait, write input, resize a PTY, or interrupt it. Completed background commands may also be reported later for the same workspaceId. Call ${toolNames.openWorkspace} first and pass workspaceId. Expose this capability only behind strong authentication.`,
         shellCommand: "Shell command to run with the local user's authority.",
     };
 }
@@ -42,7 +41,7 @@ function capabilityContractInstructions(config) {
     const staleWorkspacePolicy = config.toolMode === "codex"
         ? ""
         : ` 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 workspaceLifecycle = `Use ForgeRelay as a local coding workspace. Default to the user's existing checkout. Reuse the workspaceId from ${toolNames.openWorkspace}; resume or create another logical workspace only when the user asks.${staleWorkspacePolicy} Only open mode=\"worktree\" when the user explicitly asks for isolated or parallel Git work. ${toolNames.closeWorkspace} releases checkout-backed workspaces or safely finalizes managed-worktree-backed ones; managed close requires commitMessage. Read the managed-worktrees capability guide for advanced failure semantics.`;
     const agents = `Follow instructions returned by ${toolNames.openWorkspace}. Read an availableAgentsFiles path before working under it.`;
     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
@@ -66,7 +65,7 @@ function defaultWorkflowInstructions(config) {
     const inspection = config.toolMode === "full"
         ? `Prefer ${toolNames.read}, ${toolNames.grep}, ${toolNames.glob}, and ${toolNames.ls} for file inspection.`
         : `Use ${toolNames.shell} with command-line tools such as grep, rg, find, ls, and tree for search and directory inspection.`;
-    return joinInstructions(inspection, `Prefer ${toolNames.edit} for targeted content modifications, ${toolNames.write} only for new files or complete rewrites, ${toolNames.rename} for path moves, ${toolNames.delete} for removals, and ${toolNames.shell} for tests, builds, git inspection, package scripts, generators, formatters, and commands that are better executed by the shell. If ${toolNames.shell} returns a running process with a processId, use ${toolNames.writeStdin} only when you need to poll, wait, interact, or interrupt it; otherwise you may continue other work and consume its completion notice from a later tool result.`);
+    return joinInstructions(inspection, `Prefer ${toolNames.edit} for targeted content modifications, ${toolNames.write} only for new files or complete rewrites, ${toolNames.rename} for path moves, ${toolNames.delete} for removals, and ${toolNames.shell} for tests, builds, git inspection, package scripts, generators, formatters, and commands that are better executed by the shell. If ${toolNames.shell} returns a running process with a processId, call ${toolNames.shell} again with action=\"process\" when you need to poll, wait, interact, resize, or interrupt it; otherwise you may continue other work and consume its completion notice from a later tool result.`);
 }
 function joinInstructions(...parts) {
     return parts

package/dist/server.js

@@ -17,12 +17,13 @@ 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";
@@ -66,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;
     }
@@ -460,7 +461,7 @@ function attachCompletedProcessNotices(processSessions, workspaceId, result) {
 }
 function processOutputSchema() {
     return resultOutputSchema({
-        processId: z.number().int().positive().optional().describe("Canonical process handle for write_stdin."),
+        processId: z.number().int().positive().optional().describe("Canonical process handle for bash(action=\"process\") or the active command adapter."),
         sessionId: z.number().int().positive().optional().describe("Deprecated alias of processId for compatibility."),
         running: z.boolean(),
         exitCode: z.number().int().optional(),
@@ -522,6 +523,13 @@ function capabilityContextFor(workspace) {
         })),
     };
 }
+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;
 }
@@ -605,6 +613,8 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
             });
         });
     }
+    if (config.toolMode !== "codex")
+        return;
     registerAppTool(server, "write_stdin", {
         title: "Write to process",
         description: "Poll or write characters to a running process returned by bash or exec_command. Omit chars or pass an empty string to poll. Waiting never kills the process; pass \\u0003 to explicitly send Ctrl-C.",
@@ -679,8 +689,66 @@ 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",
@@ -987,7 +1055,11 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             arguments: z
                 .record(z.string(), z.unknown())
                 .optional()
-                .describe("Capability-specific arguments. Omit for describe and for capabilities with no arguments."),
+                .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(),
@@ -996,20 +1068,25 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             result: z.unknown().optional(),
             error: capabilityErrorOutputSchema.optional(),
         },
-        _meta: {},
+        _meta: {
+            ...toolWidgetDescriptorMeta(config, "capability")._meta,
+            "openai/fileParams": ["file"],
+        },
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
             idempotentHint: false,
-            openWorldHint: false,
+            openWorldHint: true,
         },
-    }, async ({ workspaceId, name, action, arguments: capabilityArguments }) => {
+    }, 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 {
@@ -1036,10 +1113,24 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                         });
                         return result;
                     }
-                    const capabilityResult = await capabilityRegistry.run(name, capabilityArguments ?? {}, capabilityContextFor(workspace));
+                    const execution = await capabilityRegistry.run(name, capabilityArguments ?? {}, capabilityContextFor(workspace), { nativeFile: file });
+                    changedPaths = execution.changedPaths ?? [];
                     const result = {
-                        content: [textBlock(`Capability ${name} completed.\n${JSON.stringify(capabilityResult, null, 2)}`)],
-                        structuredContent: { name, action, result: capabilityResult },
+                        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,
@@ -1076,53 +1167,25 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         });
     });
     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.",
+        title: "Close workspace",
+        description: "Close one workspace after the user chooses cleanup. Checkout-backed workspaces release only the logical handle. Managed-worktree-backed workspaces finalize the existing safe worktree lifecycle, including hooks, commit/integration, and cleanup; provide commitMessage for that mode. Running or unconsumed processes prevent closure.",
         inputSchema: {
-            workspaceId: z.string().describe("Logical workspace ID to release."),
-        },
-        outputSchema: resultOutputSchema({ workspaceId: z.string() }),
-        _meta: {},
-        annotations: WRITE_TOOL_ANNOTATIONS,
-    }, async ({ workspaceId }) => {
-        const workspace = workspaces.getWorkspace(workspaceId);
-        return runToolWithHooks(hooks, {
-            tool: toolNames.closeWorkspace,
-            invocation: workspaceHookInvocation(workspace),
-            payload: { workspaceId },
-            operation: async () => {
-                if (processSessions.activeWorkspaceIds().has(workspaceId)) {
-                    throw new Error(`Workspace ${workspaceId} still owns a running process or an unconsumed process completion. Poll or consume it before closing this workspace.`);
-                }
-                workspaces.closeWorkspace(workspaceId);
-                const result = `Closed logical workspace ${workspaceId}. Physical project files were not removed.`;
-                return {
-                    content: [textBlock(result)],
-                    structuredContent: { result, workspaceId },
-                };
-            },
-        });
-    });
-    registerAppTool(server, toolNames.closeWorktree, {
-        title: "Close worktree",
-        description: "Finalize a managed worktree after its task is complete and verified. ForgeRelay may commit remaining changes, integrate the target branch when safe, and clean up the managed worktree. Read the managed-worktrees capability guide for advanced close, safety, and failure semantics.",
-        inputSchema: {
-            workspaceId: z
-                .string()
-                .describe("Managed worktree workspace identifier returned by open_workspace."),
+            workspaceId: z.string().describe("Workspace identifier to close."),
             commitMessage: z
                 .string()
                 .min(1)
-                .describe("Concise Git commit message describing the completed worktree changes."),
+                .optional()
+                .describe("Required only for a managed-worktree-backed workspace; concise Git commit message for remaining worktree changes."),
         },
         outputSchema: resultOutputSchema({
             workspaceId: z.string(),
-            sourceRoot: z.string(),
-            branch: z.string(),
-            targetBranch: z.string(),
-            commitSha: z.string(),
-            mergedSha: z.string(),
-            committed: z.boolean(),
+            mode: z.enum(["checkout", "worktree"]),
+            sourceRoot: z.string().optional(),
+            branch: z.string().optional(),
+            targetBranch: z.string().optional(),
+            commitSha: z.string().optional(),
+            mergedSha: z.string().optional(),
+            committed: z.boolean().optional(),
             cleanupWarning: z.string().optional(),
         }),
         _meta: {},
@@ -1130,49 +1193,70 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     }, async ({ workspaceId, commitMessage }, extra) => {
         const workspace = workspaces.getWorkspace(workspaceId);
         return runToolWithHooks(hooks, {
-            tool: toolNames.closeWorktree,
+            tool: toolNames.closeWorkspace,
             invocation: workspaceHookInvocation(workspace),
-            payload: { commitMessage },
-            afterCwd: (response) => response.structuredContent.sourceRoot,
+            payload: { workspaceId, commitMessage, mode: workspace.mode },
+            afterCwd: (response) => "sourceRoot" in response.structuredContent &&
+                typeof response.structuredContent.sourceRoot === "string"
+                ? response.structuredContent.sourceRoot
+                : undefined,
             operation: async () => {
-                const busyWorkspaceIds = workspaces
-                    .workspaceIdsForPhysicalWorkspace(workspace)
-                    .filter((id) => processSessions.activeWorkspaceIds().has(id));
-                if (busyWorkspaceIds.length > 0) {
-                    throw new Error(`Cannot close this worktree while logical workspace processes are still running or awaiting completion delivery: ${busyWorkspaceIds.join(", ")}.`);
+                if (workspace.mode === "worktree") {
+                    if (!commitMessage) {
+                        throw new Error(`Managed-worktree-backed workspace ${workspaceId} requires commitMessage when closing.`);
+                    }
+                    const busyWorkspaceIds = workspaces
+                        .workspaceIdsForPhysicalWorkspace(workspace)
+                        .filter((id) => processSessions.activeWorkspaceIds().has(id));
+                    if (busyWorkspaceIds.length > 0) {
+                        throw new Error(`Cannot close this worktree-backed workspace while logical workspace processes are still running or awaiting completion delivery: ${busyWorkspaceIds.join(", ")}.`);
+                    }
+                    const startedAt = performance.now();
+                    const closed = await workspaces.closeWorktree(workspaceId, commitMessage);
+                    const result = [
+                        `Closed managed-worktree-backed workspace ${workspaceId}.`,
+                        `Merged ${closed.branch} into ${closed.targetBranch} by fast-forward.`,
+                        `Source checkout: ${closed.sourceRoot}`,
+                        `Commit: ${closed.commitSha}`,
+                        closed.cleanupWarning
+                            ? `Cleanup warning: ${closed.cleanupWarning}`
+                            : "The managed worktree directory and branch were removed.",
+                    ].join("\n");
+                    logToolCall(config, {
+                        tool: toolNames.closeWorkspace,
+                        ...workspaceLogContext(workspace, extra.sessionId),
+                        path: closed.sourceRoot,
+                        success: true,
+                        durationMs: Math.round(performance.now() - startedAt),
+                    });
+                    return attachHookReports({
+                        content: [textBlock(result)],
+                        structuredContent: {
+                            result,
+                            workspaceId,
+                            mode: "worktree",
+                            sourceRoot: closed.sourceRoot,
+                            branch: closed.branch,
+                            targetBranch: closed.targetBranch,
+                            commitSha: closed.commitSha,
+                            mergedSha: closed.mergedSha,
+                            committed: closed.committed,
+                            cleanupWarning: closed.cleanupWarning,
+                        },
+                    }, closed.hookReports);
                 }
-                const startedAt = performance.now();
-                const closed = await workspaces.closeWorktree(workspaceId, commitMessage);
-                const result = [
-                    `Closed managed worktree ${workspaceId}.`,
-                    `Merged ${closed.branch} into ${closed.targetBranch} by fast-forward.`,
-                    `Source checkout: ${closed.sourceRoot}`,
-                    `Commit: ${closed.commitSha}`,
-                    closed.cleanupWarning
-                        ? `Cleanup warning: ${closed.cleanupWarning}`
-                        : "The worktree directory and managed branch were removed.",
-                ].join("\n");
-                logToolCall(config, {
-                    tool: toolNames.closeWorktree,
-                    ...workspaceLogContext(workspace, extra.sessionId),
-                    path: closed.sourceRoot,
-                    success: true,
-                    durationMs: Math.round(performance.now() - startedAt),
-                });
-                return attachHookReports({
-                    content: [{ type: "text", text: result }],
-                    structuredContent: {
-                        result,
-                        workspaceId,
-                        sourceRoot: closed.sourceRoot,
-                        branch: closed.branch,
-                        targetBranch: closed.targetBranch,
-                        commitSha: closed.commitSha,
-                        mergedSha: closed.mergedSha,
-                        committed: closed.committed,
-                        cleanupWarning: closed.cleanupWarning,
-                    },
-                }, closed.hookReports);
+                if (commitMessage !== undefined) {
+                    throw new Error("close_workspace commitMessage is only valid for managed-worktree-backed workspaces.");
+                }
+                if (processSessions.activeWorkspaceIds().has(workspaceId)) {
+                    throw new Error(`Workspace ${workspaceId} still owns a running process or an unconsumed process completion. Poll or consume it before closing this workspace.`);
+                }
+                workspaces.closeWorkspace(workspaceId);
+                const result = `Closed checkout-backed workspace ${workspaceId}. Physical project files were not removed.`;
+                return {
+                    content: [textBlock(result)],
+                    structuredContent: { result, workspaceId, mode: "checkout" },
+                };
             },
         });
     });
@@ -1651,11 +1735,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",
@@ -1893,59 +1973,174 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 workspaceId: z
                     .string()
                     .describe("Workspace identifier returned by open_workspace."),
+                action: z
+                    .enum(["run", "process"])
+                    .optional()
+                    .describe("Defaults to run. Use process with a returned processId to poll, interact, resize, or interrupt a running command."),
                 command: z
                     .string()
-                    .describe(toolDescriptions.shellCommand),
+                    .optional()
+                    .describe(`${toolDescriptions.shellCommand} Required for action=run.`),
+                processId: z
+                    .number()
+                    .int()
+                    .positive()
+                    .optional()
+                    .describe("Process identifier returned by a previous bash action=run call. Required for action=process."),
+                input: z
+                    .string()
+                    .optional()
+                    .describe("Characters to write for action=process. Omit to poll/wait without input."),
+                interrupt: z
+                    .boolean()
+                    .optional()
+                    .describe("For action=process, send SIGINT to the process. Cannot be combined with input."),
+                tty: z
+                    .boolean()
+                    .optional()
+                    .describe("For action=run, allocate a pseudo-terminal for interactive commands. Defaults to false."),
+                columns: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(1_000)
+                    .optional()
+                    .describe("Initial PTY width for action=run, or resize width for action=process."),
+                rows: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(1_000)
+                    .optional()
+                    .describe("Initial PTY height for action=run, or resize height for action=process."),
                 workingDirectory: z
                     .string()
                     .optional()
-                    .describe("Optional working directory relative to the workspace root. Defaults to the workspace root."),
+                    .describe("For action=run, working directory relative to the workspace root. Defaults to the workspace root."),
+                yieldTimeMs: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .max(300_000)
+                    .optional()
+                    .describe("Milliseconds to wait before returning. Run preserves the existing 300000ms default; process polling defaults to 5000ms and interaction to 250ms."),
+                maxOutputTokens: z
+                    .number()
+                    .int()
+                    .positive()
+                    .max(100_000)
+                    .optional()
+                    .describe("Approximate output token budget. Defaults to 10000."),
             },
             outputSchema: processOutputSchema(),
             ...toolWidgetDescriptorMeta(config, "shell"),
             annotations: SHELL_TOOL_ANNOTATIONS,
-        }, async ({ workspaceId, command, workingDirectory }, extra) => {
+        }, async ({ workspaceId, action = "run", command, processId, input, interrupt, tty, columns, rows, workingDirectory, yieldTimeMs, maxOutputTokens, }, extra) => {
             const workspace = workspaces.getWorkspace(workspaceId);
+            if (action === "run") {
+                if (!command)
+                    throw new Error("bash action=run requires command.");
+                if (processId !== undefined || input !== undefined || interrupt !== undefined) {
+                    throw new Error("bash action=run does not accept processId, input, or interrupt.");
+                }
+                return runToolWithHooks(hooks, {
+                    tool: toolNames.shell,
+                    invocation: workspaceHookInvocation(workspace),
+                    payload: {
+                        action,
+                        command,
+                        workingDirectory: workingDirectory ?? ".",
+                    },
+                    isFailure: toolResultIsError,
+                    operation: async () => {
+                        const startedAt = performance.now();
+                        const cwd = workspaces.resolveWorkingDirectory(workspace, workingDirectory);
+                        const snapshot = await processSessions.start({
+                            workspaceId,
+                            command,
+                            cwd,
+                            workspaceRoot: workspace.root,
+                            tty,
+                            columns,
+                            rows,
+                            yieldTimeMs: yieldTimeMs ?? 300_000,
+                            maxOutputTokens,
+                        });
+                        logToolCall(config, {
+                            tool: toolNames.shell,
+                            ...workspaceLogContext(workspace, extra.sessionId),
+                            workingDirectory: workingDirectory ?? ".",
+                            command,
+                            commandLength: command.length,
+                            exitCode: snapshot.exitCode,
+                            running: snapshot.running,
+                            processId: snapshot.processId,
+                            success: snapshot.running || (snapshot.exitCode === 0 && !snapshot.signal),
+                            durationMs: Math.round(performance.now() - startedAt),
+                        });
+                        const response = processToolResponse(toolNames.shell, workspaceId, snapshot, {
+                            action,
+                            command,
+                            workingDirectory: workingDirectory ?? ".",
+                            running: snapshot.running,
+                            exitCode: snapshot.exitCode,
+                            wallTimeMs: snapshot.wallTimeMs,
+                        });
+                        return !snapshot.running && (snapshot.signal || snapshot.exitCode !== 0)
+                            ? { ...response, isError: true }
+                            : response;
+                    },
+                });
+            }
+            if (command !== undefined || workingDirectory !== undefined || tty !== undefined) {
+                throw new Error("bash action=process does not accept command, workingDirectory, or tty.");
+            }
+            if (processId === undefined)
+                throw new Error("bash action=process requires processId.");
+            if (interrupt && input !== undefined) {
+                throw new Error("bash action=process cannot combine interrupt with input.");
+            }
             return runToolWithHooks(hooks, {
                 tool: toolNames.shell,
                 invocation: workspaceHookInvocation(workspace),
                 payload: {
-                    command,
-                    workingDirectory: workingDirectory ?? ".",
+                    action,
+                    processId,
+                    inputLength: input?.length ?? 0,
+                    interrupt: interrupt ?? false,
+                    columns,
+                    rows,
                 },
                 isFailure: toolResultIsError,
                 operation: async () => {
                     const startedAt = performance.now();
-                    const cwd = workspaces.resolveWorkingDirectory(workspace, workingDirectory);
-                    const snapshot = await processSessions.start({
+                    const snapshot = await processSessions.write({
                         workspaceId,
-                        command,
-                        cwd,
-                        workspaceRoot: workspace.root,
-                        yieldTimeMs: 300_000,
+                        processId,
+                        chars: interrupt ? "\u0003" : input,
+                        columns,
+                        rows,
+                        yieldTimeMs,
+                        maxOutputTokens,
                     });
                     logToolCall(config, {
                         tool: toolNames.shell,
                         ...workspaceLogContext(workspace, extra.sessionId),
-                        workingDirectory: workingDirectory ?? ".",
-                        command,
-                        commandLength: command.length,
                         exitCode: snapshot.exitCode,
                         running: snapshot.running,
                         processId: snapshot.processId,
-                        success: snapshot.running || (snapshot.exitCode === 0 && !snapshot.signal),
+                        success: snapshot.running || snapshot.exitCode === 0,
                         durationMs: Math.round(performance.now() - startedAt),
                     });
-                    const response = processToolResponse(toolNames.shell, workspaceId, snapshot, {
-                        command,
-                        workingDirectory: workingDirectory ?? ".",
+                    return processToolResponse(toolNames.shell, workspaceId, snapshot, {
+                        action,
+                        processId,
+                        inputLength: input?.length ?? 0,
+                        interrupt: interrupt ?? false,
                         running: snapshot.running,
                         exitCode: snapshot.exitCode,
                         wallTimeMs: snapshot.wallTimeMs,
                     });
-                    return !snapshot.running && (snapshot.signal || snapshot.exitCode !== 0)
-                        ? { ...response, isError: true }
-                        : response;
                 },
             });
         });
@@ -1957,6 +2152,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             workspaces,
             hooks,
             incomingArtifactAdapters,
+            incomingArtifactRegistry,
         });
     }
     return server;

package/docs/chatgpt-coding-workflow.md

@@ -65,8 +65,8 @@ so a specific existing worktree can be reopened directly.
 
 ## Closing a managed worktree
 
-After the task is complete and verified, call `close_worktree` with the managed
-workspace ID and a commit message.
+After the task is complete and verified, call `close_workspace` with the managed-worktree-backed
+workspace ID and a `commitMessage`.
 
 ForgeRelay:
 
@@ -110,14 +110,17 @@ skill-discovery path.
 
 ## MCP capability loading
 
-ForgeRelay keeps callable MCP tools and explanatory capability documentation
-separate. `tools/list` remains the source of truth for what the current server
-actually exposes; 0.3 does not hide callable tools behind documentation.
+ForgeRelay keeps a small callable MCP surface separate from low-frequency capability
+details. `tools/list` remains the source of truth for the Host-visible tools, while
+registered low-frequency actions are discovered through the single `capability`
+gateway rather than each receiving another top-level tool schema.
 
-`open_workspace` adds two lightweight discovery surfaces:
+`open_workspace` adds lightweight discovery surfaces:
 
 - `capabilityFingerprint` is returned on every open/resume and includes the
   ForgeRelay version, active tool mode, and stable semantic capability names;
+- `capabilityCatalog` lists currently available registered actions such as
+  `hooks.check`, with compact guide metadata;
 - `capabilityGuides` is returned with bootstrap context and contains compact
   descriptors for ForgeRelay-owned, versioned guides that can be loaded with
   the normal `read` tool.
@@ -195,26 +198,24 @@ edit
 rename
 delete
 bash
-write_stdin
-close_worktree
+capability
 ```
 
-The exact lifecycle tools available depend on the active server configuration.
 In minimal mode, normal shell inspection commands such as `rg`, `find`, and `ls`
-can be used rather than dedicated MCP search tools. `bash` waits in the foreground
-for at most 300 seconds. If the command is still running, ForgeRelay returns a
-canonical `processId` without killing it. The Agent can use `write_stdin` to poll,
-wait again, interact, or explicitly send Ctrl-C, or continue other work; once the
-command finishes, its completion is attached to a later tool result using the
-same workspace ID. The former process `sessionId` remains a deprecated alias in
-0.2.x for compatibility with existing clients.
+can be used rather than dedicated MCP search tools. `bash(action="run")` (or plain
+`bash`, since `run` is the default) waits in the foreground for at most 300 seconds.
+If the command is still running, ForgeRelay returns a canonical `processId` without
+killing it. Reuse `bash(action="process", processId=...)` to poll/wait, send input,
+resize a PTY, or interrupt the existing process; or continue other work and consume
+the one-shot completion notice from a later result in the same workspace.
 
 `FORGERELAY_TOOL_MODE=full` adds dedicated search/directory tools.
 
-Experimental `FORGERELAY_TOOL_MODE=codex` provides a smaller Codex-shaped
-surface including direct `rename`/`delete` path mutations alongside `apply_patch`,
-`exec_command`, and `write_stdin`. `rename` is the unified move/rename primitive
-for both files and directories; ForgeRelay does not expose a separate `move` tool.
+Experimental `FORGERELAY_TOOL_MODE=codex` keeps its Codex-shaped compatibility
+surface, including direct `rename`/`delete` path mutations alongside `apply_patch`,
+`exec_command`, and a compatibility `write_stdin` process adapter. `rename` is the
+unified move/rename primitive for both files and directories; ForgeRelay does not
+expose a separate `move` tool.
 
 Workspace IDs are logical conversation handles rather than physical-directory
 identities. The same conversation keeps a stable ID for a project, while another
@@ -223,8 +224,9 @@ worktree. `open_workspace` can explicitly resume a known `workspaceId`, and a
 fresh logical ID is created only when the user asks for one. When a project has
 other logical workspaces idle for more than two days, `open_workspace` reports
 all of them so the user can choose to resume or clean them up. `close_workspace`
-releases only the logical handle; the last handle for a physical worktree cannot
-be released that way and must be finalized with `close_worktree`.
+is the single public close operation: checkout-backed workspaces release the logical
+handle, while managed-worktree-backed workspaces require `commitMessage` and run the
+safe commit / fast-forward-only integration / cleanup lifecycle.
 
 Shell commands are allowed to modify ordinary project files when that is a
 natural part of the user's requested development task; ForgeRelay does not apply

package/docs/configuration.md

@@ -115,9 +115,9 @@ MCP clients discover metadata from:
 
 | Value | Behavior |
 | --- | --- |
-| `minimal` | Default. Exposes `open_workspace`, `close_workspace`, `read`, `write`, `edit`, `rename`, `delete`, `bash`, `write_stdin`, and `close_worktree`. |
+| `minimal` | Default. Exposes `open_workspace`, `close_workspace`, `read`, `write`, `edit`, `rename`, `delete`, `bash`, and `capability`. |
 | `full` | Adds dedicated `grep`, `glob`, and `ls` tools. |
-| `codex` | Experimental Codex-shaped tool surface using `open_workspace`, `close_workspace`, `read`, `rename`, `delete`, `apply_patch`, `exec_command`, `write_stdin`, and `close_worktree`. |
+| `codex` | Experimental Codex-shaped compatibility surface using `open_workspace`, `close_workspace`, `read`, `rename`, `delete`, `apply_patch`, `exec_command`, `write_stdin`, and `capability`. |
 
 `FORGERELAY_MINIMAL_TOOLS` remains a compatibility-style boolean alias when the
 explicit tool mode is unset. The corresponding legacy `DEVSPACE_*` names are
@@ -163,16 +163,21 @@ current conversation. `newWorkspace: true` allocates a new logical handle withou
 creating another checkout or Git worktree and should be used only on explicit user
 request. Logical workspaces idle for more than two days are returned in `staleWorkspaces` so
 the user can choose whether to resume or release them. `close_workspace` removes a
-logical handle without deleting checkout files; it refuses to remove the last
-handle anchoring a physical worktree.
-
-`bash` has no execution-timeout input. It waits in the foreground for at most 300
-seconds; if the process is still alive, the result contains `running: true` and a
-canonical `processId`. `write_stdin` can poll or interact with that process for up
-to another 300 seconds per call. The former `sessionId` field remains a deprecated
-alias during the 0.2.x compatibility window. ForgeRelay does not kill a process
-merely because a wait window expires. Completed background processes are delivered once with a later
-tool result for the same logical workspace ID.
+checkout-backed logical handle without deleting checkout files. For a managed-worktree-backed
+workspace, `close_workspace` requires `commitMessage` and runs the existing safe
+worktree finalize lifecycle: close Hooks, commit when needed, fast-forward-only
+integration, cleanup, and alias invalidation.
+
+Regular `bash` has no execution-timeout input. `action="run"` (the default) waits
+in the foreground for at most 300 seconds; if the process is still alive, the
+result contains `running: true` and a canonical `processId`. Reuse the same `bash`
+with `action="process"` to poll/wait, send `input`, resize a PTY, or set
+`interrupt:true`; each wait can be up to 300 seconds. ForgeRelay does not kill a
+process merely because a wait window expires. Completed background processes are
+delivered once with a later tool result for the same logical workspace ID.
+
+Codex mode retains `write_stdin` only as an experimental compatibility adapter;
+regular Agent workflows should use the single `bash` process lifecycle.
 
 ## Widgets
 

package/docs/debugging.md

@@ -59,11 +59,11 @@ The acceptance checks:
 3. unauthenticated `/mcp` rejection;
 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;
+6. `tools/list` for the full debug tool surface, including unified `close_workspace`, absence of regular `write_stdin` / `close_worktree`, canonical `bash` `action="run"` / `action="process"` plus `processId`, the non-blanket shell mutation policy, no kill-timeout input, 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`, 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`;
+8. a real checkout workspace with `write`, `read`, `rename`, `delete`, foreground `bash`, `bash` long-process `run` → `processId` → `process`, 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`;
+10. a temporary Git repository with managed worktree creation, file modification, and `close_workspace` worktree finalization;
 11. 本地 bare remote 上的 release-tag-push Hook：成功 Hook 必须先运行再允许 `v0.2.0` push，失败 Hook 必须在 remote mutation 前阻断 `v0.2.1`；
 12. deterministic local subagent error path，不联系任何模型 provider；
 13. debug hook recorder 覆盖全部九个 Hooks v1 lifecycle events。

package/docs/gotchas.md

@@ -165,18 +165,19 @@ Legacy persisted `devspace/*` branches remain valid and closable.
 Uncommitted source-checkout changes are not automatically copied into a newly
 created worktree.
 
-## `close_worktree` refuses to finish
+## `close_workspace` refuses to finalize a managed worktree
 
-Close is deliberately refused when:
+For a managed-worktree-backed workspace, close is deliberately refused when:
 
 - the source checkout is dirty;
 - the source checkout is no longer on the recorded target branch;
 - the managed worktree is on the wrong branch;
 - source and managed histories diverged.
 
-Integration is fast-forward-only. If histories diverge, rebase and verify inside
-the managed worktree, then retry. ForgeRelay does not intentionally leave the
-source checkout in a merge-conflict state.
+A `commitMessage` is also required for managed-worktree-backed close. Integration
+is fast-forward-only. If histories diverge, rebase and verify inside the managed
+worktree, then retry the same `close_workspace` call with the original workspaceId.
+ForgeRelay does not intentionally leave the source checkout in a merge-conflict state.
 
 ## Windows shell commands fail
 

package/docs/security.md

@@ -141,9 +141,9 @@ Do not describe ForgeRelay as a sandboxed coding environment.
 
 Shell execution has a 300-second foreground wait ceiling, not a 300-second
 process lifetime. When `bash` is still running after that window, ForgeRelay
-returns a canonical `processId` and leaves the process alive. `write_stdin` can
-poll, wait, interact, or explicitly interrupt it. The former process `sessionId`
-remains a deprecated compatibility alias during 0.2.x. An asynchronously completed process
+returns a canonical `processId` and leaves the process alive. Regular tool modes
+reuse `bash(action="process")` to poll, wait, write input, resize a PTY, or
+explicitly interrupt that process. An asynchronously completed process
 is reported on a later tool result for the same logical workspace ID, including
 error-result paths, and is never broadcast to another workspace ID. Explicitly
 resuming the same workspace ID in another conversation intentionally transfers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",

package/scripts/debug/accept.mjs

@@ -129,9 +129,11 @@ 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", "capability"]) {
+  for (const expected of ["open_workspace", "close_workspace", "read", "write", "edit", "rename", "delete", "grep", "glob", "ls", "bash", "capability"]) {
     assert.ok(toolNames.includes(expected), `missing debug tool ${expected}`);
   }
+  assert.equal(toolNames.includes("close_worktree"), false);
+  assert.equal(toolNames.includes("write_stdin"), false);
   const bashTool = tools.find((tool) => tool.name === "bash");
   assert.match(bashTool?.description ?? "", /local user's authority/);
   assert.doesNotMatch(bashTool?.description ?? "", /may modify ordinary project files/);
@@ -139,18 +141,10 @@ try {
   assert.doesNotMatch(bashTool?.description ?? "", /external device or hardware mutations/);
   assert.doesNotMatch(bashTool?.description ?? "", /Do not use bash to create, move, rename, or delete project files/);
   assert.equal(bashTool?.inputSchema?.properties?.timeout, undefined);
-  assert.match(bashTool?.description ?? "", /waits up to 300 seconds/);
-  assert.match(bashTool?.description ?? "", /write_stdin/);
-  const writeStdinTool = tools.find((tool) => tool.name === "write_stdin");
-  assert.equal(writeStdinTool?.inputSchema?.properties?.yieldTimeMs?.maximum, 300000);
-  assert.match(
-    writeStdinTool?.inputSchema?.properties?.processId?.description ?? "",
-    /Canonical process identifier/,
-  );
-  assert.match(
-    writeStdinTool?.inputSchema?.properties?.sessionId?.description ?? "",
-    /Deprecated alias for processId/,
-  );
+  assert.match(bashTool?.description ?? "", /action=process/);
+  assert.equal(bashTool?.inputSchema?.properties?.yieldTimeMs?.maximum, 300000);
+  assert.match(bashTool?.inputSchema?.properties?.processId?.description ?? "", /action=process/);
+  assert.match(bashTool?.inputSchema?.properties?.interrupt?.description ?? "", /SIGINT/);
   const openWorkspaceTool = tools.find((tool) => tool.name === "open_workspace");
   assert.ok(openWorkspaceTool?.inputSchema?.properties?.workspaceId);
   assert.ok(openWorkspaceTool?.inputSchema?.properties?.newWorkspace);
@@ -234,7 +228,7 @@ try {
       "worktree.managed",
       "filesystem.rename-move",
       "filesystem.delete",
-      "process.write-stdin",
+      "process.lifecycle",
       "hooks.lifecycle",
       "capability-guides.read",
       "inspection.search-tools",
@@ -306,6 +300,25 @@ try {
   assert.equal(shell.structuredContent.running, false);
   pass("bash", "foreground command completed through ProcessManager");
 
+  const background = callTool(oauth.accessToken, sessionId, 61, "bash", {
+    workspaceId,
+    action: "run",
+    command: `${JSON.stringify(process.execPath)} -e "setTimeout(() => console.log('debug-process-ok'), 100)"`,
+    yieldTimeMs: 0,
+  });
+  assert.equal(background.structuredContent.running, true);
+  assert.equal(typeof background.structuredContent.processId, "number");
+  const polled = callTool(oauth.accessToken, sessionId, 62, "bash", {
+    workspaceId,
+    action: "process",
+    processId: background.structuredContent.processId,
+    yieldTimeMs: 5_000,
+  });
+  assert.equal(polled.structuredContent.running, false);
+  assert.equal(polled.structuredContent.exitCode, 0);
+  assert.match(polled.structuredContent.result, /debug-process-ok/);
+  pass("bash process", "action=run -> processId -> action=process completed through one MCP tool");
+
   const failedEdit = callTool(oauth.accessToken, sessionId, 7, "edit", {
     workspaceId,
     path: "acceptance.txt",
@@ -390,7 +403,7 @@ try {
     path: "feature.txt",
     content: "debug worktree acceptance\n",
   });
-  const closed = callTool(oauth.accessToken, sessionId, 10, "close_worktree", {
+  const closed = callTool(oauth.accessToken, sessionId, 10, "close_workspace", {
     workspaceId: worktreeWorkspaceId,
     commitMessage: "test(debug): verify 7677 worktree lifecycle",
   });
@@ -401,7 +414,7 @@ try {
     "debug worktree acceptance\n",
   );
   pass(
-    "managed worktree close",
+    "managed worktree workspace close",
     `${closed.structuredContent.branch} -> ${closed.structuredContent.targetBranch}`,
   );
 
@@ -734,6 +747,7 @@ function exerciseReleaseTagHooks(accessToken, sessionId) {
   assert.ok(existsSync(join(releaseProject, "release-ci-ran.txt")));
   assert.deepEqual(JSON.parse(readFileSync(join(releaseProject, "release-ci-ran.txt"), "utf8")), {
     tool: "bash",
+    action: "run",
     command: "git push origin v0.2.0",
     workingDirectory: ".",
     originalCommand: "git status --short && git push origin v0.2.0 && echo release-pushed",