@akira-tl/forgerelay 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.3.5] - 2026-08-10
+
+### Changed
+
+- Regular `minimal` and `full` MCP modes now expose the same canonical 9-tool surface: `open_workspace`, `capability`, `close_workspace`, `read`, `write`, `edit`, `rename`, `delete`, and `bash`. Search and directory inspection use shell commands through `bash`; `full` remains only as a configuration-compatibility value.
+- `review.changes` and `artifact.download` are now Capability Gateway-only workflows. Their dedicated top-level compatibility aliases have been removed, while review cards identify themselves as `capability` results with `capabilityName="review.changes"`.
+- Capability fingerprints now report semantic runtime capabilities such as `review.changes` instead of implementation-shaped search/review tool names, and current Guides/docs/bootstrap instructions use the final Core Surface + Capability Gateway model.
+
+### Removed
+
+- Removed the regular dedicated `grep`, `glob`, `ls`, aggregate-review, and native-artifact MCP adapters after their canonical workflows moved to `bash` or the Capability Gateway.
+
+### Fixed
+
+- Successful `report: true` lifecycle Hook reports are now mirrored into the model-readable structured result as well as MCP text content, so Hosts that surface only structured tool results still expose the Hook outcome to the Agent.
+
+## [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

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

@@ -12,8 +12,6 @@ Native artifact download 默认关闭，且当前安全发布实现主要面向
 2. 调用 `capability`，`name="artifact.download"`、`action="run"`，把 Host 原样提供的 native `file` 值放在 Gateway 顶层 `file`，并在 `arguments.path` 传 workspace-relative 目标路径；
 3. 成功后使用返回的 normalized relative path 配合普通 `read` / `rename` / `delete` / shell 等工具继续处理。
 
-0.3.3 仍保留 `download_artifact` 作为迁移期 compatibility alias，但新的 Agent workflow 不应把它视为长期 public surface。
-
 `artifact.download` 会创建缺失的父目录，但拒绝覆盖已有目标。不要把 native file 值改造成：
 
 - 任意 URL 字符串；
@@ -35,10 +33,10 @@ Native artifact download 默认关闭，且当前安全发布实现主要面向
 
 Plain MCP Host 可以忽略这些 UI metadata；不要把 UI 是否显示当成文件操作是否成功的判据。
 
