@borgee/agents-host 0.2.74 → 0.2.94

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,

package/dist/managed-daemon.js

@@ -6,7 +6,7 @@ import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { AgentsHostSupervisor } from './agents-host-supervisor.js';
 import { DEFAULT_PROJECTION_STRATEGY, normalizeProjectionStrategy, } from './projection-strategy-values.js';
-import { resolveChannelWorkspaceDirectory, resolveChannelWorkspaceRootDirectory, resolveManagedWorkspaceCollectionRoot, resolveTaskThreadScratchWorkspaceDirectory, } from './context/injection.js';
+import { resolveChannelWorkingFolderDirectory, resolveChannelWorkingFolderRootDirectory, resolveManagedWorkingFolderCollectionRoot, resolveTaskThreadScratchWorkingFolderDirectory, } from './context/injection.js';
 import { CLAUDE_PROVIDER_V2_COMPATIBILITY_GATE, COMPATIBILITY_GATES_ENV, CURRENT_AGENTS_HOST_PACKAGE_VERSION, createManagedRuntimeSettingsFingerprint, INTERNAL_CLAUDE_PROMPT_STRATEGY_ENV, INTERNAL_DISABLED_COMPATIBILITY_GATES_ENV, INTERNAL_POLICY_MODE_ENV, INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV, MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE, MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION, resolveDisabledDefaultCompatibilityGates, resolveManagedRuntimeSettingsSnapshot, serializeManagedRuntimeSettingsSnapshot, normalizeInternalProviderImplementationOverrides, } from './compatibility-gates.js';
 import { DEFAULT_PROVIDER_COMMAND_CONFIG, hasLegacyClaudeOneShotArgs, loadConfigFromEnv, } from './config.js';
 import { hasManagedLocalConfig, loadLocalConfigGenerateSpec, materializeLocalConfig, parseGenerateConfigSpec, resolveLocalConfigLayout, } from './local-config.js';
@@ -843,19 +843,19 @@ async function shutdownManagedDaemon(rootPath, sendRequest, waitForShutdown) {
     }
     await waitForShutdown(rootPath);
 }
