@qduc/term2 0.11.1 → 0.13.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.'),
@@ -26,16 +26,300 @@ const shellParametersSchema = z.object({
         .int()
         .positive()
         .optional()
-        .describe('Optional timeout in milliseconds for each command. Defaults to 120000 ms (2 minutes) if not specified.'),
+        .describe('Optional timeout in milliseconds for each command. Defaults to shell.timeout (foreground) or shell.backgroundTimeout (background) if not specified.'),
     max_output_length: relaxedNumber
         .int()
         .positive()
         .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.'),
+});
+const monitorShellJobParameters = z.object({
+    job_id: z.string().min(1).describe('The background shell job ID to monitor.'),
+    pattern: z
+        .string()
+        .optional()
+        .describe('Regular expression matched against each complete output line; absent matches any line.'),
+    stream: z.enum(['stdout', 'stderr', 'both']).optional().describe('Which output stream to monitor. Defaults to both.'),
+    idle_ms: relaxedNumber
+        .int()
+        .nonnegative()
+        .optional()
+        .describe('Quiet window in milliseconds that coalesces a burst of matches into one notification. Defaults to 1500.'),
+    notify_limit: relaxedNumber
+        .int()
+        .positive()
+        .optional()
+        .describe('Maximum number of notifications this watch may deliver before retiring. Defaults to 1 with a pattern, 5 without.'),
+    once: z.boolean().optional().describe('Retire the watch after its first notification (notify_limit 1).'),
+});
+const cancelShellMonitorParameters = z.object({
+    watch_id: z.string().min(1).describe('The watch ID returned by monitor_shell_job.'),
+});
+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 }),
+    };
+}
+const ACTIVE_JOB_MESSAGE = 'This background shell job is still running. End the current turn and wait for its automatic completion notification; do not poll get_shell_job.';
+function activeBackgroundShellJobResponse(job, output) {
+    const tail = output?.store.readTail(job.id);
+    if (!tail) {
+        // The store has no stream for this job (no monitoring layer, or a job
+        // that never went through the shell-tool seam): keep the refusal form.
+        return {
+            status: 'background_job_active',
+            jobId: job.id,
+            message: ACTIVE_JOB_MESSAGE,
+        };
+    }
+    return {
+        status: 'background_job_active',
+        jobId: job.id,
+        command: job.command,
+        tail: tail.text,
+        droppedBytes: tail.droppedBytes,
+        message: ACTIVE_JOB_MESSAGE,
+    };
+}
+/**
+ * Common transcript extraction for the job/monitor control tools: call id,
+ * normalized arguments, the parsed tool result, and a string reader.
+ */
+function backgroundShellToolTranscript(item, toolCallArgumentsById) {
+    const callId = getCallIdFromItem(item);
+    const fallbackArgs = callId && toolCallArgumentsById.has(callId) ? toolCallArgumentsById.get(callId) : null;
+    const args = normalizeToolArguments(item?.rawItem?.arguments ?? item?.arguments) ?? normalizeToolArguments(fallbackArgs) ?? {};
+    const toolName = item?.toolName ?? item?.rawItem?.name ?? 'shell_job';
+    const outputText = getOutputText(item);
+    const response = safeJsonParse(outputText);
+    const readString = (value) => (typeof value === 'string' ? value : '');
+    return { callId, args, toolName, outputText, response, readString };
+}
+/**
+ * Job control is part of what the model did, so it belongs in the transcript.
+ * It also has to be: the UI opens a `running` command row on every
+ * `tool_started` and only closes it when a command message arrives for the same
+ * callId. A formatter returning `[]` leaves that row running forever, and
+ * because a running command is the first thing that cannot render statically,
+ * every message behind it stays out of Ink's Static region for the rest of the
+ * session.
+ */
+export const formatBackgroundShellJobCommandMessage = (item, index, toolCallArgumentsById) => {
+    const { args, toolName, outputText, response, readString } = backgroundShellToolTranscript(item, toolCallArgumentsById);
+    const jobId = readString(response?.jobId) || readString(args?.job_id);
+    const status = readString(response?.status);
+    const jobCommand = readString(response?.command);
+    const output = (() => {
+        if (!response) {
+            return outputText || 'No output';
+        }
+        if (status === 'not_found') {
+            return `Job ${jobId} not found.`;
+        }
+        // The active-job response carries an instruction aimed at the model
+        // ("do not poll"), which is noise in the transcript: show the bounded
+        // tail and drop accounting instead of the static refusal string.
+        if (status === 'background_job_active') {
+            const tail = readString(response?.tail);
+            const droppedBytes = typeof response?.droppedBytes === 'number' ? response.droppedBytes : 0;
+            const body = [tail, droppedBytes > 0 ? `(${droppedBytes} bytes of earlier output dropped)` : '']
+                .filter(Boolean)
+                .join('\n');
+            return body || 'Still running.';
+        }
+        const header = jobCommand ? `${status} · ${jobCommand}` : status ? `status: ${status}` : '';
+        const body = readString(response.output);
+        const error = readString(response.error);
+        return [header, body, error].filter(Boolean).join('\n') || outputText || 'No output';
+    })();
+    return [
+        createBaseMessage(item, index, 0, false, {
+            command: jobId ? `${toolName} ${jobId}` : toolName,
+            output,
+            success: status !== 'not_found' && !readString(response?.error),
+            toolName,
+            toolArgs: args,
+        }),
+    ];
+};
+/**
+ * Transcript row for `monitor_shell_job`. Renders the returned watchId and the
+ * job it is attached to; a later `background_shell_output` notification carries
+ * the seq/matchedLines of each firing.
+ */
+export const formatBackgroundShellMonitorCommandMessage = (item, index, toolCallArgumentsById) => {
+    const { args, toolName, outputText, response, readString } = backgroundShellToolTranscript(item, toolCallArgumentsById);
+    const jobId = readString(response?.jobId) || readString(args?.job_id);
+    const watchId = readString(response?.watchId);
+    const status = readString(response?.status);
+    const output = (() => {
+        if (!response) {
+            return outputText || 'No output';
+        }
+        if (status === 'not_found') {
+            return `Job ${jobId} not found.`;
+        }
+        const error = readString(response?.error);
+        if (error) {
+            return error;
+        }
+        if (status === 'monitoring') {
+            const seq = typeof response?.seq === 'number' ? ` (firing ${response.seq})` : '';
+            const matched = readString(response?.matchedLines);
+            return [watchId ? `Monitoring job ${jobId} (watch ${watchId}).${seq}` : `Monitoring job ${jobId}.`, matched]
+                .filter(Boolean)
+                .join('\n');
+        }
+        return outputText || 'No output';
+    })();
+    return [
+        createBaseMessage(item, index, 0, false, {
+            command: watchId ? `${toolName} ${watchId}` : `${toolName} ${jobId}`,
+            output,
+            success: status === 'monitoring',
+            toolName,
+            toolArgs: args,
+        }),
+    ];
+};
+/** Transcript row for `cancel_shell_monitor`. */
+export const formatBackgroundShellCancelMonitorCommandMessage = (item, index, toolCallArgumentsById) => {
+    const { args, toolName, outputText, response, readString } = backgroundShellToolTranscript(item, toolCallArgumentsById);
+    const watchId = readString(response?.watchId) || readString(args?.watch_id);
+    const status = readString(response?.status);
+    const output = (() => {
+        if (!response) {
+            return outputText || 'No output';
+        }
+        const error = readString(response?.error);
+        if (error) {
+            return error;
+        }
+        if (status === 'not_found') {
+            return `Watch ${watchId} not found.`;
+        }
+        if (status === 'cancelled') {
+            return `Stopped monitoring (watch ${watchId}).`;
+        }
+        return outputText || 'No output';
+    })();
+    return [
+        createBaseMessage(item, index, 0, false, {
+            command: watchId ? `${toolName} ${watchId}` : toolName,
+            output,
+            success: status === 'cancelled',
+            toolName,
+            toolArgs: args,
+        }),
+    ];
+};
+/**
+ * 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.
+ *
+ * `output` carries the session-owned store + watch layer; when it is absent
+ * (legacy callers), the monitor tools are not registered.
+ */
+export function createBackgroundShellJobToolDefinitions(registry, output) {
+    const definitions = {
+        get: {
+            name: 'get_shell_job',
+            description: 'Get the non-blocking status and bounded output of a background shell job. Do not use this to poll a running job; completion is delivered automatically.',
+            parameters: getBackgroundShellJobParameters,
+            needsApproval: () => false,
+            execute: ({ job_id }) => {
+                const job = registry.get(job_id);
+                if (job?.status === 'running' || job?.status === 'cancelling')
+                    return JSON.stringify(activeBackgroundShellJobResponse(job, output));
+                return JSON.stringify(job ? backgroundShellJobResponse(job) : { jobId: job_id, status: 'not_found' });
+            },
+            formatCommandMessage: formatBackgroundShellJobCommandMessage,
+        },
+        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: formatBackgroundShellJobCommandMessage,
+        },
+    };
+    if (output) {
+        definitions.monitor = {
+            name: 'monitor_shell_job',
+            description: "Attach a watch to a running background shell job. The watch replays the job's retained output, and each time a complete line in the selected stream matches `pattern` (or any line arrives when `pattern` is absent) and the output has been quiet for `idle_ms`, a `shell_output` notification carrying the matched lines is delivered through the conversation; the job keeps running. Returns a watchId; stop the watch with cancel_shell_monitor.",
+            parameters: monitorShellJobParameters,
+            needsApproval: () => false,
+            execute: ({ job_id, pattern, stream, idle_ms, notify_limit, once }) => {
+                const job = registry.get(job_id);
+                if (!job ||
+                    output.store.readTail(job_id) === undefined ||
+                    (job.status !== 'running' && job.status !== 'cancelling')) {
+                    return JSON.stringify({ jobId: job_id, status: 'not_found' });
+                }
+                let compiled;
+                if (pattern !== undefined) {
+                    try {
+                        compiled = new RegExp(pattern);
+                    }
+                    catch (error) {
+                        return JSON.stringify({
+                            jobId: job_id,
+                            status: 'error',
+                            error: `Invalid monitor pattern: ${error instanceof Error ? error.message : String(error)}`,
+                        });
+                    }
+                }
+                const options = {
+                    jobId: job_id,
+                    pattern: compiled,
+                    stream,
+                    idleMs: idle_ms,
+                    notifyLimit: once ? 1 : notify_limit,
+                    command: job.command,
+                };
+                const watchId = output.watches.registerWatch(options);
+                return JSON.stringify({ watchId, jobId: job_id, status: 'monitoring' });
+            },
+            formatCommandMessage: formatBackgroundShellMonitorCommandMessage,
+        };
+        definitions.cancelMonitor = {
+            name: 'cancel_shell_monitor',
+            description: 'Stop a shell monitor watch so it stops delivering shell_output notifications.',
+            parameters: cancelShellMonitorParameters,
+            needsApproval: () => false,
+            execute: ({ watch_id }) => {
+                const cancelled = output.watches.cancelWatch(watch_id);
+                return JSON.stringify({ watchId: watch_id, status: cancelled ? 'cancelled' : 'not_found' });
+            },
+            formatCommandMessage: formatBackgroundShellCancelMonitorCommandMessage,
+        };
+    }
+    return definitions;
+}
 /**
  * Strip redundant 'cd <path> &&' prefix if it targets the current working directory
  */