-当 Capability catalog 广告 `review.changes` 时，本轮成功修改文件后，在最后一个相关 file mutation 之后、final response 之前通过 `capability` 调用一次，让用户看到聚合 diff；不要每改一个文件就调用一次。0.3.3 仍保留 `show_changes` compatibility alias，但它和 `review.changes` 共用同一套 checkpoint，不是两套 review 状态。
+当 Capability catalog 广告 `review.changes` 时，本轮成功修改文件后，在最后一个相关 file mutation 之后、final response 之前通过 `capability` 调用一次，让用户看到聚合 diff；不要每改一个文件就调用一次。
 
 `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 registered capability，而不是 Agent 自己的文件搬运协议。`tools/list` 只负责暴露稳定 Gateway 与当前兼容 aliases；真正可用的低频能力以当前 workspace 的 Capability catalog 为准。本指南提供流程和边界，不额外创造隐藏执行入口。
+Artifact transfer 和 change review 都属于 ForgeRelay registered capability，而不是 Agent 自己的文件搬运协议。`tools/list` 只暴露稳定 `capability` Gateway；真正可用的低频能力以当前 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

@@ -2,18 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
 import { link, lstat, mkdir, open, readdir, unlink, } from "node:fs/promises";
 import { isAbsolute, join, normalize, sep } from "node:path";
-import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
-import * as z from "zod/v4";
 import { ArtifactError } from "./artifact-error.js";
-import { runToolWithHooks } from "./hooks.js";
-import { describeIncomingArtifactValue, IncomingArtifactAdapterRegistry, } from "./incoming-artifacts.js";
-import { logEvent, workspaceLogLabel } from "./logger.js";
-const ARTIFACT_WRITE_ANNOTATIONS = {
-    readOnlyHint: false,
-    destructiveHint: false,
-    idempotentHint: false,
-    openWorldHint: true,
-};
 const NO_FOLLOW = fsConstants.O_NOFOLLOW ?? 0;
 const DIRECTORY_FLAGS = fsConstants.O_RDONLY | (fsConstants.O_DIRECTORY ?? 0) | NO_FOLLOW;
 const PARTIAL_PREFIX = ".forgerelay-download-";
@@ -21,64 +10,9 @@ const PARTIAL_SUFFIX = ".partial";
 const STALE_PARTIAL_AGE_MS = 24 * 60 * 60 * 1_000;
 const MAX_STALE_PARTIAL_CLEANUP = 32;
 const ARTIFACT_DOWNLOAD_PLATFORMS = new Set(["linux"]);
-const openAIFileReferenceInputSchema = 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(),
-});
 export function isArtifactDownloadSupportedPlatform(platform = process.platform) {
     return ARTIFACT_DOWNLOAD_PLATFORMS.has(platform);
 }
-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.",
-        inputSchema: {
-            file: openAIFileReferenceInputSchema.describe("Native file value authorized and supplied by the MCP host."),
-            workspaceId: z.string().min(1).describe("Workspace identifier returned by open_workspace."),
-            path: z.string().min(1).describe("Relative destination path inside the selected workspace. The destination must not already exist."),
-        },
-        outputSchema: {
-            path: z.string(),
-        },
-        _meta: { "openai/fileParams": ["file"] },
-        annotations: ARTIFACT_WRITE_ANNOTATIONS,
-    }, async (input) => {
-        const workspace = workspaces.getWorkspace(input.workspaceId);
-        return runToolWithHooks(hooks, {
-            tool: "download_artifact",
-            invocation: {
-                workspaceId: workspace.id,
-                workspaceRoot: workspace.root,
-                workspaceMode: workspace.mode,
-                sourceRoot: workspace.sourceRoot,
-            },
-            payload: { path: input.path },
-            changedPaths: (result) => [result.structuredContent.path],
-            operation: () => executeArtifactTool(config, input, {
-                workspace: workspaceLogLabel(workspace.root, workspace.id),
-            }, async () => {
-                const downloaded = await downloadIncomingArtifact({
-                    registry: incomingRegistry,
-                    workspaceId: workspace.id,
-                    workspaceRoot: workspace.root,
-                    maxFileBytes: config.artifactMaxFileBytes,
-                    file: input.file,
-                    path: input.path,
-                });
-                return {
-                    publicResult: { path: downloaded.path },
-                    logResult: downloaded,
-                };
-            }),
-        });
-    });
-}
 /**
  * Stream a trusted native file directly into one already-open workspace.
  *
@@ -159,53 +93,6 @@ export async function downloadIncomingArtifact({ registry, workspaceId, workspac
         await workspaceHandle?.close().catch(() => undefined);
     }
 }
-export function artifactToolLogFields(input) {
-    return {
-        fileProvided: input.file !== undefined,
-        fileReferenceShape: describeIncomingArtifactValue(input.file),
-        downloadUrlHostname: incomingFileDownloadHostname(input.file),
-        workspaceId: input.workspaceId,
-        path: input.path,
-    };
-}
-async function executeArtifactTool(config, input, logContext, operation) {
-    const startedAt = performance.now();
-    try {
-        const { publicResult, logResult } = await operation();
-        if (config.logging.toolCalls) {
-            logEvent(config.logging, "info", "artifact_tool_call", {
-                tool: "download_artifact",
-                ...artifactToolLogFields(input),
-                ...logContext,
-                path: logResult.path,
-                size: logResult.size,
-                sha256: logResult.sha256,
-                success: true,
-                durationMs: Math.round(performance.now() - startedAt),
-            });
-        }
-        return artifactToolResponse(publicResult);
-    }
-    catch (error) {
-        if (config.logging.toolCalls) {
-            logEvent(config.logging, "warn", "artifact_tool_call", {
-                tool: "download_artifact",
-                ...artifactToolLogFields(input),
-                ...logContext,
-                success: false,
-                errorCode: error instanceof ArtifactError ? error.code : "internal_error",
-                durationMs: Math.round(performance.now() - startedAt),
-            });
-        }
-        throw error;
-    }
-}
-function artifactToolResponse(result) {
-    return {
-        content: [{ type: "text", text: JSON.stringify(result) }],
-        structuredContent: result,
-    };
-}
 async function openDirectoryNoFollow(path, code, message) {
     let handle;
     try {
@@ -356,21 +243,6 @@ async function writeAll(handle, buffer, position) {
         offset += bytesWritten;
     }
 }
-function incomingFileDownloadHostname(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        return undefined;
-    }
-    const rawUrl = value.download_url;
-    if (typeof rawUrl !== "string")
-        return undefined;
-    try {
-        const hostname = new URL(rawUrl).hostname.toLowerCase();
-        return hostname.length > 0 && hostname.length <= 253 ? hostname : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
 function incomingStreamChunk(value) {
     if (Buffer.isBuffer(value))
         return value;

package/dist/capabilities.js

@@ -21,7 +21,7 @@ const CAPABILITY_GUIDE_DEFINITIONS = [
     {
         name: "artifacts-review",
         description: "Native artifact transfer and aggregate change review.",
-        whenToRead: "Read for host-provided files or show_changes.",
+        whenToRead: "Read for host-provided files or aggregate change review.",
         enabled: (config) => config.artifactsEnabled || config.widgets === "changes",
     },
     {
@@ -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,13 +72,10 @@ export function buildCapabilityFingerprint(config, version, context = {}) {
         "worktree.managed",
         "filesystem.rename-move",
         "filesystem.delete",
-        "process.write-stdin",
+        "process.lifecycle",
         "hooks.lifecycle",
         "capability-guides.read",
     ];
-    if (config.toolMode === "full") {
-        capabilities.push("inspection.search-tools");
-    }
     if (config.subagents) {
         capabilities.push("subagent.profiles");
     }
@@ -89,7 +86,7 @@ export function buildCapabilityFingerprint(config, version, context = {}) {
         capabilities.push("ui.mcp-app");
     }
     if (config.widgets === "changes") {
-        capabilities.push("review.show-changes");
+        capabilities.push("review.changes");
     }
     return {
         version,

package/dist/hooks.js

@@ -152,6 +152,10 @@ export function attachHookReports(result, executions) {
     const summary = formatVisibleHookReports(executions);
     if (!summary || !isRecord(result) || !Array.isArray(result.content))
         return result;
+    const structuredContent = isRecord(result.structuredContent) ? result.structuredContent : undefined;
+    const structuredResult = typeof structuredContent?.result === "string"
+        ? structuredContent.result
+        : undefined;
     return {
         ...result,
         content: [
@@ -161,6 +165,14 @@ export function attachHookReports(result, executions) {
                 text: summary,
             },
         ],
+        ...(structuredContent && structuredResult !== undefined
+            ? {
+                structuredContent: {
+                    ...structuredContent,
+                    result: `${structuredResult}\n\n${summary}`,
+                },
+            }
+            : {}),
     };
 }
 function appendHookReportsToError(error, executions) {

package/dist/mcp/server-instructions.js

@@ -1,15 +1,11 @@
 export const toolNames = {
     openWorkspace: "open_workspace",
     closeWorkspace: "close_workspace",
-    closeWorktree: "close_worktree",
     read: "read",
     write: "write",
     edit: "edit",
     rename: "rename",
     delete: "delete",
-    grep: "grep",
-    glob: "glob",
-    ls: "ls",
     shell: "bash",
     writeStdin: "write_stdin",
     capability: "capability",
@@ -24,9 +20,9 @@ export function buildToolDescriptions(config) {
     const skillCapability = config.skillsEnabled
         ? " Advertised skill paths may also be outside the workspace."
         : "";
-    const shellSurface = config.toolMode === "minimal"
-        ? ` In minimal tool mode, ${toolNames.grep}, ${toolNames.glob}, and ${toolNames.ls} are disabled, so shell commands may be used for equivalent search and directory inspection.`
-        : "";
+    const shellSurface = config.toolMode === "codex"
+        ? ""
+        : " Use shell commands for search and directory inspection instead of dedicated MCP search tools.";
     return {
         read: `Read a file inside an open workspace or the OS temp directory. Instruction files and advertised capability guides returned by ${toolNames.openWorkspace} are also readable when applicable.${skillCapability} Only advertised entry files and files under already-loaded advertised directories are readable outside the normal roots. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         write: `Create or completely overwrite a file inside an open workspace or the OS temp directory. Workspace paths may be relative; OS temp paths may be absolute. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
@@ -34,7 +30,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 +38,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
@@ -63,10 +59,8 @@ function defaultWorkflowInstructions(config) {
     if (config.toolMode === "codex") {
         return `Use ${toolNames.read} for direct file reads, ${toolNames.rename} and ${toolNames.delete} for direct path moves or removals, apply_patch for content modifications, exec_command for inspection, tests, builds, and other commands, and ${toolNames.writeStdin} to poll or interact with running processes.`;
     }
-    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.`);
+    const 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, 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/review-checkpoints.js

