@qduc/term2 0.11.1 → 0.12.0

package/dist/tools/system/shell.js

@@ -8,17 +8,17 @@ import { logValidationError as logValidationErrorUtil } from '../../utils/shell/
 import { executeShellCommand } from '../../utils/shell/execute-shell.js';
 import { setTrimConfig, getTrimConfig, DEFAULT_TRIM_CONFIG, } from '../../utils/output/output-trim.js';
 import { formatShellExecutionOutput } from '../../utils/shell/shell-output.js';
-import { coerceToText, getOutputText, normalizeToolArguments, createBaseMessage, getCallIdFromItem, } from '../format-helpers.js';
+import { coerceToText, getOutputText, normalizeToolArguments, createBaseMessage, getCallIdFromItem, safeJsonParse, } from '../format-helpers.js';
 import { ensureRtkInstalled, isRtkSupportedCommand, wrapWithRtk } from '../../services/rtk-service.js';
 import { shouldPreferPatchEditingModel } from '../../lib/tool-selection-policy.js';
+import { HarnessInvariantError } from '../../lib/harness-invariant-error.js';
 import { createSandboxEnvironment } from '../../utils/shell/sandbox/sandbox-env.js';
 import { SANDBOX_ESCAPE_INSTRUCTION, createSandboxRuntimeConfig, } from '../../utils/shell/sandbox/sandbox-policy.js';
 import { getDefaultShellSandboxRunner } from '../../utils/shell/sandbox/shell-sandbox-runner.js';
 import { DETAILED_DENIED_READ_INSTRUCTION } from '../../utils/shell/sandbox/denied-read-detector.js';
-import { deniedReadStore, executionOverrideStore, getProjectAllowReadStore, } from '../../utils/shell/sandbox/denied-read-stores.js';
+import { getProjectAllowReadStore } from '../../utils/shell/sandbox/denied-read-stores.js';
 import { classifySandboxFailure } from '../../utils/shell/sandbox/sandbox-failure-classifier.js';
 import { createDockerHostControl, DOCKER_HOST_CONTROL_RETRY_INSTRUCTION, } from '../../utils/shell/sandbox/docker-host-control.js';
-import { configureDockerHostControlGrants, consumeDockerHostControlDenial, consumeDockerHostControlOnce, recordDockerHostControlDenial, requiresDockerHostControlApproval, hasDockerHostControlProject, hasDockerHostControlSession, } from '../../utils/shell/sandbox/docker-host-control-grants.js';
 const shellSandboxModeSchema = z.enum(['default', 'unsandboxed']).optional().default('default');
 const shellParametersSchema = z.object({
     command: z.string().min(1).describe('Single shell command to execute.'),
@@ -33,9 +33,61 @@ const shellParametersSchema = z.object({
         .optional()
         .describe('Optional maximum output length in characters for each command. Outputs exceeding this length will be trimmed. Defaults to 40000 characters if not specified.'),
     sandbox: shellSandboxModeSchema.describe('Run mode. default runs inside the sandbox when available. unsandboxed requires explicit user approval.'),
+    background: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Run locally in the background and return a job ID immediately. Defaults to false.'),
 });
 // Re-export trim utilities for backwards compatibility
 export { setTrimConfig, getTrimConfig, DEFAULT_TRIM_CONFIG };
+const getBackgroundShellJobParameters = z.object({
+    job_id: z.string().min(1).describe('The background shell job ID.'),
+});
+function backgroundShellJobResponse(job) {
+    return {
+        jobId: job.id,
+        command: job.command,
+        status: job.status,
+        ...(job.result === undefined ? {} : { output: job.result.output }),
+        ...(job.error === undefined ? {} : { error: job.error }),
+    };
+}
+/**
+ * Root composition registers these alongside `shell` when it supplies the
+ * session-owned registry. Keeping them here makes the model contract and its
+ * shell lifecycle use the same job representation.
+ */
+export function createBackgroundShellJobToolDefinitions(registry) {
+    return {
+        get: {
+            name: 'get_shell_job',
+            description: 'Get the non-blocking status and bounded output of a background shell job.',
+            parameters: getBackgroundShellJobParameters,
+            needsApproval: () => false,
+            execute: ({ job_id }) => {
+                const job = registry.get(job_id);
+                return JSON.stringify(job ? backgroundShellJobResponse(job) : { jobId: job_id, status: 'not_found' });
+            },
+            formatCommandMessage: () => [],
+        },
+        cancel: {
+            name: 'cancel_shell_job',
+            description: 'Request cancellation of a running background shell job without waiting for it to exit.',
+            parameters: getBackgroundShellJobParameters,
+            needsApproval: () => false,
+            execute: ({ job_id }) => {
+                const job = registry.get(job_id);
+                if (!job)
+                    return JSON.stringify({ jobId: job_id, status: 'not_found' });
+                registry.cancel(job_id);
+                const current = registry.get(job_id);
+                return JSON.stringify(backgroundShellJobResponse(current ?? job));
+            },
+            formatCommandMessage: () => [],
+        },
+    };
+}
 /**
  * Strip redundant 'cd <path> &&' prefix if it targets the current working directory
  */
@@ -98,11 +150,12 @@ export const formatShellCommandMessage = (item, index, toolCallArgumentsById) =>
         if (typeof args === 'string') {
             return args;
         }
-        const directCommand = coerceCommandText(args?.command);
+        const argsRecord = args && typeof args === 'object' && !Array.isArray(args) ? args : {};
+        const directCommand = coerceCommandText(argsRecord.command);
         if (directCommand) {
             return directCommand;
         }
-        const commandsValue = args?.commands;
+        const commandsValue = argsRecord.commands;
         if (typeof commandsValue === 'string') {
             return commandsValue;
         }
@@ -122,6 +175,23 @@ export const formatShellCommandMessage = (item, index, toolCallArgumentsById) =>
         return 'Unknown command';
     })();
     const outputText = getOutputText(item);
