@borgee/agents-host 0.2.74 → 0.2.84

package/dist/chat/sdk-chat-control-plane.d.ts

@@ -1,7 +1,7 @@
-import { type BorgeePluginClient, type BorgeePluginOptions, type InboundMessageEvent, type ReportTurnActivityInput, type StopTurnHandler, type TurnActivityReporter } from '../plugin-sdk.js';
+import { type BorgeePluginClient, type BorgeePluginOptions, type InboundMessageEvent, type ReportTurnActivityInput, type StopTurnHandler, type StopBackgroundRunHandler, type TurnActivityReporter } from '../plugin-sdk.js';
 import type { ChannelSummary, ChannelHistoryEntry, ChannelMessageEvent, CreateTaskInput, DirectoryUser, MeResponseUser, PostMessageInput, PostedMessage, ReadChannelHistoryInput, Task, UpdateTaskInput } from '../types.js';
 import type { ChatControlPlane } from './chat-control-plane.js';
-type PluginClientLike = Pick<BorgeePluginClient, 'agentId' | 'close' | 'connect' | 'createTask' | 'deleteMessage' | 'editMessage' | 'getMe' | 'getTask' | 'listChannels' | 'listTasks' | 'listUsers' | 'on' | 'onStopTurn' | 'readHistory' | 'reportTurnActivity' | 'sendMessage' | 'startTyping' | 'updateTask' | 'setTaskProperty' | 'deleteTaskProperty'>;
+type PluginClientLike = Pick<BorgeePluginClient, 'agentId' | 'close' | 'connect' | 'createTask' | 'deleteMessage' | 'editMessage' | 'getMe' | 'getTask' | 'listChannels' | 'listTasks' | 'listUsers' | 'on' | 'onStopTurn' | 'onStopBackgroundRun' | 'reportActivity' | 'readHistory' | 'reportTurnActivity' | 'sendMessage' | 'startTyping' | 'updateTask' | 'setTaskProperty' | 'deleteTaskProperty'>;
 type PluginClientFactory = (options: BorgeePluginOptions) => PluginClientLike;
 type SdkChatControlPlaneOptions = Pick<BorgeePluginOptions, 'pluginId'>;
 /**
@@ -17,9 +17,11 @@ export declare class SdkChatControlPlane implements ChatControlPlane {
     private me;
     constructor(baseUrl: string, apiKey: string, createClient?: PluginClientFactory, options?: SdkChatControlPlaneOptions);
     onStopTurn(handler: StopTurnHandler | undefined): void;
+    onStopBackgroundRun(handler: StopBackgroundRunHandler | undefined): void;
     connect(onMessage: (message: ChannelMessageEvent) => void): Promise<void>;
     close(): Promise<void>;
     postMessage(input: PostMessageInput): Promise<PostedMessage>;
+    reportActivity(input: Parameters<BorgeePluginClient['reportActivity']>[0]): void;
     editMessage(messageId: string, content: string): Promise<void>;
     deleteMessage(messageId: string): Promise<void>;
     startTyping(channelId: string): () => void;

package/dist/chat/sdk-chat-control-plane.js

@@ -17,6 +17,9 @@ export class SdkChatControlPlane {
     onStopTurn(handler) {
         this.client.onStopTurn(handler);
     }
+    onStopBackgroundRun(handler) {
+        this.client.onStopBackgroundRun?.(handler);
+    }
     async connect(onMessage) {
         this.unsubscribe = this.client.on('message', (event) => {
             const message = mapInboundToChannelMessage(event);
@@ -50,6 +53,7 @@ export class SdkChatControlPlane {
         this.unsubscribe?.();
         this.unsubscribe = null;
         this.client.onStopTurn(undefined);
+        this.client.onStopBackgroundRun?.(undefined);
         await this.client.close();
     }
     async postMessage(input) {
@@ -60,6 +64,9 @@ export class SdkChatControlPlane {
         });
         return { messageId: sent.messageId };
     }
+    reportActivity(input) {
+        this.client.reportActivity(input);
+    }
     async editMessage(messageId, content) {
         await this.client.editMessage({ messageId, body: content });
     }

package/dist/context/claude-file-brief.js

@@ -1,6 +1,6 @@
 import { buildCollaborationCapabilityDeclarationSummaryLines, } from './collaboration-capabilities-diagnostics.js';
 import { MAIN_SESSION_DELEGATION_LINES } from './main-session-delegation.js';
-import { buildResolvedWorkspaceGuidanceLines } from './resolved-workspace.js';
+import { buildResolvedWorkingFolderGuidanceLines } from './resolved-working-folder.js';
 import { buildSkillManualLines, buildSkillManualReadLine } from './skill-manual.js';
 import { PARENT_CHANNEL_TASK_BOUNDARY_LINES } from './task-channel-boundary.js';
 function buildStableSkillLines(context) {
@@ -60,8 +60,8 @@ export function buildClaudeFileBrief(context) {
         '',
         ...sessionDelegationLines,
         ...(() => {
-            const workspaceLines = buildResolvedWorkspaceGuidanceLines(context);
-            return workspaceLines.length > 0 ? ['', ...workspaceLines] : [];
+            const workingFolderLines = buildResolvedWorkingFolderGuidanceLines(context);
+            return workingFolderLines.length > 0 ? ['', ...workingFolderLines] : [];
         })(),
         ...(() => {
             const capabilityLines = buildCollaborationCapabilityDeclarationSummaryLines(context?.collaborationCapabilities);

package/dist/context/injection.d.ts

@@ -1,5 +1,5 @@
 import type { ChatControlPlane } from '../chat/chat-control-plane.js';
-import type { AttentionSnapshot, ProjectionStrategy, CollaborationCapabilityDeclaration, CollaborationOutcomeSnapshot, CompactionSnapshot, LocalhostGatewayBootstrapMetadata, MissedCollaborationDiagnostic, ProviderKind, ProviderCollaborationContext, ResolvedWorkspaceContext, RuntimeSurface, SkillRuntimeBootstrapMetadata, TaskThreadCollaborationContract, TaskAssignmentThreadContext } from '../types.js';
+import type { AttentionSnapshot, ProjectionStrategy, CollaborationCapabilityDeclaration, CollaborationOutcomeSnapshot, CompactionSnapshot, LocalhostGatewayBootstrapMetadata, MissedCollaborationDiagnostic, ProviderKind, ProviderCollaborationContext, ResolvedWorkingFolderContext, RuntimeSurface, SkillRuntimeBootstrapMetadata, TaskThreadCollaborationContract, TaskAssignmentThreadContext } from '../types.js';
 export interface SkillRuntimeBootstrapPayload {
     skillDirectoryPath: string;
     nodeCliPath: string;
@@ -18,7 +18,13 @@ export interface ChannelContextPayload {
     skillRuntime?: SkillRuntimeBootstrapPayload;
     localhostGateway?: LocalhostGatewayBootstrapMetadata;
     taskAssignmentContext?: TaskAssignmentThreadContext;
-    resolvedWorkspace?: ResolvedWorkspaceContext;
+    /**
+     * Serialized into `context.json` and echoed by the gateway bootstrap response, so the key name is
+     * observable outside this process: `cleanup --purge` reads payloads written by whichever version
+     * happened to run last, and a payload whose key it does not recognize is skipped, silently leaving
+     * the directory it names on disk.
+     */
+    resolvedWorkspace?: ResolvedWorkingFolderContext;
 }
 export interface PreparedChannelContext {
     directoryPath: string;
@@ -29,7 +35,7 @@ export interface PreparedChannelContext {
     gatewayCredentialPath?: string;
     skillRuntime?: SkillRuntimeBootstrapMetadata;
     localhostGateway?: LocalhostGatewayBootstrapMetadata;
-    resolvedWorkspace?: ResolvedWorkspaceContext;
+    resolvedWorkingFolder?: ResolvedWorkingFolderContext;
 }
 export declare class ChannelContextPreparationError extends Error {
     readonly partialContext: PreparedChannelContext;
@@ -109,7 +115,7 @@ interface FileChannelContextStoreOptions {
     skillRuntimeEnabled?: boolean;
     skillAssetResolver?: SkillAssetResolver;
     localhostGateway?: LocalhostGatewayContextPublisher;
-    workspaceCollectionRootDir?: string;
+    workingFolderCollectionRootDir?: string;
     taskReader?: Pick<ChatControlPlane, 'getTask' | 'listChannels' | 'listTasks' | 'listUsers'>;
     taskResolutionTimeoutMs?: number;
     allowCrossAgentIndependentWorkspaceHandoff?: boolean;
@@ -128,13 +134,13 @@ export declare function resolveChannelContextDirectory(stateRootDir: string, cha
 export declare function resolveChannelContextPayloadPath(stateRootDir: string, channelId: string): string;
 export declare function resolveTaskAssignmentStateDirectory(stateRootDir: string, channelId: string): string;
 export declare function resolveTaskAssignmentStatePath(stateRootDir: string, channelId: string): string;
-export declare function resolveTaskWorkspaceRootDirectory(startupWorkspaceRootDir: string): string;
-export declare function resolveManagedWorkspaceCollectionRoot(workspaceCollectionRootDir: string | undefined, env?: NodeJS.ProcessEnv, resolvedHomeDir?: string): string;
-export declare function resolveChannelWorkspaceRootDirectory(workspaceCollectionRootDir: string, channelId: string): string;
-export declare function resolveChannelWorkspaceDirectory(workspaceCollectionRootDir: string, channelId: string): string;
-export declare function resolveTaskIsolatedWorkspaceDirectory(workspaceCollectionRootDir: string, channelId: string, taskId: string): string;
-export declare const resolveTaskWorkspaceDirectory: typeof resolveTaskIsolatedWorkspaceDirectory;
-export declare function resolveTaskThreadScratchWorkspaceDirectory(workspaceCollectionRootDir: string, channelId: string): string;
+export declare function resolveTaskWorkingFolderRootDirectory(channelRootDir: string): string;
+export declare function resolveManagedWorkingFolderCollectionRoot(workingFolderCollectionRootDir: string | undefined, env?: NodeJS.ProcessEnv, resolvedHomeDir?: string): string;
+export declare function resolveChannelWorkingFolderRootDirectory(workingFolderCollectionRootDir: string, channelId: string): string;
+export declare function resolveChannelWorkingFolderDirectory(workingFolderCollectionRootDir: string, channelId: string): string;
+export declare function resolveTaskIsolatedWorkingFolderDirectory(workingFolderCollectionRootDir: string, channelId: string, taskId: string): string;
+export declare const resolveTaskWorkingFolderDirectory: typeof resolveTaskIsolatedWorkingFolderDirectory;
+export declare function resolveTaskThreadScratchWorkingFolderDirectory(workingFolderCollectionRootDir: string, channelId: string): string;
 export declare function resolveChannelGatewayCredentialPath(stateRootDir: string, channelId: string): string;
 export declare function resolveGatewayCredentialPathFromPayloadPath(payloadPath: string): string;
 export declare function resolveClaudeProjectedBriefPathFromPayloadPath(payloadPath: string): string;
@@ -146,7 +152,7 @@ export declare class FileChannelContextStore implements ChannelContextStore {
     private readonly skillRuntimeEnabled;
     private readonly skillAssetResolver;
     private readonly localhostGateway?;
-    private readonly workspaceCollectionRootDir;
+    private readonly workingFolderCollectionRootDir;
     private readonly taskReader?;
     private readonly taskResolutionTimeoutMs;
     private readonly allowCrossAgentIndependentWorkspaceHandoff;

package/dist/context/injection.js

@@ -12,12 +12,12 @@ const TASK_ASSIGNMENT_STATE_FILENAME = 'context.json';
 const CHANNEL_GATEWAY_CREDENTIAL_FILENAME = '.borgee-agent-gateway.json';
 const CLAUDE_PROJECTED_BRIEF_FILENAME = 'CLAUDE.md';
 const DEFAULT_HOME_BORGEE_DIRNAME = '.borgee';
-const CHANNEL_WORKSPACE_COLLECTION_DIRNAME = 'channels';
-const CHANNEL_WORKSPACE_DIRNAME = 'workspace';
-const TASK_ISOLATED_WORKSPACE_COLLECTION_DIRNAME = 'tasks';
-const TASK_THREAD_SCRATCH_WORKSPACE_DIRNAME = 'scratch';
+const CHANNEL_WORKING_FOLDER_COLLECTION_DIRNAME = 'channels';
+const CHANNEL_WORKING_FOLDER_DIRNAME = 'workspace';
+const TASK_ISOLATED_WORKING_FOLDER_COLLECTION_DIRNAME = 'tasks';
+const TASK_THREAD_SCRATCH_WORKING_FOLDER_DIRNAME = 'scratch';
 const TASK_EXECUTION_LOCAL_DIRECTORY_PROPERTY_KEY = 'execution.local_directory';
-const DEFAULT_TASK_WORKSPACE_RESOLUTION_TIMEOUT_MS = 1_500;
+const DEFAULT_TASK_WORKING_FOLDER_RESOLUTION_TIMEOUT_MS = 1_500;
 export class ChannelContextPreparationError extends Error {
     partialContext;
     constructor(message, partialContext, options) {
@@ -113,7 +113,7 @@ function buildPromptContextForClaudeProjectedBrief(preparedContext) {
         skillRuntime: preparedContext.skillRuntime,
         localhostGateway: preparedContext.localhostGateway,
         taskAssignmentContext: preparedContext.payload.taskAssignmentContext,
-        resolvedWorkspace: preparedContext.resolvedWorkspace,
+        resolvedWorkingFolder: preparedContext.resolvedWorkingFolder,
         runtimeSurface: preparedContext.payload.runtimeSurface,
         collaborationOutcome: preparedContext.payload.collaborationOutcome,
         attentionSnapshot: preparedContext.payload.attentionSnapshot,
@@ -246,17 +246,17 @@ async function readExistingTaskAssignmentContext(statePath, fileSystem) {
         return undefined;
     }
 }
-function buildChannelResolvedWorkspace(workspaceCollectionRootDir, channelId) {
+function buildChannelResolvedWorkingFolder(workingFolderCollectionRootDir, channelId) {
     return {
         authority: 'channel',
         owningChannelId: channelId,
-        rootPath: resolveChannelWorkspaceDirectory(workspaceCollectionRootDir, channelId),
+        rootPath: resolveChannelWorkingFolderDirectory(workingFolderCollectionRootDir, channelId),
     };
 }
-function buildTaskThreadScratchResolvedWorkspace(workspaceCollectionRootDir, channelId, reason = 'missing-or-invalid-execution-target') {
+function buildTaskThreadScratchResolvedWorkingFolder(workingFolderCollectionRootDir, channelId, reason = 'missing-or-invalid-execution-target') {
     return {
         authority: 'task-thread-scratch',
-        rootPath: resolveTaskThreadScratchWorkspaceDirectory(workspaceCollectionRootDir, channelId),
+        rootPath: resolveTaskThreadScratchWorkingFolderDirectory(workingFolderCollectionRootDir, channelId),
         reason,
     };
 }
@@ -312,23 +312,23 @@ async function isExistingDirectory(fileSystem, path) {
         return false;
     }
 }
-async function resolveTaskThreadWorkspaceContext(params) {
-    const channelWorkspace = buildChannelResolvedWorkspace(params.workspaceCollectionRootDir, params.channelId);
-    const discussionOnlyWorkspace = buildTaskThreadScratchResolvedWorkspace(params.workspaceCollectionRootDir, params.channelId);
+async function resolveTaskThreadWorkingFolderContext(params) {
+    const channelWorkingFolder = buildChannelResolvedWorkingFolder(params.workingFolderCollectionRootDir, params.channelId);
+    const discussionOnlyWorkingFolder = buildTaskThreadScratchResolvedWorkingFolder(params.workingFolderCollectionRootDir, params.channelId);
     const taskAssignmentContext = params.taskAssignmentContext;
     const currentTaskId = taskAssignmentContext?.currentTaskId?.trim();
     if (taskAssignmentContext?.active !== true) {
-        return { taskAssignmentContext, resolvedWorkspace: channelWorkspace };
+        return { taskAssignmentContext, resolvedWorkingFolder: channelWorkingFolder };
     }
     if (!currentTaskId || !params.taskReader) {
-        return { taskAssignmentContext, resolvedWorkspace: discussionOnlyWorkspace };
+        return { taskAssignmentContext, resolvedWorkingFolder: discussionOnlyWorkingFolder };
     }
     try {
-        const task = await withDeadline(findTaskForThread(params.taskReader, params.channelId, currentTaskId), params.taskResolutionTimeoutMs, `workspace resolution timed out for task ${currentTaskId}`);
+        const task = await withDeadline(findTaskForThread(params.taskReader, params.channelId, currentTaskId), params.taskResolutionTimeoutMs, `working folder resolution timed out for task ${currentTaskId}`);
         if (!task) {
             return {
                 taskAssignmentContext,
-                resolvedWorkspace: discussionOnlyWorkspace,
+                resolvedWorkingFolder: discussionOnlyWorkingFolder,
             };
         }
         const executionLocalDirectory = task.properties[TASK_EXECUTION_LOCAL_DIRECTORY_PROPERTY_KEY];
@@ -337,7 +337,7 @@ async function resolveTaskThreadWorkspaceContext(params) {
             || !(await isExistingDirectory(params.fileSystem, executionLocalDirectory))) {
             return {
                 taskAssignmentContext,
-                resolvedWorkspace: discussionOnlyWorkspace,
+                resolvedWorkingFolder: discussionOnlyWorkingFolder,
             };
         }
         if (!params.allowCrossAgentIndependentWorkspaceHandoff
@@ -348,12 +348,12 @@ async function resolveTaskThreadWorkspaceContext(params) {
             })) {
             return {
                 taskAssignmentContext,
-                resolvedWorkspace: buildTaskThreadScratchResolvedWorkspace(params.workspaceCollectionRootDir, params.channelId, 'cross-agent-independent-workspace-disabled'),
+                resolvedWorkingFolder: buildTaskThreadScratchResolvedWorkingFolder(params.workingFolderCollectionRootDir, params.channelId, 'cross-agent-independent-workspace-disabled'),
             };
         }
         return {
             taskAssignmentContext,
-            resolvedWorkspace: {
+            resolvedWorkingFolder: {
                 authority: 'task-execution-target',
                 taskId: task.id,
                 rootPath: executionLocalDirectory,
@@ -363,7 +363,7 @@ async function resolveTaskThreadWorkspaceContext(params) {
     catch (error) {
         return {
             taskAssignmentContext,
-            resolvedWorkspace: discussionOnlyWorkspace,
+            resolvedWorkingFolder: discussionOnlyWorkingFolder,
         };
     }
 }
@@ -383,32 +383,32 @@ export function resolveTaskAssignmentStateDirectory(stateRootDir, channelId) {
 export function resolveTaskAssignmentStatePath(stateRootDir, channelId) {
     return join(resolveTaskAssignmentStateDirectory(stateRootDir, channelId), TASK_ASSIGNMENT_STATE_FILENAME);
 }
-export function resolveTaskWorkspaceRootDirectory(startupWorkspaceRootDir) {
-    return join(resolve(startupWorkspaceRootDir), TASK_ISOLATED_WORKSPACE_COLLECTION_DIRNAME);
+export function resolveTaskWorkingFolderRootDirectory(channelRootDir) {
+    return join(resolve(channelRootDir), TASK_ISOLATED_WORKING_FOLDER_COLLECTION_DIRNAME);
 }
-export function resolveManagedWorkspaceCollectionRoot(workspaceCollectionRootDir, env = process.env, resolvedHomeDir = homedir()) {
-    const explicitRoot = workspaceCollectionRootDir?.trim();
+export function resolveManagedWorkingFolderCollectionRoot(workingFolderCollectionRootDir, env = process.env, resolvedHomeDir = homedir()) {
+    const explicitRoot = workingFolderCollectionRootDir?.trim();
     if (explicitRoot) {
         return resolve(explicitRoot);
     }
     const home = env.HOME?.trim() || resolvedHomeDir.trim();
     if (!home) {
-        throw new Error('Unable to resolve a user home directory for agents-host workspaces');
+        throw new Error('Unable to resolve a user home directory for agents-host working folders');
     }
-    return join(resolve(home), DEFAULT_HOME_BORGEE_DIRNAME, CHANNEL_WORKSPACE_COLLECTION_DIRNAME);
+    return join(resolve(home), DEFAULT_HOME_BORGEE_DIRNAME, CHANNEL_WORKING_FOLDER_COLLECTION_DIRNAME);
 }
-export function resolveChannelWorkspaceRootDirectory(workspaceCollectionRootDir, channelId) {
-    return join(resolve(workspaceCollectionRootDir), encodeChannelPathSegment(channelId));
+export function resolveChannelWorkingFolderRootDirectory(workingFolderCollectionRootDir, channelId) {
+    return join(resolve(workingFolderCollectionRootDir), encodeChannelPathSegment(channelId));
 }
-export function resolveChannelWorkspaceDirectory(workspaceCollectionRootDir, channelId) {
-    return join(resolveChannelWorkspaceRootDirectory(workspaceCollectionRootDir, channelId), CHANNEL_WORKSPACE_DIRNAME);
+export function resolveChannelWorkingFolderDirectory(workingFolderCollectionRootDir, channelId) {
+    return join(resolveChannelWorkingFolderRootDirectory(workingFolderCollectionRootDir, channelId), CHANNEL_WORKING_FOLDER_DIRNAME);
 }
-export function resolveTaskIsolatedWorkspaceDirectory(workspaceCollectionRootDir, channelId, taskId) {
-    return join(resolveTaskWorkspaceRootDirectory(resolveChannelWorkspaceRootDirectory(workspaceCollectionRootDir, channelId)), encodeChannelPathSegment(taskId), CHANNEL_WORKSPACE_DIRNAME);
+export function resolveTaskIsolatedWorkingFolderDirectory(workingFolderCollectionRootDir, channelId, taskId) {
+    return join(resolveTaskWorkingFolderRootDirectory(resolveChannelWorkingFolderRootDirectory(workingFolderCollectionRootDir, channelId)), encodeChannelPathSegment(taskId), CHANNEL_WORKING_FOLDER_DIRNAME);
 }
-export const resolveTaskWorkspaceDirectory = resolveTaskIsolatedWorkspaceDirectory;
-export function resolveTaskThreadScratchWorkspaceDirectory(workspaceCollectionRootDir, channelId) {
-    return join(resolveChannelWorkspaceRootDirectory(workspaceCollectionRootDir, channelId), TASK_THREAD_SCRATCH_WORKSPACE_DIRNAME, CHANNEL_WORKSPACE_DIRNAME);
+export const resolveTaskWorkingFolderDirectory = resolveTaskIsolatedWorkingFolderDirectory;
+export function resolveTaskThreadScratchWorkingFolderDirectory(workingFolderCollectionRootDir, channelId) {
+    return join(resolveChannelWorkingFolderRootDirectory(workingFolderCollectionRootDir, channelId), TASK_THREAD_SCRATCH_WORKING_FOLDER_DIRNAME, CHANNEL_WORKING_FOLDER_DIRNAME);
 }
 export function resolveChannelGatewayCredentialPath(stateRootDir, channelId) {
     return join(resolveChannelContextDirectory(stateRootDir, channelId), CHANNEL_GATEWAY_CREDENTIAL_FILENAME);
@@ -509,7 +509,7 @@ export class FileChannelContextStore {
     skillRuntimeEnabled;
     skillAssetResolver;
     localhostGateway;
-    workspaceCollectionRootDir;
+    workingFolderCollectionRootDir;
     taskReader;
     taskResolutionTimeoutMs;
     allowCrossAgentIndependentWorkspaceHandoff;
@@ -520,9 +520,9 @@ export class FileChannelContextStore {
         this.skillRuntimeEnabled = options.skillRuntimeEnabled ?? false;
         this.skillAssetResolver = options.skillAssetResolver ?? new PackageSkillAssetResolver(import.meta.url, this.fileSystem);
         this.localhostGateway = options.localhostGateway;
-        this.workspaceCollectionRootDir = resolveManagedWorkspaceCollectionRoot(options.workspaceCollectionRootDir, options.env, options.resolvedHomeDir);
+        this.workingFolderCollectionRootDir = resolveManagedWorkingFolderCollectionRoot(options.workingFolderCollectionRootDir, options.env, options.resolvedHomeDir);
         this.taskReader = options.taskReader;
-        this.taskResolutionTimeoutMs = options.taskResolutionTimeoutMs ?? DEFAULT_TASK_WORKSPACE_RESOLUTION_TIMEOUT_MS;
+        this.taskResolutionTimeoutMs = options.taskResolutionTimeoutMs ?? DEFAULT_TASK_WORKING_FOLDER_RESOLUTION_TIMEOUT_MS;
         this.allowCrossAgentIndependentWorkspaceHandoff
             = options.allowCrossAgentIndependentWorkspaceHandoff ?? true;
         this.resolveStableAgentId = options.resolveStableAgentId;
@@ -571,9 +571,9 @@ export class FileChannelContextStore {
                 incomingMessageType: input.incomingMessageType,
                 incomingContent: input.incomingContent,
             }, existingTaskAssignmentContext);
-        const workspaceResolution = await resolveTaskThreadWorkspaceContext({
+        const workingFolderResolution = await resolveTaskThreadWorkingFolderContext({
             channelId: input.channelId,
-            workspaceCollectionRootDir: this.workspaceCollectionRootDir,
+            workingFolderCollectionRootDir: this.workingFolderCollectionRootDir,
             taskAssignmentContext,
             taskReader: this.taskReader,
             taskResolutionTimeoutMs: this.taskResolutionTimeoutMs,
@@ -581,8 +581,8 @@ export class FileChannelContextStore {
             resolveStableAgentId: this.resolveStableAgentId,
             fileSystem: this.fileSystem,
         });
-        const resolvedWorkspace = workspaceResolution.resolvedWorkspace;
-        const runtimeTaskAssignmentContext = workspaceResolution.taskAssignmentContext ?? taskAssignmentContext;
+        const resolvedWorkingFolder = workingFolderResolution.resolvedWorkingFolder;
+        const runtimeTaskAssignmentContext = workingFolderResolution.taskAssignmentContext ?? taskAssignmentContext;
         const persistedTaskAssignmentContext = input.taskAssignmentContextOverridePersistence === 'ephemeral'
             ? existingTaskAssignmentContext
             : runtimeTaskAssignmentContext;
@@ -591,12 +591,12 @@ export class FileChannelContextStore {
             collaboration: input.collaboration,
             taskAssignmentContext: runtimeTaskAssignmentContext,
         });
-        const payload = buildChannelContextPayload(input.channelId, runtimeSurface, input.collaborationOutcome, input.attentionSnapshot, input.compactionSnapshot, input.taskThreadCollaborationContract, input.collaborationCapabilities, input.missedCollaborationDiagnostic, skillRuntime, localhostGateway, persistedTaskAssignmentContext || resolvedWorkspace
+        const payload = buildChannelContextPayload(input.channelId, runtimeSurface, input.collaborationOutcome, input.attentionSnapshot, input.compactionSnapshot, input.taskThreadCollaborationContract, input.collaborationCapabilities, input.missedCollaborationDiagnostic, skillRuntime, localhostGateway, persistedTaskAssignmentContext || resolvedWorkingFolder
             ? {
                 ...(persistedTaskAssignmentContext
                     ? { taskAssignmentContext: persistedTaskAssignmentContext }
                     : {}),
-                resolvedWorkspace,
+                resolvedWorkspace: resolvedWorkingFolder,
             }
             : undefined);
         const gatewayCredential = buildBorgeeAgentGatewayCredential(input.channelId, issuedLocalhostGateway);
@@ -610,7 +610,7 @@ export class FileChannelContextStore {
             gatewayCredentialPath: gatewayCredential ? gatewayCredentialPath : undefined,
             skillRuntime,
             localhostGateway,
-            resolvedWorkspace,
+            resolvedWorkingFolder,
         };
         const shouldProjectClaudeBrief = input.provider === 'claude' && input.projectionStrategy === 'file-brief';
         const claudeProjectedBriefContent = shouldProjectClaudeBrief
@@ -626,8 +626,8 @@ export class FileChannelContextStore {
         try {
             await this.fileSystem.mkdir(directoryPath, { recursive: true, mode: 0o700 });
             await this.fileSystem.mkdir(resolveTaskAssignmentStateDirectory(this.stateRootDir, input.channelId), { recursive: true, mode: 0o700 });
-            if (resolvedWorkspace.authority !== 'task-execution-target') {
-                await this.fileSystem.mkdir(resolvedWorkspace.rootPath, { recursive: true, mode: 0o700 });
+            if (resolvedWorkingFolder.authority !== 'task-execution-target') {
+                await this.fileSystem.mkdir(resolvedWorkingFolder.rootPath, { recursive: true, mode: 0o700 });
             }
             await pruneGatewayCredentialSidecars(this.fileSystem, directoryPath, gatewayCredential ? CHANNEL_GATEWAY_CREDENTIAL_FILENAME : undefined);
             if (!claudeProjectedBriefContent) {
@@ -675,9 +675,9 @@ export class FileChannelContextStore {
                 directoryPath,
                 payload: {
                     ...payload,
-                    ...(resolvedWorkspace.authority === 'task-execution-target' && runtimeTaskAssignmentContext?.active === true
+                    ...(resolvedWorkingFolder.authority === 'task-execution-target' && runtimeTaskAssignmentContext?.active === true
                         ? {
-                            resolvedWorkspace: buildTaskThreadScratchResolvedWorkspace(this.workspaceCollectionRootDir, input.channelId),
+                            resolvedWorkspace: buildTaskThreadScratchResolvedWorkingFolder(this.workingFolderCollectionRootDir, input.channelId),
                         }
                         : {}),
                 },
@@ -687,9 +687,9 @@ export class FileChannelContextStore {
                 gatewayCredentialPath: gatewayCredentialWritten ? gatewayCredentialPath : undefined,
                 skillRuntime: payloadWritten ? skillRuntime : undefined,
                 localhostGateway: payloadWritten ? localhostGateway : undefined,
-                resolvedWorkspace: resolvedWorkspace.authority === 'task-execution-target' && runtimeTaskAssignmentContext?.active === true
-                    ? buildTaskThreadScratchResolvedWorkspace(this.workspaceCollectionRootDir, input.channelId)
-                    : resolvedWorkspace,
+                resolvedWorkingFolder: resolvedWorkingFolder.authority === 'task-execution-target' && runtimeTaskAssignmentContext?.active === true
+                    ? buildTaskThreadScratchResolvedWorkingFolder(this.workingFolderCollectionRootDir, input.channelId)
+                    : resolvedWorkingFolder,
             };
             throw new ChannelContextPreparationError('failed to persist channel context payload', partialContext, { cause: error });
         }

package/dist/context/prompt.js

@@ -4,7 +4,7 @@ import { buildAttentionSummaryLines } from './attention.js';
 import { buildCollaborationCapabilityDeclarationSummaryLines, buildMissedCollaborationDiagnosticSummaryLines, } from './collaboration-capabilities-diagnostics.js';
 import { buildCollaborationOutcomeSummaryLines } from './collaboration-outcome.js';
 import { MAIN_SESSION_DELEGATION_LINES } from './main-session-delegation.js';
-import { buildResolvedWorkspaceGuidanceLines } from './resolved-workspace.js';
+import { buildResolvedWorkingFolderGuidanceLines } from './resolved-working-folder.js';
 import { buildSkillManualLines, buildSkillManualReadLine } from './skill-manual.js';
 import { PARENT_CHANNEL_TASK_BOUNDARY_LINES } from './task-channel-boundary.js';
 import { buildTaskThreadCollaborationSummaryLines } from './task-thread-collaboration.js';
@@ -101,8 +101,8 @@ function buildTaskAssignmentPromptLines(params) {
             'This thread is continuing an existing task assignment.',
             'Keep the main work in this thread.',
         ];
-    if ((params.provider !== 'claude' || params.forceInlineForClaude === true) && params.promptContext?.resolvedWorkspace) {
-        lines.push(...buildResolvedWorkspacePromptLines(params.provider, params.promptContext));
+    if ((params.provider !== 'claude' || params.forceInlineForClaude === true) && params.promptContext?.resolvedWorkingFolder) {
+        lines.push(...buildResolvedWorkingFolderPromptLines(params.provider, params.promptContext));
     }
     if ((params.provider !== 'claude' || params.forceInlineForClaude === true) && taskAssignmentContext?.currentTaskId) {
         lines.push(`Current assigned task id: ${taskAssignmentContext.currentTaskId}.`);
@@ -115,8 +115,8 @@ function buildTaskAssignmentPromptLines(params) {
     }
     return lines;
 }
-function buildResolvedWorkspacePromptLines(provider, context) {
-    return buildResolvedWorkspaceGuidanceLines(context, provider);
+function buildResolvedWorkingFolderPromptLines(provider, context) {
+    return buildResolvedWorkingFolderGuidanceLines(context, provider);
 }
 function buildClaudeOrdinaryGatewayTaskLines(context) {
     if (!context?.skillRuntime || !context.localhostGateway || !context.gatewayCredentialPath) {
@@ -250,18 +250,18 @@ function buildClaudeProjectedBriefTurnPrompt(params) {
         params.incomingContent,
     ].join('\n');
 }
-function buildOrdinaryCopilotWorkspacePromptLines(params) {
+function buildOrdinaryCopilotWorkingFolderPromptLines(params) {
     if (params.provider !== 'copilot') {
         return [];
     }
-    if (!params.promptContext?.resolvedWorkspace) {
+    if (!params.promptContext?.resolvedWorkingFolder) {
         return [];
     }
     if (params.incomingMessageType?.trim() === 'task_assignment'
         || params.promptContext.taskAssignmentContext?.active === true) {
         return [];
     }
-    return buildResolvedWorkspacePromptLines(params.provider, params.promptContext);
+    return buildResolvedWorkingFolderPromptLines(params.provider, params.promptContext);
 }
 function buildInboundMetadataLines(params) {
     return [
@@ -272,7 +272,7 @@ function buildInboundMetadataLines(params) {
             return lines.length > 0 ? ['', ...lines] : [];
         })(),
         ...(() => {
-            const lines = buildOrdinaryCopilotWorkspacePromptLines(params);
+            const lines = buildOrdinaryCopilotWorkingFolderPromptLines(params);
             return lines.length > 0 ? ['', ...lines] : [];
         })(),
         ...buildTaskAssignmentPromptLines({
@@ -601,7 +601,7 @@ function buildClaudeSessionEnvironmentLines(context) {
     if (context.localhostGateway && context.gatewayCredentialPath) {
         lines.push(`Gateway credential file for this session: ${context.gatewayCredentialPath}`);
     }
-    lines.push(...buildResolvedWorkspaceGuidanceLines(context));
+    lines.push(...buildResolvedWorkingFolderGuidanceLines(context));
     if (context.taskAssignmentContext?.currentTaskId) {
         lines.push(`Current assigned task id: ${context.taskAssignmentContext.currentTaskId}.`);
     }

package/dist/context/resolved-working-folder.d.ts

@@ -0,0 +1,3 @@
+import type { PreparedPromptContext, ProviderKind } from '../types.js';
+export declare function buildResolvedWorkingFolderGuidanceLines(context: PreparedPromptContext | undefined, provider?: ProviderKind): string[];
+export declare function isDiscussionOnlyResolvedWorkingFolder(context: PreparedPromptContext | undefined): boolean;

package/dist/context/resolved-working-folder.js

@@ -0,0 +1,106 @@
+function buildWorkingFolderRootLine(context) {
+    const resolvedWorkingFolder = context.resolvedWorkingFolder;
+    if (!resolvedWorkingFolder) {
+        return undefined;
+    }
+    if (resolvedWorkingFolder.authority === 'task-execution-target') {
+        return `Explicit execution local directory for this task thread: ${resolvedWorkingFolder.rootPath}.`;
+    }
+    if (resolvedWorkingFolder.authority === 'task-thread-scratch') {
+        return `Discussion-only scratch working folder for this task thread: ${resolvedWorkingFolder.rootPath}.`;
+    }
+    if (context.taskAssignmentContext?.active === true) {
+        return `Writable working folder inherited from this task thread's channel: ${resolvedWorkingFolder.rootPath}.`;
+    }
+    return `Writable working folder for this channel: ${resolvedWorkingFolder.rootPath}.`;
+}
+function buildWorkingFolderModeLine(context) {
+    if (context.taskAssignmentContext?.active !== true || !context.resolvedWorkingFolder) {
+        return undefined;
+    }
+    if (context.resolvedWorkingFolder.authority === 'task-execution-target') {
+        return 'This task thread has a valid explicit execution.local_directory target, so execution is bound to that exact existing local directory.';
+    }
+    if (context.resolvedWorkingFolder.authority === 'task-thread-scratch') {
+        return context.resolvedWorkingFolder.reason === 'cross-agent-independent-workspace-disabled'
+            ? 'This task thread has an explicit execution.local_directory target, but this agents-host currently disables cross-agent independent-working-folder handoff, so it is discussion-only.'
+            : 'This task thread has no valid explicit execution.local_directory target, so it is discussion-only.';
+    }
+    return 'This task thread inherits the channel working folder rather than using a task-isolated working folder.';
+}
+function buildWorkingFolderLocalityLine(context) {
+    if (!context.resolvedWorkingFolder) {
+        return undefined;
+    }
+    if (context.resolvedWorkingFolder.authority === 'task-execution-target') {
+        return 'This is a human-selected existing local directory. The host validates it before use and never creates it.';
+    }
+    if (context.resolvedWorkingFolder.authority === 'task-thread-scratch') {
+        return 'This scratch working folder is host-managed only for discussion turns. It is not a bound project directory and does not imply that any target repository is checked out there.';
+    }
+    if (context.taskAssignmentContext?.active === true) {
+        return 'This writable working folder is local to agents-host for this task thread because the task inherits its channel working folder. It does not imply that the target repository has already been checked out there.';
+    }
+    return 'This writable working folder is local to agents-host for this channel. It does not imply that the target repository has already been checked out there.';
+}
+function buildCopilotCwdLine(context) {
+    if (!context.resolvedWorkingFolder) {
+        return undefined;
+    }
+    if (context.resolvedWorkingFolder.authority === 'task-execution-target') {
+        return 'GitHub Copilot runs this turn with that exact local directory as its real cwd.';
+    }
+    if (context.resolvedWorkingFolder.authority === 'task-thread-scratch') {
+        return 'GitHub Copilot runs this turn with that host-managed scratch working folder as its real cwd.';
+    }
+    if (context.taskAssignmentContext?.active === true) {
+        return 'GitHub Copilot runs this turn with that inherited channel working folder as its real cwd.';
+    }
+    return 'GitHub Copilot runs this turn with that working folder as its real cwd.';
+}
+function buildDiscussionOnlyPermissionLine(context) {
+    if (context.resolvedWorkingFolder?.authority !== 'task-thread-scratch') {
+        return undefined;
+    }
+    return context.resolvedWorkingFolder.reason === 'cross-agent-independent-workspace-disabled'
+        ? 'Filesystem and shell tool permissions stay denied in this discussion-only task thread while this agents-host keeps cross-agent independent-working-folder handoff disabled.'
+        : 'Filesystem and shell tool permissions stay denied in this discussion-only task thread until a human sets a valid execution.local_directory target.';
+}
+function buildProjectEntryPrecheckLine(context) {
+    if (context.taskAssignmentContext?.active !== true) {
+        return undefined;
+    }
+    if (context.resolvedWorkingFolder?.authority === 'task-execution-target') {
+        return 'Precheck before switching this task thread into your own local project directory: the task\'s parent channel must have exactly one human user. Cross-agent independent-working-folder handoff is also governed by this agents-host\'s local policy switch.';
+    }
+    return 'Before a human switches this task thread into their own local project directory, verify that the task\'s parent channel has exactly one human user; otherwise keep the thread discussion-only. Cross-agent independent-working-folder handoff is also governed by this agents-host\'s local policy switch.';
+}
+export function buildResolvedWorkingFolderGuidanceLines(context, provider) {
+    if (!context?.resolvedWorkingFolder) {
+        return [];
+    }
+    const lines = [buildWorkingFolderRootLine(context), buildWorkingFolderModeLine(context)]
+        .filter((line) => line != null);
+    if (provider === 'copilot') {
+        const copilotCwdLine = buildCopilotCwdLine(context);
+        if (copilotCwdLine) {
+            lines.push(copilotCwdLine);
+        }
+    }
+    const localityLine = buildWorkingFolderLocalityLine(context);
+    if (localityLine) {
+        lines.push(localityLine);
+    }
+    const permissionLine = buildDiscussionOnlyPermissionLine(context);
+    if (permissionLine) {
+        lines.push(permissionLine);
+    }
+    const precheckLine = buildProjectEntryPrecheckLine(context);
+    if (precheckLine) {
+        lines.push(precheckLine);
+    }
+    return lines;
+}
+export function isDiscussionOnlyResolvedWorkingFolder(context) {
+    return context?.resolvedWorkingFolder?.authority === 'task-thread-scratch';
+}

package/dist/context/turn-preparation.js

@@ -38,7 +38,7 @@ function toPromptContext(channelContext, input) {
                 skillRuntime: channelContext.skillRuntime,
                 localhostGateway: channelContext.localhostGateway,
                 taskAssignmentContext: channelContext.payload.taskAssignmentContext,
-                resolvedWorkspace: channelContext.resolvedWorkspace,
+                resolvedWorkingFolder: channelContext.resolvedWorkingFolder,
             }
             : {}),
         runtimeSurface,