@akira-tl/forgerelay 0.8.3 → 0.8.4

package/dist/server.js

@@ -53,6 +53,7 @@ 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";
@@ -259,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(),
@@ -345,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 {
@@ -853,33 +933,43 @@ function requireCapabilityWorkspaceRoot(context) {
 function runWorkspaceTasksCapability(store, workspaceId, input) {
     switch (input.operation) {
         case "get":
-            return store.read(workspaceId);
+            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":
-            return store.createList(workspaceId, { name: input.name, position: input.position });
+            store.createList(workspaceId, { name: input.name, position: input.position });
+            return store.readSummary(workspaceId);
         case "list.update":
-            return store.updateList(workspaceId, input.listId, {
+            store.updateList(workspaceId, input.listId, {
                 name: input.name,
                 state: input.state,
                 position: input.position,
             });
+            return store.readSummary(workspaceId);
         case "list.delete":
-            return store.deleteList(workspaceId, input.listId);
+            store.deleteList(workspaceId, input.listId);
+            return store.readSummary(workspaceId);
         case "task.create":
-            return store.createTask(workspaceId, input.listId, {
+            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":
-            return store.updateTask(workspaceId, input.listId, input.taskId, {
+            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":
-            return store.deleteTask(workspaceId, input.listId, input.taskId);
+            store.deleteTask(workspaceId, input.listId, input.taskId);
+            return store.readHeaders(workspaceId, input.listId);
     }
 }
 async function reviewWorkspaceChanges(reviewCheckpoints, workspace) {
@@ -1106,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 } : {}),
@@ -1117,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",
@@ -1245,6 +1335,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     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) => {
@@ -1278,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);
@@ -1304,9 +1414,12 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         ...subagentMcp.registryDependencies,
         workspaceTasks: {
             available: true,
-            run: async (input, context) => ({
-                value: runWorkspaceTasksCapability(workspaceTasks, context.workspaceId, input),
-            }),
+            run: async (input, context) => {
+                const value = runWorkspaceTasksCapability(workspaceTasks, context.workspaceId, input);
+                if (input.operation !== "get")
+                    taskReminders.reset(context.workspaceId);
+                return { value };
+            },
         },
         batchExecute: {
             available: batchExecuteAvailable,
@@ -2039,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()
@@ -2081,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()
@@ -2133,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(),
@@ -2208,6 +2321,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             })).optional(),
             summary: workspaceInventorySummaryOutputSchema.optional(),
             page: workspaceInventoryPageOutputSchema.optional(),
+            inspection: workspaceInspectionOutputSchema.optional(),
             instruction: z.string(),
         },
         _meta: {},
@@ -2221,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.");
@@ -2673,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}`;
@@ -2955,12 +3184,15 @@ 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.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);
@@ -2984,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)
@@ -3011,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), {
@@ -3115,8 +3350,10 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             const composite = action === "delete"
                 ? compositeWorkspaces.dissolve(workspaceId)
                 : compositeWorkspaces.close(workspaceId);
-            if (action === "delete")
+            if (action === "delete") {
                 workspaceTasks.deleteWorkspace(workspaceId);
+                taskReminders.forget(workspaceId);
+            }
             compositeActivity.forgetComposite(workspaceId);
             workspacePanelStates.delete(workspaceId);
             const result = [
@@ -3184,6 +3421,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 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 {
@@ -3227,6 +3465,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 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 {
@@ -3290,6 +3529,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     if (action === "delete") {
                         workspaces.deleteWorkspace(workspace.id);
                         workspaceTasks.deleteWorkspace(workspace.id);
+                        taskReminders.forget(workspace.id);
                     }
                     const result = [
                         action === "delete"
@@ -3454,10 +3694,10 @@ 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.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;
@@ -3510,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, {
@@ -3534,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",
@@ -3587,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, {
@@ -3616,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",
@@ -3659,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", {
@@ -3695,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), {
@@ -3745,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") {
@@ -3835,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 } : {}),
@@ -3849,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") {
@@ -3858,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",
@@ -3952,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),

package/dist/workspace-task-reminders.js

@@ -0,0 +1,42 @@
+const TASK_REMINDER = "Reminder: this Workspace has unfinished active Tasks. Review workspace.tasks and update Task state when material progress, requirements, blockers, or conclusions changed.";
+export class WorkspaceTaskReminderTracker {
+    interval;
+    tasks;
+    callsSinceUpdate = new Map();
+    constructor(interval, tasks) {
+        this.interval = interval;
+        this.tasks = tasks;
+    }
+    reset(workspaceId) {
+        this.callsSinceUpdate.delete(workspaceId);
+    }
+    forget(workspaceId) {
+        this.callsSinceUpdate.delete(workspaceId);
+    }
+    recordWork(workspaceId) {
+        if (this.interval === 0)
+            return undefined;
+        let summary;
+        try {
+            summary = this.tasks.readSummary(workspaceId);
+        }
+        catch {
+            // Reminder delivery is advisory. Invalid external Task state must still be
+            // surfaced by workspace.tasks itself, not turn unrelated work into failure.
+            this.callsSinceUpdate.delete(workspaceId);
+            return undefined;
+        }
+        const hasUnfinishedActiveTasks = summary.lists.some((list) => list.state === "active" && list.unfinishedTaskCount > 0);
+        if (!hasUnfinishedActiveTasks) {
+            this.callsSinceUpdate.delete(workspaceId);
+            return undefined;
+        }
+        const next = (this.callsSinceUpdate.get(workspaceId) ?? 0) + 1;
+        if (next < this.interval) {
+            this.callsSinceUpdate.set(workspaceId, next);
+            return undefined;
+        }
+        this.callsSinceUpdate.set(workspaceId, 0);
+        return TASK_REMINDER;
+    }
+}