@akira-tl/forgerelay 0.8.2 → 0.8.4

package/dist/server.js

@@ -21,7 +21,7 @@ import { HostTurnStore } from "./activity/host-turn-store.js";
 import { registerActivityQueryTools } from "./activity/mcp-query-tools.js";
 import { ActivityLifecycle, } from "./activity/lifecycle.js";
 import { ActivityQueryService } from "./activity/query-service.js";
-import { buildCapabilityFingerprint } from "./capabilities.js";
+import { buildCapabilityFingerprint, loadCapabilityGuides } from "./capabilities.js";
 import { CapabilityError, createCapabilityRegistry, } from "./capability-registry.js";
 import { deletePath, renamePath } from "./file-mutations.js";
 import { downloadIncomingArtifact, isArtifactDownloadSupportedPlatform, } from "./artifact-tools.js";
@@ -53,6 +53,8 @@ import { ACTIVITY_PANEL_APP_LEGACY_URI, ACTIVITY_PANEL_APP_URI_TEMPLATE, MCP_APP
 import { shutdownHttpServer } from "./server-shutdown.js";
 import { formatPathForPrompt } from "./skills.js";
 import { createWorkspaceStore } from "./workspace-store.js";
+import { WorkspaceTaskReminderTracker } from "./workspace-task-reminders.js";
+import { WorkspaceTaskStore } from "./workspace-tasks.js";
 import { formatAgentsPath, WorkspaceRegistry } from "./workspaces.js";
 import { formatAvailableSubagentProfile, summarizeSubagentProfile } from "./subagents/profiles.js";
 import { formatSubagentProviderAvailabilitySummary, formatUnavailableSubagentProvider, getSubagentProviderAvailabilitySnapshot, } from "./subagents/providers/availability.js";
@@ -258,6 +260,74 @@ const workspaceInventoryPageOutputSchema = z.object({
     limit: z.number().int().positive(),
     hasMore: z.boolean(),
 });
+const workspaceTaskInspectionSummaryOutputSchema = z.object({
+    level: z.literal("summary"),
+    version: z.literal(1),
+    revision: z.number().int().nonnegative(),
+    lists: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        state: z.enum(["active", "archived"]),
+        revision: z.number().int().positive(),
+        taskCount: z.number().int().nonnegative(),
+        unfinishedTaskCount: z.number().int().nonnegative(),
+    })),
+});
+const workspaceInspectionMemberOutputSchema = z.object({
+    name: z.string(),
+    purpose: z.string(),
+    workspaceId: z.string(),
+    known: z.boolean(),
+    location: z.enum(["local", "relay"]).optional(),
+    state: z.enum(["active", "stale", "invalid", "closed"]).optional(),
+    status: z.string().optional(),
+    routeState: z.literal("known").optional(),
+    mode: z.enum(["checkout", "worktree"]).optional(),
+    rootValid: z.boolean().optional(),
+});
+const workspaceInspectionOutputSchema = z.union([
+    z.object({
+        workspaceId: z.string(),
+        kind: z.literal("workspace"),
+        location: z.literal("local"),
+        label: z.string(),
+        root: z.string(),
+        status: z.string(),
+        state: z.enum(["active", "stale", "invalid", "closed"]),
+        mode: z.enum(["checkout", "worktree"]),
+        sourceRoot: z.string().optional(),
+        branch: z.string().optional(),
+        targetBranch: z.string().optional(),
+        managed: z.boolean(),
+        createdAt: z.string(),
+        lastUsedAt: z.string(),
+        idleMs: z.number().nonnegative(),
+        rootValid: z.boolean(),
+        taskSummary: workspaceTaskInspectionSummaryOutputSchema.optional(),
+    }),
+    z.object({
+        workspaceId: z.string(),
+        kind: z.literal("workspace"),
+        location: z.literal("relay"),
+        root: z.string(),
+        routeState: z.literal("known"),
+        mode: z.enum(["checkout", "worktree"]),
+        sourceRoot: z.string().optional(),
+        relay: z.string(),
+        executionLocation: z.string(),
+    }),
+    z.object({
+        workspaceId: z.string(),
+        kind: z.literal("composite"),
+        name: z.string(),
+        status: z.enum(["active", "closed"]),
+        state: z.enum(["active", "closed"]),
+        createdAt: z.string(),
+        lastUsedAt: z.string(),
+        members: z.array(workspaceInspectionMemberOutputSchema),
+        taskSummary: workspaceTaskInspectionSummaryOutputSchema.optional(),
+    }),
+]);
 const reviewFileOutputSchema = z.object({
     path: z.string(),
     previousPath: z.string().optional(),
@@ -344,6 +414,17 @@ function logFailedToolResponse(config, fields, content, startedAt) {
 function textBlock(text) {
     return { type: "text", text };
 }
+function attachWorkspaceTaskReminder(result, reminder) {
+    if (!reminder || toolResultIsError(result) || typeof result !== "object" || result === null)
+        return result;
+    const content = result.content;
+    if (!Array.isArray(content))
+        return result;
+    return {
+        ...result,
+        content: [...content, textBlock(reminder)],
+    };
+}
 function textSummary(content) {
     const text = contentText(content);
     return {
@@ -821,6 +902,7 @@ function workspaceHookInvocation(workspace) {
 function capabilityContextFor(workspace) {
     return {
         workspaceId: workspace.id,
+        workspaceKind: "workspace",
         workspaceRoot: workspace.root,
         guides: workspace.capabilityGuides.map((guide) => ({
             name: guide.name,
@@ -830,6 +912,66 @@ function capabilityContextFor(workspace) {
         })),
     };
 }
+function compositeCapabilityContext(workspaceId, guides) {
+    return {
+        workspaceId,
+        workspaceKind: "composite",
+        guides: guides.map((guide) => ({
+            name: guide.name,
+            description: guide.description,
+            whenToRead: guide.whenToRead,
+            path: formatPathForPrompt(guide.filePath),
+        })),
+    };
+}
+function requireCapabilityWorkspaceRoot(context) {
+    if (!context.workspaceRoot) {
+        throw new CapabilityError("capability_unavailable", `Capability execution requires a filesystem-backed Workspace; ${context.workspaceId} is ${context.workspaceKind}.`);
+    }
+    return context.workspaceRoot;
+}
+function runWorkspaceTasksCapability(store, workspaceId, input) {
+    switch (input.operation) {
+        case "get":
+            if (input.level === "headers")
+                return store.readHeaders(workspaceId, input.listId);
+            if (input.level === "detail")
+                return store.readTaskDetail(workspaceId, input.listId, input.taskId);
+            return store.readSummary(workspaceId);
+        case "list.create":
+            store.createList(workspaceId, { name: input.name, position: input.position });
+            return store.readSummary(workspaceId);
+        case "list.update":
+            store.updateList(workspaceId, input.listId, {
+                name: input.name,
+                state: input.state,
+                position: input.position,
+            });
+            return store.readSummary(workspaceId);
+        case "list.delete":
+            store.deleteList(workspaceId, input.listId);
+            return store.readSummary(workspaceId);
+        case "task.create":
+            store.createTask(workspaceId, input.listId, {
+                subject: input.subject,
+                content: input.content,
+                status: input.status,
+                position: input.position,
+            });
+            return store.readHeaders(workspaceId, input.listId);
+        case "task.update":
+            store.updateTask(workspaceId, input.listId, input.taskId, {
+                subject: input.subject,
+                content: input.content,
+                status: input.status,
+                position: input.position,
+            });
+            return store.readHeaders(workspaceId, input.listId);
+        case "task.delete":
+            store.deleteTask(workspaceId, input.listId, input.taskId);
+            return store.readHeaders(workspaceId, input.listId);
+    }
+}
 async function reviewWorkspaceChanges(reviewCheckpoints, workspace) {
     return reviewCheckpoints.reviewChanges({
         workspaceId: workspace.id,
@@ -1054,7 +1196,7 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
             const target = routing.resolve(workspaceId, member);
             const context = await routing.prepare(target, extra._meta, extra.signal, extra.sessionId);
             if (routing.isRemote(target.executionWorkspaceId)) {
-                return routing.present(await routing.execCommandRemote(target.executionWorkspaceId, {
+                return routing.presentSemantic(await routing.execCommandRemote(target.executionWorkspaceId, {
                     cmd,
                     ...(tty !== undefined ? { tty } : {}),
                     ...(columns !== undefined ? { columns } : {}),
@@ -1065,7 +1207,7 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
                     ...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
                 }, routing.hostScopeIdFor(extra._meta, extra.sessionId)), target);
             }
-            return routing.present(await shellRun({
+            return routing.presentSemantic(await shellRun({
                 workspaceId: target.executionWorkspaceId,
                 command: cmd,
                 surface: "exec_command",
@@ -1192,6 +1334,9 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     const connectionScopeId = `mcp-connection:${randomUUID()}`;
     const remoteWorkspaces = new RemoteWorkspaceRelay(config.configDir, config.stateDir);
     const compositeWorkspaces = new CompositeWorkspaceRegistry(config.stateDir);
+    const workspaceTasks = new WorkspaceTaskStore(config.stateDir);
+    const taskReminders = new WorkspaceTaskReminderTracker(config.taskReminderInterval, workspaceTasks);
+    const compositeTaskGuides = loadCapabilityGuides(config).filter((guide) => guide.name === "workspace-tasks");
     const compositeActivity = new CompositeActivityCoordinator(compositeWorkspaces, activityQueries, remoteWorkspaces);
     const resolveExecutionTarget = (workspaceId, memberName) => {
         if (!compositeWorkspaces.has(workspaceId)) {
@@ -1224,6 +1369,25 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             : remapCompositeToolResult(result, target.executionWorkspaceId, target.compositeWorkspaceId, target.memberName);
         return subagentMcp.decorateResult(target.executionWorkspaceId, presented);
     };
+    const taskReminderWorkspaceIdFor = (target) => {
+        if (target.compositeWorkspaceId)
+            return target.compositeWorkspaceId;
+        if (remoteWorkspaces.has(target.executionWorkspaceId))
+            return undefined;
+        try {
+            return workspaces.getWorkspace(target.executionWorkspaceId).id;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const presentSemanticWorkResult = (result, target) => {
+        const presented = presentExecutionResult(result, target);
+        if (toolResultIsError(presented))
+            return presented;
+        const reminderWorkspaceId = taskReminderWorkspaceIdFor(target);
+        return attachWorkspaceTaskReminder(presented, reminderWorkspaceId ? taskReminders.recordWork(reminderWorkspaceId) : undefined);
+    };
     const hostScopeIdFor = (requestMeta, transportSessionId) => hostConversationScopeId(requestMeta, transportSessionId, connectionScopeId);
     const prepareExecutionContext = async (target, requestMeta, signal, sessionId) => {
         const conversationScopeId = hostScopeIdFor(requestMeta, sessionId);
@@ -1248,6 +1412,15 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     const capabilityRegistry = createCapabilityRegistry({
         inspectHooks: (workspaceRoot) => checkHookConfiguration(workspaceRoot, config.hooks),
         ...subagentMcp.registryDependencies,
+        workspaceTasks: {
+            available: true,
+            run: async (input, context) => {
+                const value = runWorkspaceTasksCapability(workspaceTasks, context.workspaceId, input);
+                if (input.operation !== "get")
+                    taskReminders.reset(context.workspaceId);
+                return { value };
+            },
+        },
         batchExecute: {
             available: batchExecuteAvailable,
             unavailableReason: batchExecuteAvailable
@@ -1270,7 +1443,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             run: async (input, context, options) => {
                 try {
                     return {
-                        value: await codeIntelligence.run(context.workspaceRoot, input, { signal: options.signal }),
+                        value: await codeIntelligence.run(requireCapabilityWorkspaceRoot(context), input, { signal: options.signal }),
                     };
                 }
                 catch (error) {
@@ -1289,7 +1462,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             run: async (context) => {
                 const review = await reviewWorkspaceChanges(reviewCheckpoints, {
                     id: context.workspaceId,
-                    root: context.workspaceRoot,
+                    root: requireCapabilityWorkspaceRoot(context),
                 });
                 return {
                     value: {
@@ -1317,7 +1490,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     const downloaded = await downloadIncomingArtifact({
                         registry: incomingArtifactRegistry,
                         workspaceId: context.workspaceId,
-                        workspaceRoot: context.workspaceRoot,
+                        workspaceRoot: requireCapabilityWorkspaceRoot(context),
                         maxFileBytes: config.artifactMaxFileBytes,
                         file: input.file,
                         path: input.path,
@@ -1979,9 +2152,9 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         description: "Open or resume a ForgeRelay Workspace. Ordinary workspaces default to local execution; relay may name a registered remote ForgeRelay. Composite Workspaces use the same open lifecycle but have kind=\"composite\" and a name instead of a mounted root. Reuse the returned workspaceId for later calls. Bootstrap context is delivered automatically only when needed and can be suppressed or refreshed.",
         inputSchema: {
             action: z
-                .enum(["open", "list", "member"])
+                .enum(["open", "list", "inspect", "member"])
                 .optional()
-                .describe("Defaults to open. Use list to inspect known Workspaces. Use member to add/remove a named execution member on an existing Composite Workspace."),
+                .describe("Defaults to open. Use list for lightweight inventory, inspect for bounded read-only metadata about one known Workspace without opening/resuming it, or member to change Composite membership."),
             memberAction: z
                 .enum(["add", "update", "remove"])
                 .optional()
@@ -2021,7 +2194,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             workspaceId: z
                 .string()
                 .optional()
-                .describe("For action=open, an existing Workspace ID to resume or reuse. Historical duplicate IDs from earlier ForgeRelay versions may resolve to the canonical Workspace ID. For action=list, filters inventory to one Workspace ID."),
+                .describe("For action=open, an existing Workspace ID to resume or reuse. Historical duplicate IDs from earlier ForgeRelay versions may resolve to the canonical Workspace ID. For action=list, filters inventory. For action=inspect, identifies the single Workspace to inspect without opening or binding it."),
             mode: z
                 .enum(["checkout", "worktree"])
                 .optional()
@@ -2073,7 +2246,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 .describe("For action=list, maximum records to return. Defaults to 50; maximum 100."),
         },
         outputSchema: {
-            action: z.enum(["open", "list", "member"]),
+            action: z.enum(["open", "list", "inspect", "member"]),
             workspaceId: z.string().optional(),
             memberAction: z.enum(["add", "update", "remove"]).optional(),
             kind: z.enum(["workspace", "composite"]).optional(),
@@ -2148,6 +2321,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             })).optional(),
             summary: workspaceInventorySummaryOutputSchema.optional(),
             page: workspaceInventoryPageOutputSchema.optional(),
+            inspection: workspaceInspectionOutputSchema.optional(),
             instruction: z.string(),
         },
         _meta: {},
@@ -2161,6 +2335,121 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         const startedAt = performance.now();
         const conversationScopeId = openAiConversationScopeId(_meta);
         const protectedWorkspaceIds = processSessions.activeWorkspaceIds();
+        const inspectTaskSummary = (targetWorkspaceId) => {
+            try {
+                const summary = workspaceTasks.inspectSummary(targetWorkspaceId);
+                if (!summary)
+                    return undefined;
+                const { fingerprint: _fingerprint, ...inspectionSummary } = summary;
+                return inspectionSummary;
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const inspectCompositeMember = async (entry) => {
+            if (remoteWorkspaces.has(entry.workspaceId)) {
+                const inspected = remoteWorkspaces.inspectWorkspace(entry.workspaceId);
+                return {
+                    name: entry.name,
+                    purpose: entry.purpose,
+                    workspaceId: entry.workspaceId,
+                    known: true,
+                    location: inspected.location,
+                    routeState: inspected.routeState,
+                    mode: inspected.mode,
+                };
+            }
+            try {
+                const inspected = await workspaces.inspectWorkspace(entry.workspaceId);
+                return {
+                    name: entry.name,
+                    purpose: entry.purpose,
+                    workspaceId: entry.workspaceId,
+                    known: true,
+                    location: inspected.location,
+                    state: inspected.state,
+                    status: inspected.status,
+                    mode: inspected.mode,
+                    rootValid: inspected.rootValid,
+                };
+            }
+            catch {
+                return {
+                    name: entry.name,
+                    purpose: entry.purpose,
+                    workspaceId: entry.workspaceId,
+                    known: false,
+                };
+            }
+        };
+        if (action === "inspect") {
+            if (!workspaceId) {
+                throw new Error("open_workspace action=inspect requires workspaceId.");
+            }
+            if (memberAction !== undefined || member !== undefined || kind !== undefined || name !== undefined ||
+                memberName !== undefined || path !== undefined || relay !== undefined || mode !== undefined ||
+                baseRef !== undefined || newWorktree !== undefined || newWorkspace !== undefined || context !== undefined ||
+                root !== undefined || status !== undefined || state !== undefined || staleOnly !== undefined ||
+                offset !== undefined || limit !== undefined) {
+                throw new Error("open_workspace action=inspect accepts only workspaceId. It never opens, resumes, binds, or mutates the inspected Workspace.");
+            }
+            let inspection;
+            if (compositeWorkspaces.has(workspaceId)) {
+                const composite = compositeWorkspaces.get(workspaceId);
+                const members = await Promise.all(composite.members.map(inspectCompositeMember));
+                const taskSummary = inspectTaskSummary(composite.id);
+                inspection = {
+                    workspaceId: composite.id,
+                    kind: "composite",
+                    name: composite.name,
+                    status: composite.status,
+                    state: composite.status,
+                    createdAt: composite.createdAt,
+                    lastUsedAt: composite.lastUsedAt,
+                    members,
+                    ...(taskSummary ? { taskSummary } : {}),
+                };
+            }
+            else if (remoteWorkspaces.has(workspaceId)) {
+                inspection = remoteWorkspaces.inspectWorkspace(workspaceId);
+            }
+            else {
+                const inspected = await workspaces.inspectWorkspace(workspaceId);
+                const taskSummary = inspectTaskSummary(inspected.workspaceId);
+                inspection = {
+                    ...inspected,
+                    ...(taskSummary ? { taskSummary } : {}),
+                };
+            }
+            const instruction = "This is a bounded read-only Workspace inspection. It does not open/resume the target, deliver bootstrap context, bind this conversation, or grant file/process/Git/Capability authority. Explicitly open the Workspace before modifying or executing against it.";
+            const result = [
+                `Inspected Workspace ${inspection.workspaceId} (${inspection.kind}).`,
+                inspection.kind === "composite"
+                    ? `State: ${inspection.state}; members=${inspection.members.length}.`
+                    : inspection.location === "relay"
+                        ? `Route: ${inspection.routeState}; mode=${inspection.mode}; location=${inspection.location}. Remote lifecycle is not probed by inspection.`
+                        : `State: ${inspection.state}; mode=${inspection.mode}; location=${inspection.location}.`,
+                "Task summary is included only when durable local Task state already exists; Task bodies are never returned.",
+                instruction,
+            ].join("\n");
+            logToolCall(config, {
+                tool: "open_workspace",
+                action: "inspect",
+                success: true,
+                durationMs: Math.round(performance.now() - startedAt),
+            });
+            return {
+                content: [textBlock(result)],
+                structuredContent: {
+                    action: "inspect",
+                    workspaceId: inspection.workspaceId,
+                    kind: inspection.kind,
+                    inspection,
+                    instruction,
+                },
+            };
+        }
         if (action === "member") {
             if (!workspaceId || !compositeWorkspaces.has(workspaceId)) {
                 throw new Error("open_workspace action=member requires an existing Composite Workspace workspaceId.");
@@ -2398,6 +2687,15 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             const composite = workspaceId !== undefined
                 ? compositeWorkspaces.open(workspaceId)
                 : compositeWorkspaces.create(name ?? "");
+            workspaceTasks.initializeWorkspace(composite.id);
+            const compositeTaskContext = compositeCapabilityContext(composite.id, compositeTaskGuides);
+            const compositeCapabilityCatalog = capabilityRegistry.catalog(compositeTaskContext);
+            const compositeCapabilityGuides = compositeTaskGuides.map((guide) => ({
+                name: guide.name,
+                description: guide.description,
+                whenToRead: guide.whenToRead,
+                path: formatPathForPrompt(guide.filePath),
+            }));
             const memberContext = memberName
                 ? await loadCompositeMemberContext(composite.id, memberName, context ?? "auto", conversationScopeId, protectedWorkspaceIds)
                 : undefined;
@@ -2408,6 +2706,9 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     ? `Members: ${composite.members.map((member) => `${member.name} — ${member.purpose}`).join("; ")}.`
                     : "This Composite Workspace currently has no members.",
                 "Member names and purposes are structural context and are always returned when this Composite Workspace is opened. context=auto/full/none controls only heavy member bootstrap context, not this Composite identity.",
+                compositeCapabilityCatalog.length > 0
+                    ? `Composite-owned capabilities: ${compositeCapabilityCatalog.map((entry) => entry.name).join(", ")}. Use these without member because their state belongs to the Composite Workspace itself.`
+                    : undefined,
                 composite.members.length > 0
                     ? "Before first work on a member, reopen this Composite Workspace with memberName=<member> and context=auto to receive that member's project bootstrap without creating an implicit current member."
                     : undefined,
@@ -2435,6 +2736,8 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     status: composite.status,
                     state: composite.status,
                     members: composite.members,
+                    capabilityCatalog: compositeCapabilityCatalog,
+                    capabilityGuides: compositeCapabilityGuides,
                     ...(memberContext ? { memberContext } : {}),
                     instruction,
                 },
@@ -2547,6 +2850,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             conversationScopeId,
             protectedWorkspaceIds,
         });
+        workspaceTasks.initializeWorkspace(workspace.id);
         const knownWorktrees = await workspaces.listKnownWorktrees(workspace);
         const staleWorkspaces = await workspaces.listStaleWorkspaces(workspace);
         const capabilityFingerprint = buildCapabilityFingerprint(config, FORGERELAY_VERSION, {
@@ -2598,7 +2902,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         const loadedAgentsFiles = includeBootstrapContext ? cardAgentsFiles : [];
         const availableAgentsFileOutputs = includeBootstrapContext ? cardAvailableAgentsFiles : [];
         const workspaceContextInstruction = "For later open_workspace calls, context=\"auto\" avoids repeating unchanged bootstrap context; use context=\"none\" when only the workspace handle/metadata is needed, or context=\"full\" to force a refresh.";
-        const workspaceManagementInstruction = "When you need to inspect known Workspaces, continue earlier work, or organize Workspace state, use open_workspace(action=\"list\") to inspect candidates, then resume a selected workspaceId or ask the user before close_workspace cleanup.";
+        const workspaceManagementInstruction = "Use open_workspace(action=\"list\") for lightweight Workspace inventory. Use action=\"inspect\" with one known workspaceId for bounded read-only metadata without opening/resuming it. Explicitly open a Workspace before executing or mutating against it, and ask the user before close_workspace cleanup.";
         const cardInstruction = config.skillsEnabled
             ? `Use this workspaceId in all subsequent tool calls for this project. Follow loaded agentsFiles instructions. Read an availableAgentsFiles path before working under it. When a task matches an available skill, load it with read(path=\"skills://<name>\") before proceeding. When a task matches a capability guide, read its advertised path before proceeding. ${workspaceContextInstruction} ${workspaceManagementInstruction}`
             : `Use this workspaceId in all subsequent tool calls for this project. Follow loaded agentsFiles instructions. Read an availableAgentsFiles path before working under it. When a task matches a capability guide, read its advertised path before proceeding. ${workspaceContextInstruction} ${workspaceManagementInstruction}`;
@@ -2808,16 +3112,87 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             openWorldHint: true,
         },
     }, async ({ workspaceId, member, name, action, arguments: capabilityArguments, file }, extra) => {
+        if (name === "workspace.tasks" && compositeWorkspaces.has(workspaceId)) {
+            if (member !== undefined) {
+                throw new Error(`workspace.tasks belongs to Composite Workspace ${workspaceId} itself and does not accept member.`);
+            }
+            if (!compositeWorkspaces.isActive(workspaceId)) {
+                throw new Error(`Composite Workspace ${workspaceId} is closed. Reopen it with open_workspace before use.`);
+            }
+            const startedAt = performance.now();
+            const context = compositeCapabilityContext(workspaceId, compositeTaskGuides);
+            try {
+                if (action === "run") {
+                    const execution = await capabilityRegistry.run(name, capabilityArguments ?? {}, context, {
+                        nativeFile: file,
+                        signal: extra.signal,
+                        requestMeta: extra._meta,
+                        sessionId: extra.sessionId,
+                    });
+                    const result = {
+                        content: [textBlock(`Capability ${name} completed.\n${JSON.stringify(execution.value, null, 2)}`)],
+                        structuredContent: { name, action, result: execution.value },
+                    };
+                    logToolCall(config, {
+                        tool: toolNames.capability,
+                        capability: name,
+                        action,
+                        success: true,
+                        durationMs: Math.round(performance.now() - startedAt),
+                    });
+                    return result;
+                }
+                const capability = capabilityRegistry.describe(name, context);
+                const result = {
+                    content: [textBlock([
+                            `${capability.name}: ${capability.description}`,
+                            `Available: ${capability.available}`,
+                            `Guide: ${capability.guide.path}`,
+                            capability.guide.readBeforeFirstUse
+                                ? "Read the guide before first use when this contract is unfamiliar."
+                                : undefined,
+                        ].filter(Boolean).join("\n"))],
+                    structuredContent: { name, action, capability },
+                };
+                logToolCall(config, {
+                    tool: toolNames.capability,
+                    capability: name,
+                    action,
+                    success: true,
+                    durationMs: Math.round(performance.now() - startedAt),
+                });
+                return result;
+            }
+            catch (error) {
+                if (extra.signal.aborted)
+                    throw error;
+                const capabilityError = error instanceof CapabilityError
+                    ? error
+                    : new CapabilityError("execution_failed", error instanceof Error ? error.message : String(error));
+                return {
+                    content: [textBlock(`${capabilityError.code}: ${capabilityError.message}`)],
+                    structuredContent: {
+                        name,
+                        action,
+                        error: { code: capabilityError.code, message: capabilityError.message },
+                    },
+                    isError: true,
+                };
+            }
+        }
         const target = resolveExecutionTarget(workspaceId, member);
         const executionWorkspaceId = target.executionWorkspaceId;
         const executionContext = await prepareExecutionContext(target, extra._meta, extra.signal, extra.sessionId);
         if (remoteWorkspaces.has(executionWorkspaceId)) {
-            return presentExecutionResult(await remoteWorkspaces.capability(executionWorkspaceId, {
+            const response = await remoteWorkspaces.capability(executionWorkspaceId, {
                 name,
                 action,
                 ...(capabilityArguments !== undefined ? { arguments: capabilityArguments } : {}),
                 ...(file !== undefined ? { file } : {}),
-            }, hostScopeIdFor(extra._meta, extra.sessionId)), target);
+            }, hostScopeIdFor(extra._meta, extra.sessionId));
+            return action === "run" && name !== "workspace.tasks"
+                ? presentSemanticWorkResult(response, target)
+                : presentExecutionResult(response, target);
         }
         if (action === "run" && name === "batch.execute") {
             const workspace = workspaces.getWorkspace(executionWorkspaceId);
@@ -2841,7 +3216,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     success: true,
                     durationMs: Math.round(performance.now() - startedAt),
                 });
-                return presentExecutionResult(result, target);
+                return presentSemanticWorkResult(result, target);
             }
             catch (error) {
                 if (extra.signal.aborted)
@@ -2868,7 +3243,10 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             }
         }
         if (action === "run") {
-            return presentExecutionResult(await coreOperations.capabilityRun({ workspaceId: executionWorkspaceId, name, arguments: capabilityArguments, file }, executionContext), target);
+            const response = await coreOperations.capabilityRun({ workspaceId: executionWorkspaceId, name, arguments: capabilityArguments, file }, executionContext);
+            return name === "workspace.tasks"
+                ? presentExecutionResult(response, target)
+                : presentSemanticWorkResult(response, target);
         }
         const workspace = workspaces.getWorkspace(executionWorkspaceId);
         return runActivityToolWithHooks(activityLifecycle, hooks, workspace, hostScopeIdFor(extra._meta, extra.sessionId), activityRequestFor({ workspaceId: executionWorkspaceId, name, action, arguments: capabilityArguments, file }, executionContext), {
@@ -2972,6 +3350,10 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             const composite = action === "delete"
                 ? compositeWorkspaces.dissolve(workspaceId)
                 : compositeWorkspaces.close(workspaceId);
+            if (action === "delete") {
+                workspaceTasks.deleteWorkspace(workspaceId);
+                taskReminders.forget(workspaceId);
+            }
             compositeActivity.forgetComposite(workspaceId);
             workspacePanelStates.delete(workspaceId);
             const result = [
@@ -3038,6 +3420,8 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 payload: { workspaceId: session.id, action: "delete", mode: session.mode },
                 operation: async () => {
                     workspaces.deleteWorkspace(session.id);
+                    workspaceTasks.deleteWorkspace(session.id);
+                    taskReminders.forget(session.id);
                     await reviewCheckpoints.releaseWorkspace(session.id);
                     const result = `Deleted ForgeRelay Workspace ${session.id}. Physical project files were not removed.`;
                     return {
@@ -3080,6 +3464,8 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 payload: { workspaceId: session.id, action: "delete", mode: session.mode },
                 operation: async () => {
                     workspaces.deleteWorkspace(session.id);
+                    workspaceTasks.deleteWorkspace(session.id);
+                    taskReminders.forget(session.id);
                     await reviewCheckpoints.releaseWorkspace(session.id);
                     const result = `Deleted closed managed-worktree Workspace ${session.id}. Its already-removed worktree backing was not recreated.`;
                     return {
@@ -3142,6 +3528,8 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     await Promise.all(physicalWorkspaceIds.map((id) => reviewCheckpoints.releaseWorkspace(id)));
                     if (action === "delete") {
                         workspaces.deleteWorkspace(workspace.id);
+                        workspaceTasks.deleteWorkspace(workspace.id);
+                        taskReminders.forget(workspace.id);
                     }
                     const result = [
                         action === "delete"
@@ -3237,7 +3625,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             member: z
                 .string()
                 .optional()
-                .describe("Required for a Composite Workspace; explicit member name that owns this operation."),
+                .describe("Required for Composite member-scoped file reads. Omit only when reading an advertised Composite-owned capability guide."),
             path: z
                 .string()
                 .optional()
@@ -3279,14 +3667,37 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         if ((path === undefined) === (paths === undefined)) {
             throw new Error("read requires exactly one of path or paths.");
         }
+        if (compositeWorkspaces.has(workspaceId) && member === undefined && path !== undefined) {
+            const guide = compositeTaskGuides.find((candidate) => formatPathForPrompt(candidate.filePath) === path || candidate.filePath === path);
+            if (guide) {
+                if (!compositeWorkspaces.isActive(workspaceId)) {
+                    throw new Error(`Composite Workspace ${workspaceId} is closed. Reopen it with open_workspace before use.`);
+                }
+                const startedAt = performance.now();
+                const raw = readFileSync(guide.filePath, "utf8");
+                const start = (offset ?? 1) - 1;
+                const end = limit === undefined ? undefined : start + limit;
+                const result = raw.split("\n").slice(start, end).join("\n");
+                logToolCall(config, {
+                    tool: toolNames.read,
+                    path: formatPathForPrompt(guide.filePath),
+                    success: true,
+                    durationMs: Math.round(performance.now() - startedAt),
+                });
+                return {
+                    content: [textBlock(result)],
+                    structuredContent: { result },
+                };
+            }
+        }
         const target = resolveExecutionTarget(workspaceId, member);
         const executionWorkspaceId = target.executionWorkspaceId;
         const executionContext = await prepareExecutionContext(target, extra._meta, extra.signal, extra.sessionId);
         if (remoteWorkspaces.has(executionWorkspaceId)) {
-            return presentExecutionResult(await remoteWorkspaces.read(executionWorkspaceId, { path, paths, offset, limit }, hostScopeIdFor(extra._meta, extra.sessionId)), target);
+            return presentSemanticWorkResult(await remoteWorkspaces.read(executionWorkspaceId, { path, paths, offset, limit }, hostScopeIdFor(extra._meta, extra.sessionId)), target);
         }
         if (path !== undefined) {
-            return presentExecutionResult(await coreOperations.read({ workspaceId: executionWorkspaceId, path, offset, limit }, executionContext), target);
+            return presentSemanticWorkResult(await coreOperations.read({ workspaceId: executionWorkspaceId, path, offset, limit }, executionContext), target);
         }
         const workspace = workspaces.getWorkspace(executionWorkspaceId);
         let response;
@@ -3339,7 +3750,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             : { type: "succeeded" }, activityRelationFor(executionContext));
         if (!response)
             throw new Error("Bulk Read completed without a response.");
-        return presentExecutionResult(response, target);
+        return presentSemanticWorkResult(response, target);
     });
     if (config.toolMode !== "codex") {
         registerAppTool(server, toolNames.write, {
@@ -3363,9 +3774,9 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             const executionWorkspaceId = target.executionWorkspaceId;
             const executionContext = await prepareExecutionContext(target, extra._meta, extra.signal, extra.sessionId);
             if (remoteWorkspaces.has(executionWorkspaceId)) {
-                return presentExecutionResult(await remoteWorkspaces.write(executionWorkspaceId, input, hostScopeIdFor(extra._meta, extra.sessionId)), target);
+                return presentSemanticWorkResult(await remoteWorkspaces.write(executionWorkspaceId, input, hostScopeIdFor(extra._meta, extra.sessionId)), target);
             }
-            return presentExecutionResult(await coreOperations.write({ workspaceId: executionWorkspaceId, ...input }, executionContext), target);
+            return presentSemanticWorkResult(await coreOperations.write({ workspaceId: executionWorkspaceId, ...input }, executionContext), target);
         });
         registerAppTool(server, toolNames.edit, {
             title: "Edit file",
@@ -3416,12 +3827,12 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             const executionWorkspaceId = target.executionWorkspaceId;
             const executionContext = await prepareExecutionContext(target, extra._meta, extra.signal, extra.sessionId);
             if (remoteWorkspaces.has(executionWorkspaceId)) {
-                return presentExecutionResult(await remoteWorkspaces.edit(executionWorkspaceId, { path, paths, edits }, hostScopeIdFor(extra._meta, extra.sessionId)), target);
+                return presentSemanticWorkResult(await remoteWorkspaces.edit(executionWorkspaceId, { path, paths, edits }, hostScopeIdFor(extra._meta, extra.sessionId)), target);
             }
             if (path !== undefined) {
-                return presentExecutionResult(await coreOperations.edit({ workspaceId: executionWorkspaceId, path, edits }, executionContext), target);
+                return presentSemanticWorkResult(await coreOperations.edit({ workspaceId: executionWorkspaceId, path, edits }, executionContext), target);
             }
-            return presentExecutionResult(await nativeBulkMutations.edit({ workspaceId: executionWorkspaceId, paths: paths, edits }, executionContext), target);
+            return presentSemanticWorkResult(await nativeBulkMutations.edit({ workspaceId: executionWorkspaceId, paths: paths, edits }, executionContext), target);
         });
     }
     registerAppTool(server, toolNames.rename, {
@@ -3445,9 +3856,9 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         const executionWorkspaceId = target.executionWorkspaceId;
         const executionContext = await prepareExecutionContext(target, extra._meta, extra.signal, extra.sessionId);
         if (remoteWorkspaces.has(executionWorkspaceId)) {
-            return presentExecutionResult(await remoteWorkspaces.rename(executionWorkspaceId, { path, newPath }, hostScopeIdFor(extra._meta, extra.sessionId)), target);
+            return presentSemanticWorkResult(await remoteWorkspaces.rename(executionWorkspaceId, { path, newPath }, hostScopeIdFor(extra._meta, extra.sessionId)), target);
         }
-        return presentExecutionResult(await coreOperations.rename({ workspaceId: executionWorkspaceId, path, newPath }, executionContext), target);
+        return presentSemanticWorkResult(await coreOperations.rename({ workspaceId: executionWorkspaceId, path, newPath }, executionContext), target);
     });
     registerAppTool(server, toolNames.delete, {
         title: "Delete path",
@@ -3488,12 +3899,12 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         const executionWorkspaceId = target.executionWorkspaceId;
         const executionContext = await prepareExecutionContext(target, extra._meta, extra.signal, extra.sessionId);
         if (remoteWorkspaces.has(executionWorkspaceId)) {
-            return presentExecutionResult(await remoteWorkspaces.delete(executionWorkspaceId, { path, paths, recursive }, hostScopeIdFor(extra._meta, extra.sessionId)), target);
+            return presentSemanticWorkResult(await remoteWorkspaces.delete(executionWorkspaceId, { path, paths, recursive }, hostScopeIdFor(extra._meta, extra.sessionId)), target);
         }
         if (path !== undefined) {
-            return presentExecutionResult(await coreOperations.delete({ workspaceId: executionWorkspaceId, path, recursive }, executionContext), target);
+            return presentSemanticWorkResult(await coreOperations.delete({ workspaceId: executionWorkspaceId, path, recursive }, executionContext), target);
         }
-        return presentExecutionResult(await nativeBulkMutations.delete({ workspaceId: executionWorkspaceId, paths: paths, recursive }, executionContext), target);
+        return presentSemanticWorkResult(await nativeBulkMutations.delete({ workspaceId: executionWorkspaceId, paths: paths, recursive }, executionContext), target);
     });
     if (config.toolMode === "codex") {
         registerAppTool(server, "apply_patch", {
@@ -3524,7 +3935,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             const executionWorkspaceId = target.executionWorkspaceId;
             const executionContext = await prepareExecutionContext(target, extra._meta, extra.signal, extra.sessionId);
             if (remoteWorkspaces.has(executionWorkspaceId)) {
-                return presentExecutionResult(await remoteWorkspaces.applyPatch(executionWorkspaceId, { patch }, hostScopeIdFor(extra._meta, extra.sessionId)), target);
+                return presentSemanticWorkResult(await remoteWorkspaces.applyPatch(executionWorkspaceId, { patch }, hostScopeIdFor(extra._meta, extra.sessionId)), target);
             }
             const workspace = workspaces.getWorkspace(executionWorkspaceId);
             return runActivityToolWithHooks(activityLifecycle, hooks, workspace, hostScopeIdFor(extra._meta, extra.sessionId), activityRequestFor({ workspaceId: executionWorkspaceId, patch }, executionContext), {
@@ -3574,7 +3985,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                         },
                     };
                 },
-            }, activityRelationFor(executionContext)).then((result) => presentExecutionResult(result, target));
+            }, activityRelationFor(executionContext)).then((result) => presentSemanticWorkResult(result, target));
         });
     }
     if (config.toolMode !== "codex") {
@@ -3664,7 +4075,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             const executionWorkspaceId = target.executionWorkspaceId;
             const executionContext = await prepareExecutionContext(target, extra._meta, extra.signal, extra.sessionId);
             if (remoteWorkspaces.has(executionWorkspaceId)) {
-                return presentExecutionResult(await remoteWorkspaces.bash(executionWorkspaceId, {
+                const response = await remoteWorkspaces.bash(executionWorkspaceId, {
                     action,
                     ...(command !== undefined ? { command } : {}),
                     ...(processId !== undefined ? { processId } : {}),
@@ -3678,7 +4089,10 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     ...(yieldTimeMs !== undefined ? { yieldTimeMs } : {}),
                     ...(timeoutMs !== undefined ? { timeoutMs } : {}),
                     ...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
-                }, hostScopeIdFor(extra._meta, extra.sessionId)), target);
+                }, hostScopeIdFor(extra._meta, extra.sessionId));
+                return action === "run"
+                    ? presentSemanticWorkResult(response, target)
+                    : presentExecutionResult(response, target);
             }
             const workspace = workspaces.getWorkspace(executionWorkspaceId);
             if (action === "run") {
@@ -3687,7 +4101,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 if (processId !== undefined || outputId !== undefined || input !== undefined || interrupt !== undefined) {
                     throw new Error("bash action=run does not accept processId, outputId, input, or interrupt.");
                 }
-                return presentExecutionResult(await coreOperations.shellRun({
+                return presentSemanticWorkResult(await coreOperations.shellRun({
                     workspaceId: executionWorkspaceId,
                     command,
                     surface: "bash",
@@ -3781,6 +4195,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         resolve: resolveExecutionTarget,
         prepare: prepareExecutionContext,
         present: presentExecutionResult,
+        presentSemantic: presentSemanticWorkResult,
         isRemote: (workspaceId) => remoteWorkspaces.has(workspaceId),
         execCommandRemote: (workspaceId, input, conversationScopeId) => remoteWorkspaces.execCommand(workspaceId, input, conversationScopeId),
         writeStdinRemote: (workspaceId, input, conversationScopeId) => remoteWorkspaces.writeStdin(workspaceId, input, conversationScopeId),