@@ -98,11 +382,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 +407,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 +475,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, backgroundShellWatches, } = 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 +506,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 +544,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 +579,89 @@ 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;
+            let observedJobId;
+            // Background-only monitor seam: set when the background branch opens the
+            // job's output stream, so the shared onOutputChunk never touches the
+            // store for a foreground lease job.
+            let monitoredJobId;
+            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');
+                // Use provided values or settings defaults or hardcoded defaults. A
+                // background launch uses shell.backgroundTimeout instead of
+                // shell.timeout (background jobs may legitimately outlive the
+                // foreground budget); an explicit timeout_ms always wins.
+                const timeoutValue = timeout_ms ?? settingsService.get(background ? 'shell.backgroundTimeout' : '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 +672,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 +705,292 @@ 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
+                        // A long-running monitored background job must survive a full
+                        // buffer: drop from the head of the retained text instead of
+                        // killing the child. Foreground keeps the 'kill' default.
+                        overflow: background ? 'truncate' : 'kill',
+                        env: sandboxed
+                            ? createSandboxEnvironment(undefined, {
+                                cwd,
+                                readPolicy: settingsService.get('sandbox.readPolicy'),
+                                dockerHostControl,
+                            })
+                            : undefined,
+                        pauseOnSandboxNetworkApproval: sandboxed,
+                        signal,
+                        sshService,
+                        onOutputChunk: (stream, text) => {
+                            if (observedJobId)
+                                backgroundShellRegistry?.recordOutputChunk(observedJobId);
+                            // Monitoring is background-only: the store stream is opened only
+                            // for the background branch, so a foreground lease job is never
+                            // pushed here. watches.push feeds the store and evaluates the
+                            // job's watches in one call.
+                            if (monitoredJobId)
+                                backgroundShellWatches?.push(monitoredJobId, stream, text);
+                        },
                     });
-                }
-                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,
+                            onStarted: (jobId) => {
+                                observedJobId = jobId;
+                                // Open the retained output stream (and the watch layer) for
+                                // this job at launch; settled in onSettled below.
+                                if (backgroundShellWatches) {
+                                    monitoredJobId = jobId;
+                                    backgroundShellWatches.open(jobId);
+                                }
+                            },
+                            onSettled: () => {
+                                // Flush matched-but-undelivered watch firings before the
+                                // registry emits background_shell_completed (it awaits this
+                                // callback first): no monitor firing may trail the terminal
+                                // notification. Then release shell resources as before.
+                                if (monitoredJobId)
+                                    backgroundShellWatches?.settleJob(monitoredJobId);
+                                return 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,
+                        onStarted: (jobId) => {
+                            observedJobId = jobId;
+                        },
+                        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,
     };
 }