@@ -39,19 +39,19 @@ export function createReviewCheckpointManager() {
             }
             assertWorkspaceRoot(state, workspaceId, root);
             if (!state?.gitRoot) {
-                throw new Error(state?.diagnostic ?? "show_changes requires a Git workspace in this version.");
+                throw new Error(state?.diagnostic ?? "review.changes requires a Git workspace in this version.");
             }
             let effectiveSince = since;
             let usedWorkspaceOpenFallback = false;
             if (since === "last_shown" && !state.baselineRefAvailable) {
                 if (!state.openRefAvailable) {
-                    throw new Error("Review checkpoints are missing; show_changes cannot reconstruct that history safely.");
+                    throw new Error("Review checkpoints are missing; review.changes cannot reconstruct that history safely.");
                 }
                 effectiveSince = "workspace_open";
                 usedWorkspaceOpenFallback = true;
             }
             else if (since === "workspace_open" && !state.openRefAvailable) {
-                throw new Error("The workspace-open review checkpoint is missing; show_changes cannot reconstruct that history safely.");
+                throw new Error("The workspace-open review checkpoint is missing; review.changes cannot reconstruct that history safely.");
             }
             const baselineRef = effectiveSince === "workspace_open" ? state.openRef : state.baselineRef;
             const baseline = (await git(state.gitRoot, ["rev-parse", "--verify", `${baselineRef}^{commit}`])).stdout.trim();
@@ -98,7 +98,7 @@ async function initializeWorkspaceState(states, workspaceId, root) {
     try {
         const eligibility = await getGitEligibility(root);
         if (!eligibility.ok || !eligibility.gitRoot) {
-            state.diagnostic = eligibility.message ?? "show_changes requires a Git workspace in this version.";
+            state.diagnostic = eligibility.message ?? "review.changes requires a Git workspace in this version.";
             return;
         }
         const [openCommit, baselineCommit] = await Promise.all([