@borgee/agents-host 0.2.56 → 0.2.62

package/dist/policy/copilot-permission.d.ts

@@ -10,6 +10,7 @@ export interface CopilotPermissionPolicyContext {
     auditSink?: AuthorizationAuditSinkLike;
     agentId?: string;
     channelId?: string;
+    toolPermissionMode?: 'default' | 'deny-all';
 }
 export declare function resolveCopilotPermissionResponse(context: CopilotPermissionPolicyContext): RequestPermissionResponse;
 export declare function createLegacyMissingAllowOptionError(): Error;

package/dist/policy/copilot-permission.js

@@ -84,6 +84,24 @@ function appendAuditRecord(context, effectiveDecision, reason, policyDecision) {
     });
 }
 export function resolveCopilotPermissionResponse(context) {
+    if (context.toolPermissionMode === 'deny-all') {
+        const rejectOption = resolveRejectOption(context.params.options);
+        const deniedDecision = rejectOption
+            ? {
+                outcome: 'selected',
+                optionId: rejectOption.optionId,
+                optionKind: rejectOption.kind,
+                reason: 'discussion-only-task-thread',
+                toolKind: normalizeToolKind(context.params.toolCall.kind),
+            }
+            : {
+                outcome: 'cancelled',
+                reason: 'discussion-only-task-thread',
+                toolKind: normalizeToolKind(context.params.toolCall.kind),
+            };
+        appendAuditRecord(context, deniedDecision, deniedDecision.reason, deniedDecision);
+        return decisionToResponse(deniedDecision);
+    }
     if (!context.gateEnabled) {
         const legacyOption = legacySelectPermissionOption(context.params.options);
         return {

package/dist/policy/gateway-authorization.js

@@ -33,7 +33,7 @@ function decodePathSegment(segment) {
 export function matchChannelRoute(pathname, allowCollaborationRoutes = false) {
     const resources = allowCollaborationRoutes
         ? '(bootstrap|me|history|draft|users|messages|tasks|current-task)'
-        : '(bootstrap|me|history|tasks|current-task)';
+        : '(bootstrap|me|history|users|tasks|current-task)';
     const match = new RegExp(`^/v1/channels/([^/]+)/${resources}$`).exec(pathname);
     if (!match) {
         return null;
@@ -112,7 +112,7 @@ function allowedMethodsForRoute(route, collaborationRoutesEnabled) {
 export function evaluateGatewayAuthorization(input) {
     const url = new URL(input.request.url ?? '/', input.baseUrl);
     const hiddenCollaborationRoute = !input.allowCollaborationRoutes
-        && ['draft', 'users', 'messages'].includes(matchChannelRoute(url.pathname, true)?.resource ?? '');
+        && ['draft', 'messages'].includes(matchChannelRoute(url.pathname, true)?.resource ?? '');
     if (hasVisibleHeader(input.request.headers.origin)) {
         return {
             reason: 'browser-origin-not-allowed',

package/dist/providers/claude/cli-client.d.ts

@@ -93,7 +93,7 @@ export declare class ClaudeCliClient {
     private invalidateSession;
     private closeSession;
     private rejectQueuedTurnsAfterSessionTaint;
-    private findChannelIdBySessionId;
+    private findChannelStateBySessionId;
     private currentSessionStoreAgentId;
     private ensureSessionStoreLoaded;
     private readPersistedSessionId;

package/dist/providers/claude/cli-client.js

@@ -1,5 +1,6 @@
 import { Readable, Writable } from 'node:stream';
 import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, resolve } from 'node:path';
 import spawn from 'cross-spawn';
@@ -11,6 +12,7 @@ import { AcpProgressCollector } from '../acp-progress-collector.js';
 import { readClaudeActivityMetadata } from './activity-metadata.js';
 import { resolveCopilotPermissionResponse } from '../../policy/copilot-permission.js';
 import { buildClaudeSessionPromptAppend } from '../../context/prompt.js';
+import { isDiscussionOnlyResolvedWorkspace } from '../../context/resolved-workspace.js';
 import { IDLE_BACKEND_SHUTDOWN_DISABLED_MS, IdleBackendShutdownScheduler, } from '../idle-backend-shutdown.js';
 const SESSION_TAINTED_ERRORS = new WeakSet();
 const IDLE_BACKEND_STOPPED_MESSAGE = 'Claude ACP backend stopped after idle timeout';
@@ -386,6 +388,22 @@ function hashSessionAppend(systemPromptAppend) {
     }
     return createHash('sha256').update(systemPromptAppend).digest('hex');
 }
+function resolveSkillManualContentHash(promptContext) {
+    const skillMarkdownPath = promptContext?.skillRuntime?.skillMarkdownPath;
+    if (!skillMarkdownPath) {
+        return undefined;
+    }
+    try {
+        return createHash('sha256')
+            .update(skillMarkdownPath)
+            .update('\0')
+            .update(readFileSync(skillMarkdownPath))
+            .digest('hex');
+    }
+    catch {
+        return `unreadable:${skillMarkdownPath}`;
+    }
+}
 function resolveSessionVisibilityKey(promptContext, systemPromptAppend, promptStrategy) {
     const resolvedPromptStrategy = resolveProjectionStrategy(promptStrategy);
     const explicitPromptStrategy = resolvedPromptStrategy === DEFAULT_PROJECTION_STRATEGY && promptStrategy == null
@@ -395,9 +413,11 @@ function resolveSessionVisibilityKey(promptContext, systemPromptAppend, promptSt
             : resolvedPromptStrategy;
     const additionalDirectories = resolveSessionAdditionalDirectories(promptContext);
     const sessionAppendHash = hashSessionAppend(systemPromptAppend);
+    const skillManualContentHash = resolveSkillManualContentHash(promptContext);
     const projectedBriefHash = promptContext?.claudeProjectedBriefHash;
     if (!additionalDirectories
         && !sessionAppendHash
+        && !skillManualContentHash
         && !projectedBriefHash
         && !promptContext?.gatewayCredentialPath
         && !explicitPromptStrategy) {
@@ -407,12 +427,14 @@ function resolveSessionVisibilityKey(promptContext, systemPromptAppend, promptSt
         return JSON.stringify({
             ...(additionalDirectories ? { additionalDirectories } : {}),
             sessionAppendHash,
+            ...(skillManualContentHash ? { skillManualContentHash } : {}),
             ...(projectedBriefHash ? { projectedBriefHash } : {}),
             ...(explicitPromptStrategy ? { promptStrategy: explicitPromptStrategy } : {}),
         });
     }
     return JSON.stringify({
         ...(additionalDirectories ? { additionalDirectories } : {}),
+        ...(skillManualContentHash ? { skillManualContentHash } : {}),
         ...(promptContext?.gatewayCredentialPath
             ? { gatewayCredentialPath: promptContext.gatewayCredentialPath }
             : {}),
@@ -721,6 +743,9 @@ export class ClaudeCliClient {
                     state.activeTurn = turn;
                     try {
                         state.cwd = this.resolveSessionCwd(turn.preparedTurn.promptContext);
+                        state.toolPermissionMode = isDiscussionOnlyResolvedWorkspace(turn.preparedTurn.promptContext)
+                            ? 'deny-all'
+                            : 'default';
                         const sessionPromptAppend = resolveTurnSessionPromptAppend(turn.preparedTurn);
                         state.visibilityKey = resolveSessionVisibilityKey(turn.preparedTurn.promptContext, sessionPromptAppend, turn.preparedTurn.projectionStrategy);
                         await this.ensureStarted();
@@ -999,13 +1024,15 @@ export class ClaudeCliClient {
         this.shutdownPromise = this.shutdownBackend(error);
     }
     handlePermissionRequest(params) {
+        const state = this.findChannelStateBySessionId(params.sessionId);
         return resolveCopilotPermissionResponse({
             gateEnabled: true,
             policyMode: 'enforce',
             params,
             logger: this.logger,
             agentId: this.resolveSessionStoreAgentId()?.trim() || undefined,
-            channelId: this.findChannelIdBySessionId(params.sessionId),
+            channelId: state?.channelId,
+            toolPermissionMode: state?.toolPermissionMode ?? 'default',
         });
     }
     invalidateSession(channelId, state, session) {
@@ -1057,10 +1084,10 @@ export class ClaudeCliClient {
         }
         state.queue.length = 0;
     }
-    findChannelIdBySessionId(sessionId) {
+    findChannelStateBySessionId(sessionId) {
         for (const state of this.channels.values()) {
             if (state.session?.sessionId === sessionId) {
-                return state.channelId;
+                return state;
             }
         }
         return undefined;

package/dist/providers/codex/cli-client.d.ts

@@ -108,6 +108,8 @@ export declare class CodexCliClient {
     private failAll;
     private closeSession;
     private clearIdleTimer;
+    private handlePermissionRequest;
+    private findChannelStateBySessionId;
     private reconcileIdleChannelState;
     private ensureSessionStoreLoaded;
     private readPersistedSessionId;

package/dist/providers/codex/cli-client.js

@@ -8,6 +8,8 @@ import { HostLogger, summarizeChildStderr, summarizeError } from '../../debug.js
 import { AcpProgressCollector } from '../acp-progress-collector.js';
 import { assertCodexProjectDocumentSize, buildCodexProjectDocument } from './project-doc.js';
 import { isGatewayCredentialSidecarBasename } from '../../context/injection.js';
+import { isDiscussionOnlyResolvedWorkspace } from '../../context/resolved-workspace.js';
+import { resolveCopilotPermissionResponse } from '../../policy/copilot-permission.js';
 import { IDLE_BACKEND_SHUTDOWN_DISABLED_MS, IdleBackendShutdownScheduler, } from '../idle-backend-shutdown.js';
 const SESSION_TAINTED_ERRORS = new WeakSet();
 const DEFAULT_IDLE_SESSION_TTL_MS = 2 * 24 * 60 * 60 * 1000;
@@ -193,26 +195,6 @@ function markSessionTainted(error) {
 function isSessionTainted(error) {
     return error instanceof Error && SESSION_TAINTED_ERRORS.has(error);
 }
-function createPermissionResponse(params) {
-    const options = Array.isArray(params.options) ? params.options : [];
-    const preferredKinds = ['allow_once', 'allow_always', 'reject_once', 'reject_always'];
-    for (const kind of preferredKinds) {
-        const match = options.find((option) => option.kind === kind);
-        if (match) {
-            return {
-                outcome: {
-                    outcome: 'selected',
-                    optionId: match.optionId,
-                },
-            };
-        }
-    }
-    return {
-        outcome: {
-            outcome: 'cancelled',
-        },
-    };
-}
 function resolveBundledCodexAdapterPath() {
     return require.resolve('@agentclientprotocol/codex-acp');
 }
@@ -423,7 +405,7 @@ export class CodexCliClient {
         const stream = this.runtime.ndJsonStream(output, input);
         const app = this.runtime
             .client({ name: 'borgee-agents-host' })
-            .onRequest(this.runtime.methods.client.session.requestPermission, ({ params }) => (createPermissionResponse(params)));
+            .onRequest(this.runtime.methods.client.session.requestPermission, ({ params }) => (this.handlePermissionRequest(params)));
         const connection = app.connect(stream);
         this.connection = connection;
         void connection.closed.then(() => {
@@ -487,6 +469,9 @@ export class CodexCliClient {
                     state.activeTurn = turn;
                     try {
                         state.cwd = await this.resolveSessionCwd(turn.preparedTurn.promptContext);
+                        state.toolPermissionMode = isDiscussionOnlyResolvedWorkspace(turn.preparedTurn.promptContext)
+                            ? 'deny-all'
+                            : 'default';
                         const projectedPromptContext = await this.refreshProjectedPromptContextBestEffort(turn.channelId, turn.preparedTurn.promptContext);
                         state.additionalDirectories = this.resolveSessionAdditionalDirectories(projectedPromptContext);
                         state.visibilityKey = this.resolveSessionVisibilityKey(projectedPromptContext);
@@ -953,6 +938,25 @@ export class CodexCliClient {
         clearTimeout(state.idleTimer);
         state.idleTimer = undefined;
     }
+    handlePermissionRequest(params) {
+        const state = this.findChannelStateBySessionId(params.sessionId);
+        return resolveCopilotPermissionResponse({
+            gateEnabled: true,
+            policyMode: 'enforce',
+            params,
+            logger: this.logger,
+            channelId: state?.channelId,
+            toolPermissionMode: state?.toolPermissionMode ?? 'default',
+        });
+    }
+    findChannelStateBySessionId(sessionId) {
+        for (const state of this.channels.values()) {
+            if (state.session?.sessionId === sessionId) {
+                return state;
+            }
+        }
+        return undefined;
+    }
     reconcileIdleChannelState(channelId, state) {
         if (this.channels.get(channelId) !== state) {
             return;

package/dist/providers/copilot/cli-client.d.ts

@@ -103,7 +103,7 @@ export declare class CopilotCliClient {
     private closeSession;
     private rejectQueuedTurnsAfterSessionTaint;
     private clearIdleTimer;
-    private findChannelIdBySessionId;
+    private findChannelStateBySessionId;
     private reconcileIdleChannelState;
     private ensureSessionStoreLoaded;
     private readPersistedSessionId;

package/dist/providers/copilot/cli-client.js

@@ -4,6 +4,7 @@ import { PROTOCOL_VERSION, client, methods, ndJsonStream, } from '@agentclientpr
 import { HostLogger, summarizeChildStderr, summarizeError } from '../../debug.js';
 import { AcpProgressCollector } from '../acp-progress-collector.js';
 import { resolveCopilotPermissionResponse } from '../../policy/copilot-permission.js';
+import { isDiscussionOnlyResolvedWorkspace } from '../../context/resolved-workspace.js';
 import { IDLE_BACKEND_SHUTDOWN_DISABLED_MS, IdleBackendShutdownScheduler, } from '../idle-backend-shutdown.js';
 const SESSION_TAINTED_ERRORS = new WeakSet();
 const DEFAULT_IDLE_SESSION_TTL_MS = 2 * 24 * 60 * 60 * 1000;
@@ -407,6 +408,9 @@ export class CopilotCliClient {
                     state.activeTurn = turn;
                     try {
                         state.cwd = await this.resolveSessionCwd(turn.preparedTurn.promptContext);
+                        state.toolPermissionMode = isDiscussionOnlyResolvedWorkspace(turn.preparedTurn.promptContext)
+                            ? 'deny-all'
+                            : 'default';
                         await this.ensureStarted();
                         await this.recycleSessionIfCwdChanged(channelId, state);
                         const session = await this.getOrCreateSession(channelId, state);
@@ -666,6 +670,7 @@ export class CopilotCliClient {
         return Promise.race([promise, this.fatalPromise]);
     }
     handlePermissionRequest(params) {
+        const state = this.findChannelStateBySessionId(params.sessionId);
         return resolveCopilotPermissionResponse({
             gateEnabled: this.permissionPolicy.gateEnabled ?? false,
             policyMode: this.permissionPolicy.policyMode ?? 'audit-only',
@@ -673,7 +678,8 @@ export class CopilotCliClient {
             logger: this.logger,
             auditSink: this.permissionPolicy.auditSink,
             agentId: this.resolveSessionStoreAgentId()?.trim() || undefined,
-            channelId: this.findChannelIdBySessionId(params.sessionId),
+            channelId: state?.channelId,
+            toolPermissionMode: state?.toolPermissionMode ?? 'default',
         });
     }
     failAll(error) {
@@ -761,10 +767,10 @@ export class CopilotCliClient {
         clearTimeout(state.idleTimer);
         state.idleTimer = undefined;
     }
-    findChannelIdBySessionId(sessionId) {
+    findChannelStateBySessionId(sessionId) {
         for (const state of this.channels.values()) {
             if (state.session?.sessionId === sessionId) {
-                return state.channelId;
+                return state;
             }
         }
         return undefined;

package/dist/providers/create-provider.d.ts

@@ -8,7 +8,7 @@ interface CreateProviderOptions {
     compatibilityGates?: ReadonlySet<string>;
     localhostGateway?: LocalhostGatewayContextPublisher;
     authorizationAuditSink?: AuthorizationAuditSinkLike;
-    controlPlane?: Pick<ChatControlPlane, 'getTask' | 'listChannels' | 'listTasks'>;
+    controlPlane?: Pick<ChatControlPlane, 'getTask' | 'listChannels' | 'listTasks' | 'listUsers'>;
 }
 export declare function createProvider(config: ProviderRuntimeConfig, debugLogger?: DebugLogger, options?: CreateProviderOptions): ProviderAdapter;
 export {};

package/dist/providers/create-provider.js

@@ -135,6 +135,8 @@ export function createProvider(config, debugLogger, options = {}) {
                 ? options.localhostGateway
                 : undefined,
             taskReader: options.controlPlane,
+            allowCrossAgentIndependentWorkspaceHandoff: config.allowCrossAgentIndependentWorkspaceHandoff,
+            resolveStableAgentId: config.resolveStableAgentId,
         })
         : undefined;
     const resolveInternalProjection = () => resolveInternalProjectionStrategy();

package/dist/types.d.ts

@@ -10,6 +10,12 @@ export interface ProviderCommandConfig {
     copilotSessionTtlMinutes: number;
     /** Minutes a provider's shared ACP adapter process may stay idle before it is shut down; `0` keeps it resident. */
     providerIdleShutdownMinutes: number;
+    /**
+     * Whether this agents-host may let a hosted agent enter an independent
+     * execution.local_directory workspace for a task thread created by another
+     * agent. Undefined keeps the default allow behavior.
+     */
+    allowCrossAgentIndependentWorkspaceHandoff?: boolean;
 }
 export interface ProviderRuntimeConfig extends ProviderCommandConfig {
     provider: ProviderKind;
@@ -286,6 +292,8 @@ export interface ProviderInput {
     taskThreadCollaborationContract?: TaskThreadCollaborationContract;
     collaborationCapabilities?: CollaborationCapabilityDeclaration;
     missedCollaborationDiagnostic?: MissedCollaborationDiagnostic;
+    taskAssignmentContextOverride?: TaskAssignmentThreadContext;
+    taskAssignmentContextOverridePersistence?: 'persist' | 'ephemeral';
 }
 export interface ProviderProtocolContext {
     anchorMessageId: string;
@@ -334,12 +342,17 @@ export interface ChannelResolvedWorkspaceContext {
     owningChannelId: string;
     rootPath: string;
 }
-export interface TaskResolvedWorkspaceContext {
-    authority: 'task';
+export interface TaskThreadScratchWorkspaceContext {
+    authority: 'task-thread-scratch';
+    rootPath: string;
+    reason?: 'missing-or-invalid-execution-target' | 'cross-agent-independent-workspace-disabled';
+}
+export interface TaskExecutionTargetResolvedWorkspaceContext {
+    authority: 'task-execution-target';
     taskId: string;
     rootPath: string;
 }
-export type ResolvedWorkspaceContext = ChannelResolvedWorkspaceContext | TaskResolvedWorkspaceContext;
+export type ResolvedWorkspaceContext = ChannelResolvedWorkspaceContext | TaskThreadScratchWorkspaceContext | TaskExecutionTargetResolvedWorkspaceContext;
 export interface RuntimeSurface {
     schemaVersion: 1;
     turnMode: ProviderCollaborationTurnMode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@borgee/agents-host",
-  "version": "0.2.56",
+  "version": "0.2.62",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -35,7 +35,7 @@
     "tsx": "^4.20.5",
     "typescript": "^5.9.3",
     "vitest": "^4.1.5",
-    "@borgee/plugin-sdk": "0.10.0"
+    "@borgee/plugin-sdk": "0.12.0"
   },
   "scripts": {
     "predev": "pnpm --filter @borgee/plugin-sdk build",

package/skills/borgee-agent/SKILL.md

@@ -64,15 +64,15 @@ Everything below writes that leading interpreter and script path as `borgee-agen
 
 On `task get`, `task update`, `task set-property` and `task delete-property` the task id is an optional leading positional. Inside a task thread, omitting it addresses this thread's own task: the host's published binding names it, and where the host published none the gateway scans the parent channel's visible tasks for this thread instead — so pass the id explicitly when that scan cannot land on a single task. `task list` and `task create` are refused inside a task thread; they belong to the parent channel. In a parent channel every one of those ids is required, and omitting it answers `not_found`.
 
-The keys `task set-property` and `task delete-property` accept are a closed set, and a value has a size limit: see `references/task-properties.md`. In this slice, `workspace.mode` is the formal task-workspace switch: `inherit` keeps a task thread on its channel workspace, while `isolated` moves that task thread onto its own task workspace.
+The keys `task set-property` and `task delete-property` accept are a closed set, and a value has a size limit: see `references/task-properties.md`. In this slice, `workspace.mode` still records the host-managed scratch isolation hint, while `execution.local_directory` is a human-owned execution target that hosted agents may read but must not retarget through the generic task-property rail.
 
 ## What is available on a turn
 
-`health`, `bootstrap`, `whoami`, `history` and the task commands are live on every turn whose prompt names a gateway credential file.
+`health`, `bootstrap`, `whoami`, `history`, `users` and the task commands are live on every turn whose prompt names a gateway credential file.
 
-`users`, `draft`, `send` and `mention` are live only where collaboration is enabled; the prompt says when it is not, and the gateway answers `not_found` for all four. `draft`, `send` and `mention` additionally need the turn execution id the prompt carries: no command returns that id and the gateway credential file does not hold it.
+`draft`, `send` and `mention` are live only where collaboration is enabled; the prompt says when they are not, and the gateway answers `not_found` for all three. They additionally need the turn execution id the prompt carries: no command returns that id and the gateway credential file does not hold it.
 
-A `not_found` from `draft` therefore has two readings — collaboration is off, or the host holds no draft for this turn yet — so take it as an answer about the draft, not as evidence that `users`, `send` and `mention` have gone.
+A `not_found` from `draft` therefore has two readings — collaboration is off, or the host holds no draft for this turn yet — so take it as an answer about the draft, not as evidence that `users`, `send` and `mention` have all gone.
 
 Whether you are in a parent channel or inside a task assignment thread is in the prompt too, and it decides which task grammar above applies.
 

package/skills/borgee-agent/references/errors.md

@@ -22,8 +22,8 @@
 | 429 `collaboration_target_cooldown` | The same reply target or mention set was addressed moments ago. | Do not repeat it. |
 | 404 `not_found` on `task get` / `task update` / a property command with no task id | You are not inside a task thread, so there is no current task to resolve. | Pass the task id. |
 | 404 `not_found` on a task command with a task id | The task does not exist, or belongs to another channel. | Check the id with `task list`. |
-| 404 `not_found` on `users`, `send`, `mention` | Collaboration is not enabled for this turn, so those commands do not exist. | Do not use them; the turn prompt says when they are live. |
-| 404 `not_found` on `draft` | Either collaboration is not enabled for this turn, or the host holds no draft for it yet — a draft exists only once the turn has produced visible reply text. | Not a verdict on the other collaboration commands: `users`, `send` and `mention` may well answer on this same turn. Carry on and read the draft later if you still need it. |
+| 404 `not_found` on `send`, `mention` | Collaboration is not enabled for this turn, so those commands do not exist. | Do not use them; the turn prompt says when they are live. |
+| 404 `not_found` on `draft` | Either collaboration is not enabled for this turn, or the host holds no draft for it yet — a draft exists only once the turn has produced visible reply text. | Not a verdict on the other collaboration commands: `users` may still answer on this same turn, and `send` / `mention` may answer once collaboration is live. Carry on and read the draft later if you still need it. |
 | 404 `bootstrap_unavailable` | The host has not published this turn's channel payload yet. | Retry the read once; if it persists, continue without it. |
 | 400 `task_thread_collection_not_allowed` | `task list` or `task create` inside a task thread. | Those belong to the parent channel. |
 | 400 `multiline_message_body_not_allowed`, `message_body_too_verbose` | An auxiliary send must be one line of at most 12 words, and the `<@id>` the CLI appends counts as one of them — each extra `--mention` costs another. | Shorten it to a single-line notice. |

package/skills/borgee-agent/references/task-properties.md

@@ -1,6 +1,6 @@
 # Task properties
 
-A task property associates a task with something that lives outside it, or with a closed task-level runtime choice. Use one to record what a reader would otherwise have to hunt for in the thread — the pull request that implements the task, the issue it came from, or the task workspace mode it should run with.
+A task property associates a task with something that lives outside it, or with a closed task-level runtime choice. Use one to record what a reader would otherwise have to hunt for in the thread — the pull request that implements the task, the issue it came from, or the execution metadata a human attached to it.
 
 Read them back with `task get`: every task response carries a `properties` object, `{}` when the task has none.
 
@@ -21,7 +21,8 @@ The key set is closed; writing an unregistered key is rejected with `unknown_pro
 | --- | --- |
 | `link.pr` | The pull request that implements this task. Set it as soon as the PR exists, not at the end. |
 | `link.issue` | The issue or ticket the task originates from. |
-| `workspace.mode` | The task workspace binding for task threads. `inherit` keeps the task on its channel workspace. `isolated` switches it to its task-isolated workspace. Deleting the key returns to the default `inherit` behavior. |
+| `execution.local_directory` | The explicit local directory a human selected as this task thread's execution target. New tasks default it from the immediately previous task thread in the same channel: if that previous task carried a value, the new task inherits it; if the previous task left it unset, the new task also starts unset. Hosted agents can read it, but the generic agent task-property rail must not write it. Humans set it through the existing user rail. The extra single-human-user guard applies when a task thread is about to switch into somebody's own local workspace/project directory, not as a blanket rule on every property write. A separate agents-host local policy switch governs whether a hosted agent may enter an independent workspace for a task thread that originated from another agent's task. |
+| `workspace.mode` | The host-managed scratch-workspace isolation hint for task threads. `inherit` keeps the scratch workspace on the shared host-managed path, while `isolated` reserves the task's own host-managed scratch workspace shape. Deleting the key returns to the default `inherit` behavior. |
 | `agent.session_id` | Do not write this. It is registered, so a write is accepted and lands — overwriting the host's record of which provider session worked this task. The host writes it itself after each turn. |
 
 ## One key per call
@@ -30,4 +31,4 @@ Each call writes exactly one key, and that is what makes it safe to write a prop
 
 ## Value
 
-A value is a plain string of at most 8 KiB; a longer one is rejected with `property_value_too_long`. It is a reference — a URL, an identifier — never a document. Some registered keys are closed enums: `workspace.mode` accepts only `inherit` or `isolated`.
+A value is a plain string of at most 8 KiB; a longer one is rejected with `property_value_too_long`. It is a reference — a URL, an identifier — never a document. `execution.local_directory` must be a non-empty absolute path string. Before a human lets a task thread switch into their own local workspace/project directory, first verify that the task's parent channel has exactly one human user; otherwise keep the thread discussion-only. If a hosted agent is trying to enter an independent workspace for a task thread that originated from another agent's task, this agents-host's local handoff policy must also allow it. Some registered keys are closed enums: `workspace.mode` accepts only `inherit` or `isolated`.