@borgee/agents-host 0.2.56 → 0.2.62

package/dist/context/injection.js

@@ -1,4 +1,4 @@
-import { promises as fs } from 'node:fs';
+import { constants as fsConstants, promises as fs } from 'node:fs';
 import { createHash, randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -7,14 +7,16 @@ import { findTaskForThread } from '../task-thread-resolution.js';
 import { buildClaudeFileBrief } from './claude-file-brief.js';
 const CHANNEL_CONTEXT_ROOT_DIRNAME = 'channel-context';
 const CHANNEL_CONTEXT_PAYLOAD_FILENAME = 'context.json';
+const TASK_ASSIGNMENT_STATE_ROOT_DIRNAME = 'task-assignment-state';
+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_WORKSPACE_MODE_PROPERTY_KEY = 'workspace.mode';
-const TASK_WORKSPACE_MODE_ISOLATED = 'isolated';
+const TASK_THREAD_SCRATCH_WORKSPACE_DIRNAME = 'scratch';
+const TASK_EXECUTION_LOCAL_DIRECTORY_PROPERTY_KEY = 'execution.local_directory';
 const DEFAULT_TASK_WORKSPACE_RESOLUTION_TIMEOUT_MS = 1_500;
 export class ChannelContextPreparationError extends Error {
     partialContext;
@@ -43,8 +45,11 @@ const DEFAULT_FILE_SYSTEM = {
     async rename(oldPath, newPath) {
         await fs.rename(oldPath, newPath);
     },
-    async access(path) {
-        await fs.access(path);
+    async access(path, mode) {
+        await fs.access(path, mode);
+    },
+    async stat(path) {
+        return await fs.stat(path);
     },
 };
 const BORGEE_AGENT_SKILL_DIRNAME = 'borgee-agent';
@@ -231,9 +236,9 @@ function buildTaskAssignmentContextForTurn(options, existingContext) {
     }
     return existingContext;
 }
-async function readExistingTaskAssignmentContext(payloadPath, fileSystem) {
+async function readExistingTaskAssignmentContext(statePath, fileSystem) {
     try {
-        const raw = await fileSystem.readFile(payloadPath, { encoding: 'utf8' });
+        const raw = await fileSystem.readFile(statePath, { encoding: 'utf8' });
         const payload = JSON.parse(raw);
         return sanitizeTaskAssignmentContext(payload.taskAssignmentContext);
     }
@@ -241,125 +246,124 @@ async function readExistingTaskAssignmentContext(payloadPath, fileSystem) {
         return undefined;
     }
 }
-function sanitizeResolvedWorkspaceContext(value) {
-    if (!isRecord(value) || typeof value.rootPath !== 'string' || !isAbsolute(value.rootPath)) {
-        return undefined;
+function buildChannelResolvedWorkspace(workspaceCollectionRootDir, channelId) {
+    return {
+        authority: 'channel',
+        owningChannelId: channelId,
+        rootPath: resolveChannelWorkspaceDirectory(workspaceCollectionRootDir, channelId),
+    };
+}
+function buildTaskThreadScratchResolvedWorkspace(workspaceCollectionRootDir, channelId, reason = 'missing-or-invalid-execution-target') {
+    return {
+        authority: 'task-thread-scratch',
+        rootPath: resolveTaskThreadScratchWorkspaceDirectory(workspaceCollectionRootDir, channelId),
+        reason,
+    };
+}
+async function isCrossAgentTaskCreatedByAnotherAgent(params) {
+    const selfAgentId = params.resolveStableAgentId?.()?.trim();
+    if (!selfAgentId) {
+        return true;
     }
-    if (value.authority === 'channel'
-        && typeof value.owningChannelId === 'string'
-        && value.owningChannelId.length > 0) {
-        return {
-            authority: 'channel',
-            owningChannelId: value.owningChannelId,
-            rootPath: value.rootPath,
-        };
+    if (params.task.createdBy === selfAgentId) {
+        return false;
     }
-    if (value.authority === 'task'
-        && typeof value.taskId === 'string'
-        && isUsableTaskId(value.taskId.trim())) {
-        return {
-            authority: 'task',
-            taskId: value.taskId.trim(),
-            rootPath: value.rootPath,
-        };
+    if (!params.taskReader) {
+        return true;
     }
-    return undefined;
+    const users = await params.taskReader.listUsers();
+    const creator = users.find((user) => user.id === params.task.createdBy);
+    if (!creator) {
+        return true;
+    }
+    return creator.kind === 'agent';
 }
-async function readExistingResolvedWorkspaceContext(payloadPath, fileSystem) {
+async function withDeadline(promise, timeoutMs, timeoutMessage) {
+    if (timeoutMs <= 0) {
+        return await promise;
+    }
+    let timer;
     try {
-        const raw = await fileSystem.readFile(payloadPath, { encoding: 'utf8' });
-        const payload = JSON.parse(raw);
-        return sanitizeResolvedWorkspaceContext(payload.resolvedWorkspace);
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(timeoutMessage)), timeoutMs);
+            }),
+        ]);
     }
-    catch {
-        return undefined;
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
     }
 }
-function buildChannelResolvedWorkspace(workspaceCollectionRootDir, channelId) {
-    return {
-        authority: 'channel',
-        owningChannelId: channelId,
-        rootPath: resolveChannelWorkspaceDirectory(workspaceCollectionRootDir, channelId),
-    };
-}
-function buildStickyChannelResolvedWorkspace(workspaceCollectionRootDir, resolvedWorkspace) {
-    if (resolvedWorkspace?.authority !== 'channel') {
-        return undefined;
+async function isExistingDirectory(fileSystem, path) {
+    if (!isAbsolute(path)) {
+        return false;
     }
-    const expectedRootPath = resolveChannelWorkspaceDirectory(workspaceCollectionRootDir, resolvedWorkspace.owningChannelId);
-    if (resolvedWorkspace.rootPath !== expectedRootPath) {
-        return undefined;
+    try {
+        await fileSystem.access(path, fsConstants.R_OK | fsConstants.W_OK | fsConstants.X_OK);
+        if (typeof fileSystem.stat !== 'function') {
+            return true;
+        }
+        return (await fileSystem.stat(path)).isDirectory();
+    }
+    catch {
+        return false;
     }
-    return {
-        authority: 'channel',
-        owningChannelId: resolvedWorkspace.owningChannelId,
-        rootPath: expectedRootPath,
-    };
 }
 async function resolveTaskThreadWorkspaceContext(params) {
     const channelWorkspace = buildChannelResolvedWorkspace(params.workspaceCollectionRootDir, params.channelId);
+    const discussionOnlyWorkspace = buildTaskThreadScratchResolvedWorkspace(params.workspaceCollectionRootDir, params.channelId);
     const taskAssignmentContext = params.taskAssignmentContext;
     const currentTaskId = taskAssignmentContext?.currentTaskId?.trim();
-    if (taskAssignmentContext?.active !== true
-        || !currentTaskId
-        || !params.taskReader) {
+    if (taskAssignmentContext?.active !== true) {
         return { taskAssignmentContext, resolvedWorkspace: channelWorkspace };
     }
-    const stickyTaskWorkspace = params.existingResolvedWorkspace?.authority === 'task'
-        && params.existingResolvedWorkspace.taskId === currentTaskId
-        ? {
-            authority: 'task',
-            taskId: currentTaskId,
-            rootPath: resolveTaskWorkspaceDirectory(params.workspaceCollectionRootDir, params.channelId, currentTaskId),
-        }
-        : undefined;
-    const stickyChannelWorkspace = buildStickyChannelResolvedWorkspace(params.workspaceCollectionRootDir, params.existingResolvedWorkspace);
+    if (!currentTaskId || !params.taskReader) {
+        return { taskAssignmentContext, resolvedWorkspace: discussionOnlyWorkspace };
+    }
     try {
         const task = await withDeadline(findTaskForThread(params.taskReader, params.channelId, currentTaskId), params.taskResolutionTimeoutMs, `workspace resolution timed out for task ${currentTaskId}`);
         if (!task) {
             return {
                 taskAssignmentContext,
-                resolvedWorkspace: channelWorkspace,
+                resolvedWorkspace: discussionOnlyWorkspace,
             };
         }
-        async function withDeadline(promise, timeoutMs, timeoutMessage) {
-            if (timeoutMs <= 0) {
-                return await promise;
-            }
-            let timer;
-            try {
-                return await Promise.race([
-                    promise,
-                    new Promise((_, reject) => {
-                        timer = setTimeout(() => reject(new Error(timeoutMessage)), timeoutMs);
-                    }),
-                ]);
-            }
-            finally {
-                if (timer) {
-                    clearTimeout(timer);
-                }
-            }
+        const executionLocalDirectory = task.properties[TASK_EXECUTION_LOCAL_DIRECTORY_PROPERTY_KEY];
+        if (typeof executionLocalDirectory !== 'string'
+            || executionLocalDirectory.length === 0
+            || !(await isExistingDirectory(params.fileSystem, executionLocalDirectory))) {
+            return {
+                taskAssignmentContext,
+                resolvedWorkspace: discussionOnlyWorkspace,
+            };
         }
-        if (task.properties[TASK_WORKSPACE_MODE_PROPERTY_KEY] !== TASK_WORKSPACE_MODE_ISOLATED) {
+        if (!params.allowCrossAgentIndependentWorkspaceHandoff
+            && await isCrossAgentTaskCreatedByAnotherAgent({
+                task,
+                taskReader: params.taskReader,
+                resolveStableAgentId: params.resolveStableAgentId,
+            })) {
             return {
                 taskAssignmentContext,
-                resolvedWorkspace: buildChannelResolvedWorkspace(params.workspaceCollectionRootDir, task.channelId),
+                resolvedWorkspace: buildTaskThreadScratchResolvedWorkspace(params.workspaceCollectionRootDir, params.channelId, 'cross-agent-independent-workspace-disabled'),
             };
         }
         return {
             taskAssignmentContext,
             resolvedWorkspace: {
-                authority: 'task',
+                authority: 'task-execution-target',
                 taskId: task.id,
-                rootPath: resolveTaskWorkspaceDirectory(params.workspaceCollectionRootDir, params.channelId, task.id),
+                rootPath: executionLocalDirectory,
             },
         };
     }
     catch (error) {
         return {
             taskAssignmentContext,
-            resolvedWorkspace: stickyTaskWorkspace ?? stickyChannelWorkspace ?? channelWorkspace,
+            resolvedWorkspace: discussionOnlyWorkspace,
         };
     }
 }
@@ -373,6 +377,12 @@ export function resolveChannelContextDirectory(stateRootDir, channelId) {
 export function resolveChannelContextPayloadPath(stateRootDir, channelId) {
     return join(resolveChannelContextDirectory(stateRootDir, channelId), CHANNEL_CONTEXT_PAYLOAD_FILENAME);
 }
+export function resolveTaskAssignmentStateDirectory(stateRootDir, channelId) {
+    return resolve(stateRootDir, TASK_ASSIGNMENT_STATE_ROOT_DIRNAME, encodeChannelPathSegment(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);
 }
@@ -397,6 +407,9 @@ export function resolveTaskIsolatedWorkspaceDirectory(workspaceCollectionRootDir
     return join(resolveTaskWorkspaceRootDirectory(resolveChannelWorkspaceRootDirectory(workspaceCollectionRootDir, channelId)), encodeChannelPathSegment(taskId), CHANNEL_WORKSPACE_DIRNAME);
 }
 export const resolveTaskWorkspaceDirectory = resolveTaskIsolatedWorkspaceDirectory;
+export function resolveTaskThreadScratchWorkspaceDirectory(workspaceCollectionRootDir, channelId) {
+    return join(resolveChannelWorkspaceRootDirectory(workspaceCollectionRootDir, channelId), TASK_THREAD_SCRATCH_WORKSPACE_DIRNAME, CHANNEL_WORKSPACE_DIRNAME);
+}
 export function resolveChannelGatewayCredentialPath(stateRootDir, channelId) {
     return join(resolveChannelContextDirectory(stateRootDir, channelId), CHANNEL_GATEWAY_CREDENTIAL_FILENAME);
 }
@@ -499,6 +512,8 @@ export class FileChannelContextStore {
     workspaceCollectionRootDir;
     taskReader;
     taskResolutionTimeoutMs;
+    allowCrossAgentIndependentWorkspaceHandoff;
+    resolveStableAgentId;
     constructor(stateRootDir, options = {}) {
         this.stateRootDir = stateRootDir;
         this.fileSystem = options.fileSystem ?? DEFAULT_FILE_SYSTEM;
@@ -508,6 +523,9 @@ export class FileChannelContextStore {
         this.workspaceCollectionRootDir = resolveManagedWorkspaceCollectionRoot(options.workspaceCollectionRootDir, options.env, options.resolvedHomeDir);
         this.taskReader = options.taskReader;
         this.taskResolutionTimeoutMs = options.taskResolutionTimeoutMs ?? DEFAULT_TASK_WORKSPACE_RESOLUTION_TIMEOUT_MS;
+        this.allowCrossAgentIndependentWorkspaceHandoff
+            = options.allowCrossAgentIndependentWorkspaceHandoff ?? true;
+        this.resolveStableAgentId = options.resolveStableAgentId;
     }
     async prepare(inputOrChannelId, options) {
         const input = typeof inputOrChannelId === 'string'
@@ -519,10 +537,10 @@ export class FileChannelContextStore {
         const auxiliaryCollaborationEnabled = collaborationCommandsEnabled && collaborationRoutesAllowedForTurnMode;
         const directoryPath = resolveChannelContextDirectory(this.stateRootDir, input.channelId);
         const payloadPath = resolveChannelContextPayloadPath(this.stateRootDir, input.channelId);
+        const taskAssignmentStatePath = resolveTaskAssignmentStatePath(this.stateRootDir, input.channelId);
         const claudeProjectedBriefPath = resolveClaudeProjectedBriefPathFromPayloadPath(payloadPath);
         const gatewayCredentialPath = resolveGatewayCredentialPathFromPayloadPath(payloadPath);
-        const existingTaskAssignmentContext = await readExistingTaskAssignmentContext(payloadPath, this.fileSystem);
-        const existingResolvedWorkspace = await readExistingResolvedWorkspaceContext(payloadPath, this.fileSystem);
+        const existingTaskAssignmentContext = await readExistingTaskAssignmentContext(taskAssignmentStatePath, this.fileSystem);
         const skillRuntime = this.skillRuntimeEnabled
             ? await this.resolveSkillRuntimeBestEffort()
             : undefined;
@@ -548,34 +566,40 @@ export class FileChannelContextStore {
                     : {}),
             }
             : undefined;
-        const taskAssignmentContext = buildTaskAssignmentContextForTurn({
-            incomingMessageType: input.incomingMessageType,
-            incomingContent: input.incomingContent,
-        }, existingTaskAssignmentContext);
+        const taskAssignmentContext = input.taskAssignmentContextOverride
+            ?? buildTaskAssignmentContextForTurn({
+                incomingMessageType: input.incomingMessageType,
+                incomingContent: input.incomingContent,
+            }, existingTaskAssignmentContext);
         const workspaceResolution = await resolveTaskThreadWorkspaceContext({
             channelId: input.channelId,
             workspaceCollectionRootDir: this.workspaceCollectionRootDir,
             taskAssignmentContext,
-            existingResolvedWorkspace,
             taskReader: this.taskReader,
             taskResolutionTimeoutMs: this.taskResolutionTimeoutMs,
+            allowCrossAgentIndependentWorkspaceHandoff: this.allowCrossAgentIndependentWorkspaceHandoff,
+            resolveStableAgentId: this.resolveStableAgentId,
+            fileSystem: this.fileSystem,
         });
         const resolvedWorkspace = workspaceResolution.resolvedWorkspace;
+        const runtimeTaskAssignmentContext = workspaceResolution.taskAssignmentContext ?? taskAssignmentContext;
+        const persistedTaskAssignmentContext = input.taskAssignmentContextOverridePersistence === 'ephemeral'
+            ? existingTaskAssignmentContext
+            : runtimeTaskAssignmentContext;
         const runtimeSurface = buildRuntimeSurfaceForTurn({
             localhostGateway,
             collaboration: input.collaboration,
-            taskAssignmentContext: workspaceResolution.taskAssignmentContext ?? taskAssignmentContext,
+            taskAssignmentContext: runtimeTaskAssignmentContext,
         });
-        const payload = buildChannelContextPayload(input.channelId, runtimeSurface, input.collaborationOutcome, input.attentionSnapshot, input.compactionSnapshot, input.taskThreadCollaborationContract, input.collaborationCapabilities, input.missedCollaborationDiagnostic, skillRuntime, localhostGateway, workspaceResolution.taskAssignmentContext || resolvedWorkspace
+        const payload = buildChannelContextPayload(input.channelId, runtimeSurface, input.collaborationOutcome, input.attentionSnapshot, input.compactionSnapshot, input.taskThreadCollaborationContract, input.collaborationCapabilities, input.missedCollaborationDiagnostic, skillRuntime, localhostGateway, persistedTaskAssignmentContext || resolvedWorkspace
             ? {
-                ...(workspaceResolution.taskAssignmentContext
-                    ? { taskAssignmentContext: workspaceResolution.taskAssignmentContext }
+                ...(persistedTaskAssignmentContext
+                    ? { taskAssignmentContext: persistedTaskAssignmentContext }
                     : {}),
                 resolvedWorkspace,
             }
             : undefined);
         const gatewayCredential = buildBorgeeAgentGatewayCredential(input.channelId, issuedLocalhostGateway);
-        let resolvedWorkspaceMaterialized = false;
         let claudeProjectedBriefWritten = false;
         let payloadWritten = false;
         let gatewayCredentialWritten = false;
@@ -601,14 +625,24 @@ export class FileChannelContextStore {
         }
         try {
             await this.fileSystem.mkdir(directoryPath, { recursive: true, mode: 0o700 });
-            await this.fileSystem.mkdir(resolvedWorkspace.rootPath, { recursive: true, mode: 0o700 });
-            resolvedWorkspaceMaterialized = true;
+            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 });
+            }
             await pruneGatewayCredentialSidecars(this.fileSystem, directoryPath, gatewayCredential ? CHANNEL_GATEWAY_CREDENTIAL_FILENAME : undefined);
             if (!claudeProjectedBriefContent) {
                 await unlinkIfPresent(this.fileSystem, claudeProjectedBriefPath);
             }
             await this.fileSystem.writeFile(payloadPath, `${JSON.stringify(payload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
             payloadWritten = true;
+            if (persistedTaskAssignmentContext) {
+                const stagingTaskAssignmentStatePath = join(resolveTaskAssignmentStateDirectory(this.stateRootDir, input.channelId), `.task-assignment-state.${randomUUID()}.json`);
+                await this.fileSystem.writeFile(stagingTaskAssignmentStatePath, `${JSON.stringify({ taskAssignmentContext: persistedTaskAssignmentContext }, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+                await this.fileSystem.rename(stagingTaskAssignmentStatePath, taskAssignmentStatePath);
+            }
+            else {
+                await unlinkIfPresent(this.fileSystem, taskAssignmentStatePath);
+            }
             if (gatewayCredential) {
                 // Replaced atomically: a CLI invocation left over from an earlier turn must read either
                 // the old credential or the new one, never a missing or half-written file, because the
@@ -639,14 +673,23 @@ export class FileChannelContextStore {
             }
             const partialContext = {
                 directoryPath,
-                payload,
+                payload: {
+                    ...payload,
+                    ...(resolvedWorkspace.authority === 'task-execution-target' && runtimeTaskAssignmentContext?.active === true
+                        ? {
+                            resolvedWorkspace: buildTaskThreadScratchResolvedWorkspace(this.workspaceCollectionRootDir, input.channelId),
+                        }
+                        : {}),
+                },
                 claudeProjectedBriefPath: claudeProjectedBriefWritten ? claudeProjectedBriefPath : undefined,
                 claudeProjectedBriefHash: claudeProjectedBriefWritten ? preparedContext.claudeProjectedBriefHash : undefined,
                 payloadPath: payloadWritten ? payloadPath : undefined,
                 gatewayCredentialPath: gatewayCredentialWritten ? gatewayCredentialPath : undefined,
                 skillRuntime: payloadWritten ? skillRuntime : undefined,
                 localhostGateway: payloadWritten ? localhostGateway : undefined,
-                resolvedWorkspace: resolvedWorkspaceMaterialized ? resolvedWorkspace : undefined,
+                resolvedWorkspace: resolvedWorkspace.authority === 'task-execution-target' && runtimeTaskAssignmentContext?.active === true
+                    ? buildTaskThreadScratchResolvedWorkspace(this.workspaceCollectionRootDir, input.channelId)
+                    : resolvedWorkspace,
             };
             throw new ChannelContextPreparationError('failed to persist channel context payload', partialContext, { cause: error });
         }

package/dist/context/prompt.js

@@ -39,7 +39,9 @@ function buildLocalhostGatewayPromptLines(context) {
     if (!context.skillRuntime) {
         return lines;
     }
-    lines.push(context.taskAssignmentContext?.active === true
+    const taskThreadActive = context.taskAssignmentContext?.active === true
+        || context.runtimeSurface?.task.currentThread === 'task-assignment-thread';
+    lines.push(taskThreadActive
         ? 'This turn runs inside a task assignment thread.'
         : 'This turn runs in a parent channel, not a task thread.');
     if (context.runtimeSurface?.task.currentThread === 'parent-channel'
@@ -61,7 +63,7 @@ function buildLocalhostGatewayPromptLines(context) {
     const collaborationLive = context.localhostGateway.collaboration?.enabled === true
         && (context.collaborationTurnMode ?? 'ordinary') === 'ordinary';
     if (!collaborationLive) {
-        lines.push('Auxiliary collaboration commands (users, draft, send, mention) are not available this turn.');
+        lines.push('Auxiliary collaboration commands (draft, send, mention) are not available this turn.');
     }
     else if (context.collaborationTurnExecutionId) {
         lines.push(`Pass --turn-execution-id ${context.collaborationTurnExecutionId} on send, mention and draft.`);
@@ -77,13 +79,15 @@ function buildLocalhostGatewayPromptLines(context) {
 function buildTaskAssignmentPromptLines(params) {
     const isTaskAssignmentTurn = params.incomingMessageType?.trim() === 'task_assignment';
     const taskAssignmentContext = params.promptContext?.taskAssignmentContext;
-    if (!isTaskAssignmentTurn && taskAssignmentContext?.active !== true) {
+    const taskAssignmentThreadActive = taskAssignmentContext?.active === true
+        || params.promptContext?.runtimeSurface?.task.currentThread === 'task-assignment-thread';
+    if (!isTaskAssignmentTurn && !taskAssignmentThreadActive) {
         return [];
     }
     if (params.provider === 'claude'
         && params.forceInlineForClaude !== true
         && !isTaskAssignmentTurn
-        && taskAssignmentContext?.active === true) {
+        && taskAssignmentThreadActive) {
         return [];
     }
     const lines = isTaskAssignmentTurn
@@ -180,7 +184,7 @@ function buildClaudeProjectedBriefTurnDeltaLines(context) {
     const collaborationLive = context.localhostGateway.collaboration?.enabled === true
         && (context.collaborationTurnMode ?? 'ordinary') === 'ordinary';
     if (!collaborationLive) {
-        lines.push('Auxiliary collaboration commands (users, draft, send, mention) are not available this turn.');
+        lines.push('Auxiliary collaboration commands (draft, send, mention) are not available this turn.');
     }
     else if (context.collaborationTurnExecutionId) {
         lines.push(`Pass --turn-execution-id ${context.collaborationTurnExecutionId} on send, mention and draft.`);
@@ -291,8 +295,8 @@ function buildTurnControlAttentionLines(context) {
     const attentionLines = context?.attentionSnapshot
         ? [
             'Attention controls are projection-only host hints. They do not bypass server-side mention policy or widen message delivery.',
-            `To follow ordinary delivered human messages in this channel, add "attentionUpdate":"follow-channel".`,
-            `To stop follow-based human wake for this channel, add "attentionUpdate":"unfollow-channel".`,
+            `To pin a durable follow hint for ordinary delivered human messages in this channel, add "attentionUpdate":"follow-channel".`,
+            `To clear an explicit follow hint and return to server-policy wake for this channel, add "attentionUpdate":"unfollow-channel".`,
             `To mute ordinary delivered human wake while keeping explicit mentions and task assignments untouched, add "attentionUpdate":"mute-channel".`,
             `To set a durable channel-level attention hint, add "attentionUpdate":"claim-channel".`,
             ...(taskThreadAttentionAvailable

package/dist/context/resolved-workspace.d.ts

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

package/dist/context/resolved-workspace.js

@@ -3,8 +3,11 @@ function buildWorkspaceRootLine(context) {
     if (!resolvedWorkspace) {
         return undefined;
     }
-    if (resolvedWorkspace.authority === 'task') {
-        return `Writable task-isolated workspace root for this task thread: ${resolvedWorkspace.rootPath}.`;
+    if (resolvedWorkspace.authority === 'task-execution-target') {
+        return `Explicit execution local directory for this task thread: ${resolvedWorkspace.rootPath}.`;
+    }
+    if (resolvedWorkspace.authority === 'task-thread-scratch') {
+        return `Discussion-only scratch workspace for this task thread: ${resolvedWorkspace.rootPath}.`;
     }
     if (context.taskAssignmentContext?.active === true) {
         return `Writable workspace root inherited from this task thread's channel: ${resolvedWorkspace.rootPath}.`;
@@ -15,8 +18,13 @@ function buildWorkspaceModeLine(context) {
     if (context.taskAssignmentContext?.active !== true || !context.resolvedWorkspace) {
         return undefined;
     }
-    if (context.resolvedWorkspace.authority === 'task') {
-        return 'This task thread runs in a task-isolated workspace instead of inheriting the channel workspace.';
+    if (context.resolvedWorkspace.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.resolvedWorkspace.authority === 'task-thread-scratch') {
+        return context.resolvedWorkspace.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-workspace 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 workspace rather than using a task-isolated workspace.';
 }
@@ -24,8 +32,11 @@ function buildWorkspaceLocalityLine(context) {
     if (!context.resolvedWorkspace) {
         return undefined;
     }
-    if (context.resolvedWorkspace.authority === 'task') {
-        return 'This writable workspace is local to agents-host for this task thread. It does not imply that the target repository has already been checked out there.';
+    if (context.resolvedWorkspace.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.resolvedWorkspace.authority === 'task-thread-scratch') {
+        return 'This scratch workspace is host-managed only for discussion turns. It is not a bound project workspace and does not imply that any target repository is checked out there.';
     }
     if (context.taskAssignmentContext?.active === true) {
         return 'This writable workspace is local to agents-host for this task thread because the task inherits its channel workspace. It does not imply that the target repository has already been checked out there.';
@@ -36,14 +47,34 @@ function buildCopilotCwdLine(context) {
     if (!context.resolvedWorkspace) {
         return undefined;
     }
-    if (context.resolvedWorkspace.authority === 'task') {
-        return 'GitHub Copilot runs this turn with that task-isolated workspace as its real cwd.';
+    if (context.resolvedWorkspace.authority === 'task-execution-target') {
+        return 'GitHub Copilot runs this turn with that exact local directory as its real cwd.';
+    }
+    if (context.resolvedWorkspace.authority === 'task-thread-scratch') {
+        return 'GitHub Copilot runs this turn with that host-managed scratch workspace as its real cwd.';
     }
     if (context.taskAssignmentContext?.active === true) {
         return 'GitHub Copilot runs this turn with that inherited channel workspace as its real cwd.';
     }
     return 'GitHub Copilot runs this turn with that workspace as its real cwd.';
 }
+function buildDiscussionOnlyPermissionLine(context) {
+    if (context.resolvedWorkspace?.authority !== 'task-thread-scratch') {
+        return undefined;
+    }
+    return context.resolvedWorkspace.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-workspace 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.resolvedWorkspace?.authority === 'task-execution-target') {
+        return 'Precheck before switching this task thread into your own local workspace or project directory: the task\'s parent channel must have exactly one human user. Cross-agent independent-workspace handoff is also governed by this agents-host\'s local policy switch.';
+    }
+    return 'Before a human switches this task thread into their own local workspace or project directory, verify that the task\'s parent channel has exactly one human user; otherwise keep the thread discussion-only. Cross-agent independent-workspace handoff is also governed by this agents-host\'s local policy switch.';
+}
 export function buildResolvedWorkspaceGuidanceLines(context, provider) {
     if (!context?.resolvedWorkspace) {
         return [];
@@ -60,5 +91,16 @@ export function buildResolvedWorkspaceGuidanceLines(context, provider) {
     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 isDiscussionOnlyResolvedWorkspace(context) {
+    return context?.resolvedWorkspace?.authority === 'task-thread-scratch';
+}

package/dist/context/turn-preparation.js

@@ -127,6 +127,14 @@ export class ProviderTurnPreparer {
                     ...(input.incomingMessageType !== undefined && incomingContent !== undefined
                         ? { incomingContent }
                         : {}),
+                    ...(input.taskAssignmentContextOverride
+                        ? {
+                            taskAssignmentContextOverride: input.taskAssignmentContextOverride,
+                            ...(input.taskAssignmentContextOverridePersistence
+                                ? { taskAssignmentContextOverridePersistence: input.taskAssignmentContextOverridePersistence }
+                                : {}),
+                        }
+                        : {}),
                 };
                 channelContext = await this.channelContextStore.prepare(prepareInput);
             }

package/dist/gateway/localhost-gateway.js

@@ -550,11 +550,6 @@ class LoopbackLocalhostGatewayController {
                     return;
                 }
                 case 'users': {
-                    if (!binding.payload?.localhostGateway?.collaboration?.enabled) {
-                        this.sendJson(response, 404, { error: 'not_found' });
-                        this.recordAudit('not-found', 404, decision.path, request.method ?? 'GET', decision.binding);
-                        return;
-                    }
                     this.sendJson(response, 200, {
                         users: await this.controlPlane.listUsers(),
                     });
@@ -910,6 +905,8 @@ function mapGatewayControlPlaneError(error, fallbackReason) {
             // is broken, and it would retry the same bad call instead of correcting it.
             case 'bpp.task_property_key_unknown':
                 return new GatewayHttpError(400, { error: 'unknown_property_key' }, 'bad-request');
+            case 'bpp.task_property_write_forbidden':
+                return new GatewayHttpError(403, { error: 'forbidden' }, 'forbidden');
             case 'bpp.task_property_value_invalid':
                 return new GatewayHttpError(400, { error: 'invalid_property_value' }, 'bad-request');
             case 'bpp.task_property_value_too_long':

package/dist/local-config.js

@@ -2,7 +2,7 @@ import { promises as fs } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
 import { parseDocument, stringify } from 'yaml';
-import { assertProviderCompatibility, assertProviderCommandCompatibility, optionalNonEmptyString, optionalStringArray, parseCopilotSessionTtlMinutesValue, parseProviderIdleShutdownMinutesValue, requireNonEmptyString, resolveProvider, resolveProviderCommandConfig, } from './config.js';
+import { assertProviderCompatibility, assertProviderCommandCompatibility, optionalNonEmptyString, optionalStringArray, parseCopilotSessionTtlMinutesValue, parseBooleanValue, parseProviderIdleShutdownMinutesValue, requireNonEmptyString, resolveProvider, resolveProviderCommandConfig, } from './config.js';
 import { resolveLocalConfigAgentStateRoot } from './state-paths.js';
 const SUPPORTED_CONFIG_EXTENSIONS = new Set(['.json', '.yaml', '.yml']);
 export const DEFAULT_LOCAL_HOST_CONFIG_FILENAME = 'agents-host.yaml';
@@ -127,6 +127,10 @@ function parseProviderCommandOverrides(value, sourceLabel) {
     if (value.providerIdleShutdownMinutes !== undefined && value.providerIdleShutdownMinutes !== null) {
         overrides.providerIdleShutdownMinutes = parseProviderIdleShutdownMinutesValue(value.providerIdleShutdownMinutes, sourceLabel);
     }
+    if (value.allowCrossAgentIndependentWorkspaceHandoff !== undefined
+        && value.allowCrossAgentIndependentWorkspaceHandoff !== null) {
+        overrides.allowCrossAgentIndependentWorkspaceHandoff = parseBooleanValue(value.allowCrossAgentIndependentWorkspaceHandoff, 'allowCrossAgentIndependentWorkspaceHandoff', sourceLabel);
+    }
     return overrides;
 }
 function toAgentsDir(hostConfigPath, rawAgentsDir) {
@@ -599,6 +603,9 @@ function renderAgentConfigYaml(agent) {
     if (agent.providerIdleShutdownMinutes !== undefined) {
         config.providerIdleShutdownMinutes = agent.providerIdleShutdownMinutes;
     }
+    if (agent.allowCrossAgentIndependentWorkspaceHandoff !== undefined) {
+        config.allowCrossAgentIndependentWorkspaceHandoff = agent.allowCrossAgentIndependentWorkspaceHandoff;
+    }
     return stringify(config);
 }
 function buildManagedAgentSnapshot(host, stateRootBaseDir, sourcePath, agent) {
@@ -638,6 +645,9 @@ function resolveAgentProviderCommandConfig(hostDefaults, agent) {
         ...(agent.providerIdleShutdownMinutes !== undefined
             ? { providerIdleShutdownMinutes: agent.providerIdleShutdownMinutes }
             : {}),
+        ...(agent.allowCrossAgentIndependentWorkspaceHandoff !== undefined
+            ? { allowCrossAgentIndependentWorkspaceHandoff: agent.allowCrossAgentIndependentWorkspaceHandoff }
+            : {}),
     });
 }
 export async function loadLocalConfigSnapshot(hostConfigPath, deps = {}) {