+    const backgroundRequested = args !== null && typeof args === 'object' && !Array.isArray(args) && args.background === true;
+    const launchAcknowledgement = backgroundRequested
+        ? safeJsonParse(outputText)
+        : null;
+    if (launchAcknowledgement?.status === 'running' &&
+        typeof launchAcknowledgement.jobId === 'string' &&
+        launchAcknowledgement.jobId.length > 0) {
+        return [
+            createBaseMessage(item, index, 0, false, {
+                command,
+                output: `Background job ${launchAcknowledgement.jobId} is running.`,
+                success: true,
+                toolName: 'shell',
+                toolArgs: args,
+            }),
+        ];
+    }
     // Check if this is an error message (doesn't start with expected status formats)
     const firstLine = outputText.split('\n')[0]?.trim() || '';
     const isErrorMessage = firstLine.includes('error') ||
@@ -173,8 +243,9 @@ const getShellDescription = (searchViaShell) => 'Execute a single shell command.
 const SHELL_DESCRIPTION_ORCHESTRATOR = 'Execute a single shell command. Directly inspect, test, or perform a small clear operation when that is the most efficient path. By default, local shell commands run inside the sandbox when available. Use sandbox: "unsandboxed" only for network or outside-host access; it requires explicit user approval and must be run by the main agent. Long output is truncated, the full output is saved to a file; ' +
     'delegate complex, risky, or separable work when specialization, context compression, or safe parallelism provides meaningful leverage.';
 export function createShellToolDefinition(deps) {
-    const { loggingService, settingsService, executionContext, rtkInstaller = ensureRtkInstalled, executeShellCommandImpl = executeShellCommand, shellSandboxRunner = getDefaultShellSandboxRunner(), dockerHostControlFactory = createDockerHostControl, orchestratorMode = false, searchViaShell: searchViaShellExplicit, } = deps;
-    configureDockerHostControlGrants(settingsService);
+    const { loggingService, settingsService, executionContext, rtkInstaller = ensureRtkInstalled, executeShellCommandImpl = executeShellCommand, shellSandboxRunner = getDefaultShellSandboxRunner(), dockerHostControlFactory = createDockerHostControl, orchestratorMode = false, searchViaShell: searchViaShellExplicit, postExecuteDeniedRead = false, sessionAccess, nestedCompatibility, backgroundShellRegistry, } = deps;
+    const deniedReadByCallId = new Map();
+    const overrideByCallId = new Map();
     // Create command logger function with dependencies
     const logValidationError = (message) => logValidationErrorUtil(settingsService, message);
     const searchViaShellSetting = settingsService.get('app.searchViaShell') ?? 'auto';
@@ -203,17 +274,22 @@ export function createShellToolDefinition(deps) {
                 const cwd = executionContext?.getCwd() || process.cwd();
                 const sessionId = getConversationSessionId(context);
                 const sandboxEnabled = isSandboxEnabled();
-                const dockerHostControlRequested = sandboxEnabled && requiresDockerHostControlApproval(params.command);
+                const dockerHostControlRequested = sandboxEnabled &&
+                    (sessionAccess?.requiresDockerApproval(params.command) ??
+                        nestedCompatibility?.docker.requiresApproval(sessionId, params.command) ??
+                        false);
                 if (dockerHostControlRequested &&
-                    !hasDockerHostControlProject(cwd) &&
-                    (!sessionId || !hasDockerHostControlSession(sessionId, cwd))) {
+                    !(sessionAccess?.hasDockerProject(cwd) ?? nestedCompatibility?.docker.hasProject(cwd) ?? false) &&
+                    !(sessionAccess?.hasDockerSessionGrant(cwd) ??
+                        (sessionId ? nestedCompatibility?.docker.hasSession(sessionId, cwd) : false) ??
+                        false)) {
                     return true;
                 }
                 const sshService = executionContext?.getSSHService();
                 if (!sshService && sandboxEnabled) {
                     // If a previous sandboxed run denied a read for this command, require
                     // approval so the user can allow/remember the path or escape unsandboxed.
-                    if (deniedReadStore.peek(params.command)) {
+                    if (!postExecuteDeniedRead && nestedCompatibility?.deniedReads.peek(params.command)) {
                         return true;
                     }
                     const availability = await shellSandboxRunner.availability();
@@ -236,20 +312,34 @@ export function createShellToolDefinition(deps) {
                 logValidationError(`Validation failed: ${errorMessage}`);
                 loggingService.error('Shell tool validation error', {
                     error: errorMessage,
-                    commands: [params.command.substring(0, 100)],
+                    // params.command may itself be why we're in this catch (e.g. undefined
+                    // after a malformed tool call), so don't re-dereference it unguarded.
+                    commands: [typeof params.command === 'string' ? params.command.substring(0, 100) : String(params.command)],
                 });
                 return true; // fail-safe: require approval on validation errors
             }
         },
-        execute: async ({ command, timeout_ms, max_output_length, sandbox = 'default' }, _context, details) => {
+        execute: async ({ command, timeout_ms, max_output_length, sandbox = 'default', background = false }, _context, details) => {
+            const toolCallId = details?.toolCall?.callId;
+            // The application run loop owns turn cancellation on its typed context;
+            // SDK details only identify the provider tool call.
+            const toolSignal = _context?.signal ??
+                details?.signal;
             const cwd = executionContext?.getCwd() || process.cwd();
             const sessionId = getConversationSessionId(_context);
             const sandboxEnabled = isSandboxEnabled();
-            const dockerHostControlRequested = sandboxEnabled && requiresDockerHostControlApproval(command);
+            const dockerHostControlRequested = sandboxEnabled &&
+                (sessionAccess?.requiresDockerApproval(command) ??
+                    nestedCompatibility?.docker.requiresApproval(sessionId, command) ??
+                    false);
             const hasDockerGrant = dockerHostControlRequested &&
-                (hasDockerHostControlProject(cwd) ||
-                    (sessionId &&
-                        (hasDockerHostControlSession(sessionId, cwd) || consumeDockerHostControlOnce(sessionId, command))));
+                (sessionAccess?.hasDockerGrant(command, cwd) ??
+                    (nestedCompatibility
+                        ? nestedCompatibility.docker.hasProject(cwd) ||
+                            (sessionId &&
+                                (nestedCompatibility.docker.hasSession(sessionId, cwd) ||
+                                    nestedCompatibility.docker.consumeOnce(sessionId, command)))
+                        : false));
             if (dockerHostControlRequested && !hasDockerGrant) {
                 return 'Error: Docker host control requires explicit approval.';
             }
@@ -257,54 +347,81 @@ export function createShellToolDefinition(deps) {
                 return `Error: plan mode is read-only. Command not executed: ${command}`;
             }
             const sshService = executionContext?.getSSHService();
+            if (background && !backgroundShellRegistry) {
+                return 'Error: Background shell execution is unavailable in this session.';
+            }
+            if (background && sshService) {
+                return 'Error: Background shell execution is only available for local sessions.';
+            }
             const previousCorrelationId = loggingService.getCorrelationId();
             const correlationId = randomUUID();
             const startedAt = Date.now();
             let sandboxed = false;
             let dockerHostControl;
-            // Set correlation ID for tracking related operations
-            loggingService.setCorrelationId(correlationId);
+            let backgroundCleanupDeferred = false;
+            let transferred = false;
+            const ownsCorrelationId = !background;
+            let foregroundCorrelationRestored = false;
+            const restoreForegroundCorrelation = () => {
+                if (!ownsCorrelationId || foregroundCorrelationRestored)
+                    return;
+                foregroundCorrelationRestored = true;
+                if (previousCorrelationId) {
+                    loggingService.setCorrelationId(previousCorrelationId);
+                }
+                else {
+                    loggingService.clearCorrelationId();
+                }
+            };
+            // The logger correlation ID is process-global. A foreground command owns
+            // it for the duration of its await; a background job uses the explicit
+            // `correlationId` fields below instead so it cannot contaminate another
+            // overlapping command's logs.
+            if (ownsCorrelationId)
+                loggingService.setCorrelationId(correlationId);
+            const withExecutionCorrelation = (metadata) => background || transferred ? { ...metadata, correlationId } : metadata;
             try {
                 // Use provided values or settings defaults or hardcoded defaults
                 const timeoutValue = timeout_ms ?? settingsService.get('shell.timeout');
                 const timeout = timeoutValue != null ? timeoutValue : undefined;
                 const maxOutputLengthValue = max_output_length ?? settingsService.get('shell.maxOutputChars');
-                const maxOutputLength = maxOutputLengthValue != null ? maxOutputLengthValue : undefined;
-                loggingService.debug('Shell command execution started', {
+                const configuredMaxOutputLength = settingsService.get('shell.maxOutputChars');
+                const foregroundMaxOutputLength = maxOutputLengthValue != null ? maxOutputLengthValue : undefined;
+                const backgroundMaxOutputLength = configuredMaxOutputLength != null
+                    ? Math.min(foregroundMaxOutputLength ?? configuredMaxOutputLength, configuredMaxOutputLength)
+                    : foregroundMaxOutputLength;
+                const initialMaxOutputLength = background ? backgroundMaxOutputLength : foregroundMaxOutputLength;
+                loggingService.debug('Shell command execution started', withExecutionCorrelation({
                     commandCount: 1,
                     commands: [command],
                     timeout,
                     workingDirectory: cwd,
-                    maxOutputLength,
-                });
+                    maxOutputLength: initialMaxOutputLength,
+                }));
                 // Strip redundant 'cd <path> &&' if it targets the current directory
                 const optimizedCommand = stripRedundantCd(command, cwd);
                 if (optimizedCommand !== command) {
-                    loggingService.debug('Stripped redundant cd command', {
-                        original: command,
-                        optimized: optimizedCommand,
-                        cwd,
-                    });
+                    loggingService.debug('Stripped redundant cd command', withExecutionCorrelation({ original: command, optimized: optimizedCommand, cwd }));
                 }
                 let commandToRun = optimizedCommand;
                 let sandboxAvailability;
-                if (!sshService &&
-                    settingsService.get('shell.useRtkCompression') &&
-                    isRtkSupportedCommand(optimizedCommand)) {
+                if (!sshService && settingsService.get('shell.useRtkCompression') && isRtkSupportedCommand(optimizedCommand)) {
                     const rtkPath = await rtkInstaller({ loggingService });
                     if (rtkPath) {
                         commandToRun = wrapWithRtk(optimizedCommand, rtkPath);
-                        loggingService.debug('Wrapped command with rtk', { rtkPath, original: optimizedCommand });
+                        loggingService.debug('Wrapped command with rtk', withExecutionCorrelation({ rtkPath, original: optimizedCommand }));
                     }
                 }
                 // Consume any execution override set by a denied-read approval decision.
                 // This is a one-shot override for this single execution only.
-                const override = executionOverrideStore.consume(command);
+                const override = postExecuteDeniedRead && typeof toolCallId === 'string'
+                    ? overrideByCallId.get(toolCallId) ?? null
+                    : nestedCompatibility?.executionOverrides.consume(command) ?? null;
+                if (postExecuteDeniedRead && typeof toolCallId === 'string')
+                    overrideByCallId.delete(toolCallId);
                 if (override?.forceUnsandboxed) {
                     sandbox = 'unsandboxed';
-                    loggingService.debug('Shell executing unsandboxed by approved override', {
-                        command: optimizedCommand.substring(0, 100),
-                    });
+                    loggingService.debug('Shell executing unsandboxed by approved override', withExecutionCorrelation({ command: optimizedCommand.substring(0, 100) }));
                 }
                 const extraAllowReadFromOverride = override?.extraAllowRead ?? [];
                 if (dockerHostControlRequested) {
@@ -315,13 +432,15 @@ export function createShellToolDefinition(deps) {
                         dockerHostControl = dockerHostControlFactory();
                         // The run that uses the approval settles the pending block, so a
                         // later run of the same command is judged on its own.
-                        consumeDockerHostControlDenial(command);
-                        loggingService.security('Docker host-control capability granted for shell command', {
+                        if (sessionAccess)
+                            sessionAccess.consumeDockerDenial(command);
+                        else
+                            nestedCompatibility?.docker.consumeDenial(sessionId, command);
+                        loggingService.security('Docker host-control capability granted for shell command', withExecutionCorrelation({
                             command: optimizedCommand.substring(0, 100),
                             cwd,
                             socketPath: dockerHostControl.socketPath,
-                            correlationId,
-                        });
+                        }));
                     }
                     catch (error) {
                         return `Error: ${error instanceof Error ? error.message : String(error)}`;
@@ -346,146 +465,258 @@ export function createShellToolDefinition(deps) {
                                     ...extraAllowReadFromOverride,
                                 ],
                                 onProtectedFiltered: (filtered) => {
-                                    loggingService.info('Shell sandbox removed write access to protected paths', {
-                                        filtered,
-                                        cwd,
-                                    });
+                                    loggingService.info('Shell sandbox removed write access to protected paths', withExecutionCorrelation({ filtered, cwd }));
                                 },
                             });
                             const wrapped = await shellSandboxRunner.wrap(commandToRun, {
                                 cwd,
                                 config: sandboxConfig,
-                                signal: details?.signal,
+                                signal: toolSignal,
                             });
                             commandToRun = wrapped.command;
                             sandboxed = true;
                             if (wrapped.diagnostics?.length) {
-                                loggingService.debug('Shell sandbox diagnostics', { diagnostics: wrapped.diagnostics });
+                                loggingService.debug('Shell sandbox diagnostics', withExecutionCorrelation({ diagnostics: wrapped.diagnostics }));
                             }
                         }
                         catch (error) {
-                            loggingService.warn('Shell sandbox initialization failed; refusing unsandboxed fallback', {
-                                error: error instanceof Error ? error.message : String(error),
-                            });
+                            loggingService.warn('Shell sandbox initialization failed; refusing unsandboxed fallback', withExecutionCorrelation({ error: error instanceof Error ? error.message : String(error) }));
                             return `Error: ${SANDBOX_ESCAPE_INSTRUCTION}`;
                         }
                     }
-                    else if (sandboxAvailability.type !== 'disabled') {
-                        loggingService.warn('Shell sandbox unavailable; running command without sandbox', {
+                    else {
+                        loggingService.warn('Shell sandbox unavailable; refusing unsandboxed fallback', withExecutionCorrelation({
                             availability: sandboxAvailability.type,
                             reason: 'reason' in sandboxAvailability ? sandboxAvailability.reason : undefined,
-                        });
+                        }));
+                        return `Error: ${SANDBOX_ESCAPE_INSTRUCTION}`;
                     }
                 }
-                const result = await executeShellCommandImpl(commandToRun, {
-                    cwd,
-                    timeout,
-                    maxBuffer: 1024 * 1024, // 1MB max buffer
-                    env: sandboxed
-                        ? createSandboxEnvironment(undefined, {
-                            cwd,
-                            readPolicy: settingsService.get('sandbox.readPolicy'),
-                            dockerHostControl,
-                        })
-                        : undefined,
-                    pauseOnSandboxNetworkApproval: sandboxed,
-                    signal: details?.signal,
-                    sshService,
-                });
-                const stdout = result.stdout ?? '';
-                const rawStderr = stripRtkWarning(result.stderr ?? '');
-                const annotatedStderr = sandboxed ? shellSandboxRunner.annotateFailure(optimizedCommand, rawStderr) : rawStderr;
-                const readPolicy = settingsService.get('sandbox.readPolicy');
-                const sandboxFailure = classifySandboxFailure({
-                    command: optimizedCommand,
-                    rawStderr,
-                    annotatedStderr,
-                    sandboxed,
-                    readPolicy,
-                    dockerHostControlActive: Boolean(dockerHostControl),
-                    exitCode: result.exitCode,
-                });
-                if (sandboxFailure?.type === 'docker_blocked') {
-                    // Keyed by the command the model passed, because that is what the
-                    // approval flow and the retry will present.
-                    recordDockerHostControlDenial(command);
-                    loggingService.security('Sandbox blocked Docker daemon access; agent retry will prompt for approval', {
-                        confidence: sandboxFailure.confidence,
-                        command: command.substring(0, 100),
+                const executePreparedCommand = async (signal) => {
+                    const result = await executeShellCommandImpl(commandToRun, {
                         cwd,
-                        correlationId,
-                    });
-                    return `Error: ${DOCKER_HOST_CONTROL_RETRY_INSTRUCTION}`;
-                }
-                if (sandboxFailure?.type === 'denied_read') {
-                    deniedReadStore.record(optimizedCommand, sandboxFailure.deniedRead);
-                    loggingService.security('Sandbox denied read; agent retry will prompt for approval', {
-                        deniedPath: sandboxFailure.deniedRead.path,
-                        suggestedParent: sandboxFailure.deniedRead.suggestedParent,
-                        sensitive: sandboxFailure.deniedRead.sensitive,
-                        confidence: sandboxFailure.confidence,
-                        command: optimizedCommand.substring(0, 100),
-                        correlationId,
-                    });
-                    return `Error: ${DETAILED_DENIED_READ_INSTRUCTION}`;
-                }
-                const stderr = sandboxFailure ? `${sandboxFailure.stderr}\n\n${SANDBOX_ESCAPE_INSTRUCTION}` : annotatedStderr;
-                const exitCode = result.exitCode ?? null;
-                const outcome = result.timedOut
-                    ? { type: 'timeout' }
-                    : { type: 'exit', exitCode };
-                if (result.timedOut) {
-                    loggingService.warn('Shell command timeout', {
-                        command: optimizedCommand.substring(0, 100),
                         timeout,
+                        maxBuffer: 1024 * 1024, // 1MB max buffer
+                        env: sandboxed
+                            ? createSandboxEnvironment(undefined, {
+                                cwd,
+                                readPolicy: settingsService.get('sandbox.readPolicy'),
+                                dockerHostControl,
+                            })
+                            : undefined,
+                        pauseOnSandboxNetworkApproval: sandboxed,
+                        signal,
+                        sshService,
                     });
-                }
-                else if (exitCode === 0) {
-                    loggingService.debug('Shell command executed successfully', {
-                        command: optimizedCommand.substring(0, 100),
-                        exitCode: 0,
-                        stdoutLength: stdout.length,
-                        stderrLength: stderr.length,
+                    const stdout = result.stdout ?? '';
+                    const rawStderr = stripRtkWarning(result.stderr ?? '');
+                    const annotatedStderr = sandboxed
+                        ? shellSandboxRunner.annotateFailure(optimizedCommand, rawStderr)
+                        : rawStderr;
+                    const readPolicy = settingsService.get('sandbox.readPolicy');
+                    const sandboxFailure = classifySandboxFailure({
+                        command: optimizedCommand,
+                        rawStderr,
+                        annotatedStderr,
+                        sandboxed,
+                        readPolicy,
+                        dockerHostControlActive: Boolean(dockerHostControl),
+                        exitCode: result.exitCode,
                     });
-                }
-                else {
-                    loggingService.debug('Shell command execution failed', {
-                        command: optimizedCommand.substring(0, 100),
+                    if (sandboxFailure?.type === 'docker_blocked') {
+                        // Keyed by the command the model passed, because that is what the
+                        // approval flow and the retry will present.
+                        if (sessionAccess)
+                            sessionAccess.recordDockerDenial(command);
+                        else
+                            nestedCompatibility?.docker.recordDenial(sessionId, command);
+                        loggingService.security('Sandbox blocked Docker daemon access; agent retry will prompt for approval', withExecutionCorrelation({
+                            confidence: sandboxFailure.confidence,
+                            command: command.substring(0, 100),
+                            cwd,
+                            sessionId,
+                            // Without a session the block is unattributable, so it is not
+                            // remembered and the retry will be sandboxed again.
+                            denialRecorded: Boolean(sessionId),
+                        }));
+                        return { output: `Error: ${DOCKER_HOST_CONTROL_RETRY_INSTRUCTION}`, status: 'failed' };
+                    }
+                    if (sandboxFailure?.type === 'denied_read') {
+                        if (!background && !transferred && postExecuteDeniedRead && typeof toolCallId !== 'string') {
+                            throw new HarnessInvariantError('Root shell denied-read handling requires an SDK tool call ID');
+                        }
+                        // Keyed by the command the model passed, not `optimizedCommand`: the
+                        // retry and both approval lookups (needsApproval here, and the
+                        // conversation layer, which has no cwd to re-derive the stripped form)
+                        // only ever see the raw string.
+                        if ((background || transferred) && postExecuteDeniedRead) {
+                            loggingService.security('Sandbox denied read in background shell job; foreground retry is required', withExecutionCorrelation({
+                                deniedPath: sandboxFailure.deniedRead.path,
+                                suggestedParent: sandboxFailure.deniedRead.suggestedParent,
+                                sensitive: sandboxFailure.deniedRead.sensitive,
+                                confidence: sandboxFailure.confidence,
+                                command: optimizedCommand.substring(0, 100),
+                            }));
+                            return {
+                                output: 'Error: Sandbox blocked a read access. Background jobs cannot request permission after launch; rerun this command in the foreground to choose an allow option.',
+                                status: 'failed',
+                            };
+                        }
+                        if (postExecuteDeniedRead) {
+                            deniedReadByCallId.set(toolCallId, sandboxFailure.deniedRead);
+                        }
+                        else {
+                            nestedCompatibility?.deniedReads.record(command, sandboxFailure.deniedRead);
+                        }
+                        loggingService.security('Sandbox denied read; agent retry will prompt for approval', withExecutionCorrelation({
+                            deniedPath: sandboxFailure.deniedRead.path,
+                            suggestedParent: sandboxFailure.deniedRead.suggestedParent,
+                            sensitive: sandboxFailure.deniedRead.sensitive,
+                            confidence: sandboxFailure.confidence,
+                            command: optimizedCommand.substring(0, 100),
+                        }));
+                        return { output: `Error: ${DETAILED_DENIED_READ_INSTRUCTION}`, status: 'failed' };
+                    }
+                    const stderr = sandboxFailure ? `${sandboxFailure.stderr}\n\n${SANDBOX_ESCAPE_INSTRUCTION}` : annotatedStderr;
+                    const exitCode = result.exitCode ?? null;
+                    const outcome = result.timedOut
+                        ? { type: 'timeout' }
+                        : { type: 'exit', exitCode };
+                    if (result.timedOut) {
+                        loggingService.warn('Shell command timeout', withExecutionCorrelation({ command: optimizedCommand.substring(0, 100), timeout }));
+                    }
+                    else if (exitCode === 0) {
+                        loggingService.debug('Shell command executed successfully', withExecutionCorrelation({
+                            command: optimizedCommand.substring(0, 100),
+                            exitCode: 0,
+                            stdoutLength: stdout.length,
+                            stderrLength: stderr.length,
+                        }));
+                    }
+                    else {
+                        loggingService.debug('Shell command execution failed', withExecutionCorrelation({
+                            command: optimizedCommand.substring(0, 100),
+                            exitCode,
+                            stderrLength: stderr.length,
+                        }));
+                    }
+                    loggingService.debug('Shell command execution completed', withExecutionCorrelation({
+                        commandCount: 1,
+                        successCount: outcome.type === 'exit' && outcome.exitCode === 0 ? 1 : 0,
+                        failureCount: outcome.type === 'exit' && outcome.exitCode !== 0 ? 1 : 0,
+                        timeoutCount: outcome.type === 'timeout' ? 1 : 0,
+                    }));
+                    const formattedOutput = await formatShellExecutionOutput({
+                        command: optimizedCommand,
+                        cwd,
+                        stdout,
+                        stderr,
                         exitCode,
-                        stderrLength: stderr.length,
+                        timedOut: outcome.type === 'timeout',
+                        maxOutputLength: background || transferred ? backgroundMaxOutputLength : foregroundMaxOutputLength,
+                        durationMs: Date.now() - startedAt,
                     });
+                    return {
+                        output: formattedOutput.text,
+                        status: result.timedOut ? 'timed_out' : exitCode === 0 ? 'completed' : 'failed',
+                    };
+                };
+                const cleanupAfterExecution = async () => {
+                    if (sandboxed) {
+                        await shellSandboxRunner.cleanupAfterCommand?.();
+                    }
+                    dockerHostControl?.cleanup();
+                    restoreForegroundCorrelation();
+                };
+                if (background) {
+                    try {
+                        const job = backgroundShellRegistry.launch({
+                            command: optimizedCommand,
+                            run: executePreparedCommand,
+                            onSettled: cleanupAfterExecution,
+                            resultToStatus: (result) => result.status,
+                        });
+                        backgroundCleanupDeferred = true;
+                        return JSON.stringify({ jobId: job.id, status: job.status });
+                    }
+                    catch (error) {
+                        return `Error: ${error instanceof Error ? error.message : String(error)}`;
+                    }
                 }
-                loggingService.debug('Shell command execution completed', {
-                    commandCount: 1,
-                    successCount: outcome.type === 'exit' && outcome.exitCode === 0 ? 1 : 0,
-                    failureCount: outcome.type === 'exit' && outcome.exitCode !== 0 ? 1 : 0,
-                    timeoutCount: outcome.type === 'timeout' ? 1 : 0,
-                });
-                const formattedOutput = await formatShellExecutionOutput({
-                    command: optimizedCommand,
-                    cwd,
-                    stdout,
-                    stderr,
-                    exitCode,
-                    timedOut: outcome.type === 'timeout',
-                    maxOutputLength,
-                    durationMs: Date.now() - startedAt,
-                });
-                return formattedOutput.text;
+                if (backgroundShellRegistry && !sshService && typeof toolCallId === 'string') {
+                    const lease = backgroundShellRegistry.startForeground({
+                        callId: toolCallId,
+                        command: optimizedCommand,
+                        parentSignal: toolSignal,
+                        run: executePreparedCommand,
+                        onSettled: cleanupAfterExecution,
+                        resultToStatus: (result) => result.status,
+                        onAdopted: () => {
+                            transferred = true;
+                            restoreForegroundCorrelation();
+                        },
+                    });
+                    // Cleanup is lease-owned now, whether it stays foreground or moves.
+                    backgroundCleanupDeferred = true;
+                    const result = await lease.foregroundResult;
+                    if ('jobId' in result) {
+                        // The tool call returns now, but only the parent-turn ownership is
+                        // released. Process cleanup remains deferred to lease settlement.
+                        restoreForegroundCorrelation();
+                        return JSON.stringify(result);
+                    }
+                    return result.output;
+                }
+                return (await executePreparedCommand(toolSignal)).output;
             }
             finally {
-                if (sandboxed) {
-                    await shellSandboxRunner.cleanupAfterCommand?.();
-                }
-                dockerHostControl?.cleanup();
-                if (previousCorrelationId) {
-                    loggingService.setCorrelationId(previousCorrelationId);
-                }
-                else {
-                    loggingService.clearCorrelationId();
+                if (!backgroundCleanupDeferred) {
+                    if (sandboxed) {
+                        await shellSandboxRunner.cleanupAfterCommand?.();
+                    }
+                    dockerHostControl?.cleanup();
+                    restoreForegroundCorrelation();
                 }
             }
         },
+        postExecutePause: postExecuteDeniedRead
+            ? {
+                describe: (params, _result, details) => {
+                    const callId = details?.toolCall?.callId;
+                    if (typeof callId !== 'string')
+                        return null;
+                    const info = deniedReadByCallId.get(callId);
+                    if (!info)
+                        return null;
+                    return {
+                        toolName: 'shell',
+                        argumentsText: JSON.stringify(params),
+                        deniedRead: {
+                            deniedPath: info.path,
+                            suggestedParent: info.suggestedParent,
+                            sensitive: info.sensitive,
+                            command: params.command,
+                        },
+                    };
+                },
+                resolve: async ({ result, details, executeAgain }, decision) => {
+                    const callId = details?.toolCall?.callId;
+                    const info = typeof callId === 'string' ? deniedReadByCallId.get(callId) : undefined;
+                    if (typeof callId === 'string')
+                        deniedReadByCallId.delete(callId);
+                    if (typeof callId !== 'string' ||
+                        !info ||
+                        (decision !== 'allow-once' && decision !== 'allow-remember' && decision !== 'unsandboxed-once')) {
+                        return result;
+                    }
+                    if (decision === 'allow-remember') {
+                        getProjectAllowReadStore(executionContext?.getCwd() || process.cwd()).append(info.suggestedParent);
+                    }
+                    overrideByCallId.set(callId, decision === 'unsandboxed-once' ? { forceUnsandboxed: true } : { extraAllowRead: [info.suggestedParent] });
+                    return executeAgain();
+                },
+            }
+            : undefined,
         formatCommandMessage: formatShellCommandMessage,
     };
 }