-function resolveTrustedPersistedChannelWorkspaceRoot(workspaceCollectionRoot, owningChannelId, rootPath) {
+function resolveTrustedPersistedChannelWorkingFolderRoot(workingFolderCollectionRoot, owningChannelId, rootPath) {
     if (!owningChannelId || !isAbsolute(rootPath)) {
         return null;
     }
-    const expectedWorkspacePath = resolveChannelWorkspaceDirectory(workspaceCollectionRoot, owningChannelId);
-    if (rootPath !== expectedWorkspacePath) {
+    const expectedWorkingFolderPath = resolveChannelWorkingFolderDirectory(workingFolderCollectionRoot, owningChannelId);
+    if (rootPath !== expectedWorkingFolderPath) {
         return null;
     }
-    return resolveChannelWorkspaceRootDirectory(workspaceCollectionRoot, owningChannelId);
+    return resolveChannelWorkingFolderRootDirectory(workingFolderCollectionRoot, owningChannelId);
 }
-async function discoverManagedWorkspaceRootsForPurge(rootPath, processEnv) {
-    const trustedWorkspaceCollectionRoots = new Set([
-        resolveManagedWorkspaceCollectionRoot(undefined, processEnv),
+async function discoverManagedWorkingFolderRootsForPurge(rootPath, processEnv) {
+    const trustedWorkingFolderCollectionRoots = new Set([
+        resolveManagedWorkingFolderCollectionRoot(undefined, processEnv),
     ]);
     const managedStateRoot = resolveManagedStateRoot(rootPath);
     const agentStateEntries = await fs.readdir(managedStateRoot, { withFileTypes: true }).catch((error) => {
@@ -864,7 +864,7 @@ async function discoverManagedWorkspaceRootsForPurge(rootPath, processEnv) {
         }
         throw error;
     });
-    const workspaceRoots = new Set();
+    const workingFolderRoots = new Set();
     for (const agentStateEntry of agentStateEntries) {
         if (!agentStateEntry.isDirectory()) {
             continue;
@@ -900,43 +900,43 @@ async function discoverManagedWorkspaceRootsForPurge(rootPath, processEnv) {
             if (!isRecord(parsed) || typeof parsed.channelId !== 'string' || !isRecord(parsed.resolvedWorkspace)) {
                 continue;
             }
-            const resolvedWorkspace = parsed.resolvedWorkspace;
-            if ((resolvedWorkspace.authority !== 'channel'
-                && resolvedWorkspace.authority !== 'task-thread-scratch'
-                && resolvedWorkspace.authority !== 'task-execution-target')
-                || typeof resolvedWorkspace.rootPath !== 'string'
-                || !isAbsolute(resolvedWorkspace.rootPath)) {
+            const resolvedWorkingFolder = parsed.resolvedWorkspace;
+            if ((resolvedWorkingFolder.authority !== 'channel'
+                && resolvedWorkingFolder.authority !== 'task-thread-scratch'
+                && resolvedWorkingFolder.authority !== 'task-execution-target')
+                || typeof resolvedWorkingFolder.rootPath !== 'string'
+                || !isAbsolute(resolvedWorkingFolder.rootPath)) {
                 continue;
             }
-            for (const workspaceCollectionRoot of trustedWorkspaceCollectionRoots) {
-                if (resolvedWorkspace.authority === 'channel') {
-                    if (typeof resolvedWorkspace.owningChannelId !== 'string'
-                        || resolvedWorkspace.owningChannelId.length === 0) {
+            for (const workingFolderCollectionRoot of trustedWorkingFolderCollectionRoots) {
+                if (resolvedWorkingFolder.authority === 'channel') {
+                    if (typeof resolvedWorkingFolder.owningChannelId !== 'string'
+                        || resolvedWorkingFolder.owningChannelId.length === 0) {
                         continue;
                     }
-                    const trustedChannelWorkspaceRoot = resolveTrustedPersistedChannelWorkspaceRoot(workspaceCollectionRoot, resolvedWorkspace.owningChannelId, resolvedWorkspace.rootPath);
-                    if (!trustedChannelWorkspaceRoot) {
+                    const trustedChannelWorkingFolderRoot = resolveTrustedPersistedChannelWorkingFolderRoot(workingFolderCollectionRoot, resolvedWorkingFolder.owningChannelId, resolvedWorkingFolder.rootPath);
+                    if (!trustedChannelWorkingFolderRoot) {
                         continue;
                     }
-                    workspaceRoots.add(trustedChannelWorkspaceRoot);
+                    workingFolderRoots.add(trustedChannelWorkingFolderRoot);
                     break;
                 }
-                if (resolvedWorkspace.authority === 'task-thread-scratch') {
-                    const expectedWorkspacePath = resolveTaskThreadScratchWorkspaceDirectory(workspaceCollectionRoot, parsed.channelId);
-                    if (resolvedWorkspace.rootPath !== expectedWorkspacePath) {
+                if (resolvedWorkingFolder.authority === 'task-thread-scratch') {
+                    const expectedWorkingFolderPath = resolveTaskThreadScratchWorkingFolderDirectory(workingFolderCollectionRoot, parsed.channelId);
+                    if (resolvedWorkingFolder.rootPath !== expectedWorkingFolderPath) {
                         continue;
                     }
-                    workspaceRoots.add(resolveChannelWorkspaceRootDirectory(workspaceCollectionRoot, parsed.channelId));
+                    workingFolderRoots.add(resolveChannelWorkingFolderRootDirectory(workingFolderCollectionRoot, parsed.channelId));
                     break;
                 }
-                if (resolvedWorkspace.authority !== 'task-execution-target') {
+                if (resolvedWorkingFolder.authority !== 'task-execution-target') {
                     continue;
                 }
                 continue;
             }
         }
     }
-    return [...workspaceRoots].sort((left, right) => left.localeCompare(right));
+    return [...workingFolderRoots].sort((left, right) => left.localeCompare(right));
 }
 export async function cleanupManagedRuntime(options, deps = {}) {
     const sendRequest = deps.sendRequest ?? sendManagedDaemonRequest;
@@ -974,8 +974,8 @@ export async function cleanupManagedRuntime(options, deps = {}) {
         await waitForShutdown(resolved.rootPath);
     }
     if (options.purge === true) {
-        for (const workspaceRoot of await discoverManagedWorkspaceRootsForPurge(resolved.rootPath, options.processEnv ?? process.env)) {
-            await fs.rm(workspaceRoot, { recursive: true, force: true });
+        for (const workingFolderRoot of await discoverManagedWorkingFolderRootsForPurge(resolved.rootPath, options.processEnv ?? process.env)) {
+            await fs.rm(workingFolderRoot, { recursive: true, force: true });
         }
         await removeRuntimeRoot(resolved.rootPath);
     }