agent-world 0.13.0 → 0.15.0

package/dist/core/shell-cmd-tool.js

@@ -27,6 +27,21 @@
  * - Uses universal validation framework for consistent parameter checking
  *
  * Recent Changes:
+ * - 2026-03-12: Shared tool approval flow now persists durable approval prompt/resolution messages for replay-safe shell approval history.
+ * - 2026-03-12: Added `toolPermission` enforcement: 'read' level blocks execution with an error result; 'ask' level forces every invocation through HITL approval regardless of risk tier.
+ * - 2026-03-06: Added explicit canonical failure reasons for shell validation/policy failures so approval denials and validation errors no longer masquerade as non-zero exits.
+ * - 2026-03-06: Unified shell continuation output on one bounded-preview result contract, removed `smart`-mode branching, and stopped persisting a synthetic assistant stdout mirror message after shell completion.
+ * - 2026-03-06: Added canonical shell error-result formatting helper so upstream tool persistence can normalize shell failures without falling back to ad hoc error strings.
+ * - 2026-03-05: Hardened timeout termination to target process groups/process trees (SIGTERM + SIGKILL fallback) and removed child-process builtin timeout to keep timeout outcomes deterministic in the tool layer.
+ * - 2026-03-05: Switched shell timeout grace config to shared reliability config helper.
+ * - 2026-03-01: Prevented `./` and `../` parameter tokens from being misclassified as `<skill-id>/<path>` so non-skill shell paths remain unchanged.
+ * - 2026-02-28: Generalized skill-relative path fallback to work with any folder prefix, removing `scripts/`-specific behavior.
+ * - 2026-02-28: Added skill-aware script path resolution so `<skill-id>/scripts/<file>` parameters are auto-resolved to absolute paths under the skill root directory.
+ * - 2026-02-28: Added deterministic shell risk tiering (`allow`/`hitl_required`/`block`) with per-call HITL approve/deny gating via shared `requestToolApproval` helper for high-risk in-scope commands.
+ * - 2026-02-24: Required explicit chatId context for stdout/stderr streaming event emission to preserve chat isolation under strict frontend filtering.
+ * - 2026-02-21: Streamed stderr via legacy `tool-stream` events while streaming stdout as assistant SSE; persisted only finalized stdout assistant message after execution completes.
+ * - 2026-02-21: Added assistant-style SSE start/chunk/end streaming for shell runtime output so command chunks are delivered as assistant stream events instead of `tool-stream` messages.
+ * - 2026-02-21: Added minimal LLM shell-result mode (`status` + `exit_code` semantics) for tool-call continuations, excluding stdout/stderr transcript bodies.
  * - 2026-02-15: Moved core cwd-boundary enforcement into `executeShellCommand` via optional `trustedWorkingDirectory` execution option.
  * - 2026-02-15: Added optional `output_format=json` for machine-readable command results.
  * - 2026-02-15: Added optional `artifact_paths` support with SHA-256 hashing and byte-size metadata for files within trusted scope.
@@ -63,16 +78,22 @@
  * - Initial implementation for shell_cmd LLM tool
  */
 import { spawn } from 'child_process';
-import { resolve, join, relative } from 'path';
+import { resolve, join, relative, dirname } from 'path';
 import { createHash } from 'crypto';
 import { homedir } from 'os';
-import { realpathSync, promises as fsPromises } from 'fs';
+import { existsSync, readdirSync, realpathSync, promises as fsPromises } from 'fs';
 import { createCategoryLogger } from './logger.js';
+import { getShellTimeoutKillGraceMs } from './reliability-config.js';
 import { validateToolParameters } from './tool-utils.js';
-import { publishSSE } from './events/index.js';
+import { requestToolApproval } from './tool-approval.js';
+import { publishSSE } from './events/publishers.js';
 import { getDefaultWorkingDirectory, getEnvValueFromText } from './utils.js';
+import { getSkillSourcePath, getSkills } from './skill-registry.js';
+import { buildToolArtifactPreviewUrl, createArtifactToolPreview, createTextToolPreview, serializeToolExecutionEnvelope, } from './tool-execution-envelope.js';
 import { createShellProcessExecution, transitionShellProcessExecution, attachShellProcessHandle, markShellProcessCancelRequested, listShellProcessExecutions, getShellProcessExecution, cancelShellProcessExecution, deleteShellProcessExecution, stopShellProcessesForChatScope, subscribeShellProcessStatus, clearShellProcessRegistryForTests } from './shell-process-registry.js';
 const logger = createCategoryLogger('shell-cmd');
+const SHELL_RISK_APPROVE_OPTION = 'approve';
+const SHELL_RISK_DENY_OPTION = 'deny';
 /**
  * Resolve directory path, handling tilde expansion and relative paths
  */
@@ -86,6 +107,28 @@ function resolveDirectory(directory) {
     return resolve(directory);
 }
 const DEFAULT_MIN_OUTPUT_CHARS = 400;
+const DEFAULT_LLM_PREVIEW_OUTPUT_CHARS = 1200;
+function inferShellFailureReason(errorMessage) {
+    const normalized = String(errorMessage || '').trim().toLowerCase();
+    if (!normalized) {
+        return undefined;
+    }
+    if (normalized.includes('approval required')
+        || normalized.includes('request was not approved')
+        || normalized.includes('command not executed:')) {
+        return 'approval_denied';
+    }
+    if (normalized.includes('invalid command')
+        || normalized.includes('invalid json in tool arguments')
+        || normalized.includes('invalid tool call payload')
+        || normalized.includes('working directory mismatch')
+        || normalized.includes('outside world working directory')
+        || normalized.includes('blocked dangerous operation')
+        || normalized.includes('cannot be executed')) {
+        return 'validation_error';
+    }
+    return undefined;
+}
 function buildOutputSnippet(content, maxOutputChars) {
     if (!content) {
         return { text: '', truncated: false };
@@ -299,6 +342,181 @@ function tokenizeInlineCommandArgs(command) {
 function tokenizeCommand(command) {
     return command.match(/"([^"\\]|\\.)*"|'([^'\\]|\\.)*'|[^\s]+/g) ?? [];
 }
+function normalizeExecutable(command) {
+    const executable = getExecutableName(command).toLowerCase();
+    return executable.endsWith('.exe') ? executable.slice(0, -4) : executable;
+}
+function normalizeParameterTokens(parameters) {
+    if (!Array.isArray(parameters)) {
+        return [];
+    }
+    return parameters
+        .filter((parameter) => typeof parameter === 'string')
+        .map((parameter) => stripWrappingQuotes(parameter).trim())
+        .filter(Boolean);
+}
+function hasFlag(parameters, aliases) {
+    const aliasSet = new Set(aliases.map((alias) => alias.toLowerCase()));
+    return parameters.some((parameter) => {
+        const lowered = parameter.toLowerCase();
+        if (aliasSet.has(lowered))
+            return true;
+        if (lowered.startsWith('--')) {
+            return false;
+        }
+        if (lowered.startsWith('-') && lowered.length > 2) {
+            const shortFlags = lowered.slice(1).split('');
+            for (const shortFlag of shortFlags) {
+                if (aliasSet.has(`-${shortFlag}`)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    });
+}
+function isSystemCriticalPath(token) {
+    const normalized = token.trim().replace(/\\/g, '/').toLowerCase();
+    if (!normalized)
+        return false;
+    if (normalized === '/' || normalized === '~' || normalized === '/root') {
+        return true;
+    }
+    if (/^[a-z]:\/$/.test(normalized)) {
+        return true;
+    }
+    const criticalPrefixes = [
+        '/etc',
+        '/usr',
+        '/bin',
+        '/sbin',
+        '/lib',
+        '/opt',
+        '/var',
+        '/system',
+        '/library',
+        '/private',
+        '/proc',
+        '/sys',
+        '/dev'
+    ];
+    return criticalPrefixes.some((prefix) => normalized === prefix || normalized.startsWith(`${prefix}/`));
+}
+function hasWildcardTarget(parameters) {
+    return parameters.some((token) => token.includes('*') || token.includes('?'));
+}
+function assessRmRisk(parameters) {
+    const hasRecursive = hasFlag(parameters, ['-r', '-R', '--recursive']);
+    const hasForce = hasFlag(parameters, ['-f', '--force']);
+    const hasNoPreserveRoot = hasFlag(parameters, ['--no-preserve-root']);
+    const pathTargets = parameters
+        .map((token) => extractPathToken(token) ?? token)
+        .map((token) => stripWrappingQuotes(token));
+    const hasCriticalTarget = pathTargets.some((token) => isSystemCriticalPath(token));
+    if (hasNoPreserveRoot || (hasRecursive && hasForce && hasCriticalTarget)) {
+        return {
+            tier: 'block',
+            reason: 'catastrophic_delete_target',
+            tags: ['risk:destructive', 'risk:delete', 'risk:critical-target']
+        };
+    }
+    return {
+        tier: 'hitl_required',
+        reason: hasWildcardTarget(parameters) ? 'destructive_delete_wildcard' : 'destructive_delete',
+        tags: ['risk:destructive', 'risk:delete']
+    };
+}
+export function classifyShellCommandRisk(command, parameters) {
+    if (typeof command !== 'string' || !command.trim()) {
+        return {
+            tier: 'allow',
+            reason: 'invalid_or_empty_command',
+            tags: ['risk:none']
+        };
+    }
+    const executable = normalizeExecutable(command);
+    const parameterTokens = normalizeParameterTokens(parameters);
+    const hasUrl = parameterTokens.some((token) => /^https?:\/\//i.test(token));
+    if (['rm', 'rmdir', 'unlink', 'del', 'erase'].includes(executable)) {
+        return assessRmRisk(parameterTokens);
+    }
+    if (['mkfs', 'mkfs.ext4', 'mkfs.xfs', 'mkfs.btrfs', 'fdisk', 'sfdisk', 'parted'].includes(executable)) {
+        return {
+            tier: 'block',
+            reason: 'catastrophic_disk_operation',
+            tags: ['risk:destructive', 'risk:disk']
+        };
+    }
+    if (executable === 'dd' && parameterTokens.some((token) => token.toLowerCase().startsWith('of=/dev/'))) {
+        return {
+            tier: 'block',
+            reason: 'catastrophic_disk_write',
+            tags: ['risk:destructive', 'risk:disk']
+        };
+    }
+    if (['chmod', 'chown', 'chgrp'].includes(executable) && hasFlag(parameterTokens, ['-r', '-R', '--recursive'])) {
+        return {
+            tier: 'hitl_required',
+            reason: 'recursive_permission_change',
+            tags: ['risk:permissions', 'risk:recursive']
+        };
+    }
+    if (executable === 'git' && parameterTokens[0]?.toLowerCase() === 'clean' && hasFlag(parameterTokens, ['-f', '-d', '-x'])) {
+        return {
+            tier: 'hitl_required',
+            reason: 'destructive_git_clean',
+            tags: ['risk:destructive', 'risk:git']
+        };
+    }
+    if (['curl', 'wget'].includes(executable) && hasUrl && hasFlag(parameterTokens, ['-o', '-O', '--output-document'])) {
+        return {
+            tier: 'hitl_required',
+            reason: 'remote_download',
+            tags: ['risk:network', 'risk:download']
+        };
+    }
+    return {
+        tier: 'allow',
+        reason: 'low_risk_command',
+        tags: ['risk:none']
+    };
+}
+async function requestShellCommandRiskApproval(options) {
+    const approval = await requestToolApproval({
+        world: options.world,
+        chatId: options.chatId,
+        toolCallId: options.toolCallId,
+        title: 'Approve risky shell command?',
+        message: [
+            `Command: ${options.command} ${options.parameters.join(' ')}`.trim(),
+            `Risk: ${options.risk.reason}`,
+            `Trusted directory: ${options.resolvedDirectory}`,
+            'Proceed with this command?',
+        ].join('\n'),
+        defaultOptionId: SHELL_RISK_DENY_OPTION,
+        options: [
+            { id: SHELL_RISK_APPROVE_OPTION, label: 'Approve', description: 'Run this command once.' },
+            { id: SHELL_RISK_DENY_OPTION, label: 'Deny', description: 'Do not run this command.' },
+        ],
+        approvedOptionIds: [SHELL_RISK_APPROVE_OPTION],
+        metadata: {
+            tool: 'shell_cmd',
+            riskTier: options.risk.tier,
+            riskReason: options.risk.reason,
+            riskTags: options.risk.tags,
+            command: options.command,
+            parameters: options.parameters,
+            cwd: options.resolvedDirectory,
+            ...(options.toolCallId ? { toolCallId: options.toolCallId } : {}),
+        },
+        agentName: options.agentName || null,
+        messages: options.messages,
+    });
+    return {
+        approved: approval.approved,
+        reason: approval.reason,
+    };
+}
 function hasDisallowedShellSyntax(value) {
     if (!value)
         return false;
@@ -408,7 +626,7 @@ function findInlineScriptExecutionFlag(command, parameters) {
     }
     return null;
 }
-export function validateShellCommandScope(command, parameters, trustedWorkingDirectory) {
+export function validateShellCommandScope(command, parameters, trustedWorkingDirectory, additionalTrustedRoots) {
     const singleCommandValidation = validateSingleCommandContract(command);
     if (!singleCommandValidation.valid) {
         return singleCommandValidation;
@@ -450,14 +668,177 @@ export function validateShellCommandScope(command, parameters, trustedWorkingDir
             continue;
         const resolvedPath = resolveTokenPath(token, trustedWorkingDirectory);
         if (!isPathWithinTrustedDirectory(resolvedPath, trustedWorkingDirectory)) {
-            return {
-                valid: false,
-                error: `Working directory mismatch: path "${token}" is outside world working directory "${trustedWorkingDirectory}".`
-            };
+            const withinAdditionalRoot = (additionalTrustedRoots || []).some((root) => isPathWithinTrustedDirectory(resolvedPath, root));
+            if (!withinAdditionalRoot) {
+                return {
+                    valid: false,
+                    error: `Working directory mismatch: path "${token}" is outside world working directory "${trustedWorkingDirectory}".`
+                };
+            }
         }
     }
     return { valid: true };
 }
+const SKILL_DIR_PREFIXES = ['.agents/skills/', 'skills/'];
+function extractSkillIdAndRemainder(param) {
+    for (const prefix of SKILL_DIR_PREFIXES) {
+        if (param.startsWith(prefix)) {
+            const afterPrefix = param.slice(prefix.length);
+            const slashIndex = afterPrefix.indexOf('/');
+            if (slashIndex <= 0)
+                continue;
+            const skillId = afterPrefix.slice(0, slashIndex);
+            const remainder = afterPrefix.slice(slashIndex + 1);
+            if (skillId && remainder)
+                return { skillId, remainder };
+        }
+    }
+    const slashIndex = param.indexOf('/');
+    if (slashIndex <= 0)
+        return null;
+    const skillId = param.slice(0, slashIndex);
+    if (skillId === '.' || skillId === '..' || skillId.startsWith('.') || skillId.startsWith('-')) {
+        return null;
+    }
+    const remainder = param.slice(slashIndex + 1);
+    if (!remainder)
+        return null;
+    return { skillId, remainder };
+}
+function resolveWithPrefixFallback(skillRoot, relativePath, requireExisting = true) {
+    const directCandidate = join(skillRoot, relativePath);
+    if (!requireExisting || existsSync(directCandidate)) {
+        return directCandidate;
+    }
+    const slashIndex = relativePath.indexOf('/');
+    if (slashIndex <= 0) {
+        return null;
+    }
+    const withoutFirstSegment = relativePath.slice(slashIndex + 1);
+    if (!withoutFirstSegment) {
+        return null;
+    }
+    const fallbackCandidate = join(skillRoot, withoutFirstSegment);
+    if (!requireExisting || existsSync(fallbackCandidate)) {
+        return fallbackCandidate;
+    }
+    return null;
+}
+function resolveFromRuntimeSkillsRoot(param, runtimeSkillsRoot) {
+    if (!runtimeSkillsRoot)
+        return null;
+    if (!param.includes('/'))
+        return null;
+    if (!existsSync(runtimeSkillsRoot))
+        return null;
+    let entries = [];
+    try {
+        entries = readdirSync(runtimeSkillsRoot, { withFileTypes: true, encoding: 'utf8' });
+    }
+    catch {
+        return null;
+    }
+    for (const entry of entries) {
+        const isDirectory = entry.isDirectory();
+        const isSymlink = typeof entry.isSymbolicLink === 'function' && entry.isSymbolicLink();
+        if (!isDirectory && !isSymlink)
+            continue;
+        const skillRoot = join(runtimeSkillsRoot, entry.name);
+        const candidatePath = resolveWithPrefixFallback(skillRoot, param);
+        if (candidatePath) {
+            return { absolutePath: candidatePath, skillRoot };
+        }
+    }
+    return null;
+}
+function resolveBareSkillPath(param, runtimeSkillsRoot) {
+    if (!param.includes('/'))
+        return null;
+    const runtimeMatch = resolveFromRuntimeSkillsRoot(param, runtimeSkillsRoot);
+    if (runtimeMatch) {
+        return runtimeMatch;
+    }
+    const skills = getSkills();
+    for (const skill of skills) {
+        const sourcePath = getSkillSourcePath(skill.skill_id);
+        if (!sourcePath)
+            continue;
+        const skillRoot = dirname(sourcePath);
+        const candidatePath = resolveWithPrefixFallback(skillRoot, param);
+        if (candidatePath) {
+            return { absolutePath: candidatePath, skillRoot };
+        }
+    }
+    return null;
+}
+function hasActiveSkillContext(messages, chatId) {
+    if (!Array.isArray(messages)) {
+        return false;
+    }
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (!message || typeof message !== 'object') {
+            continue;
+        }
+        const messageChatId = typeof message.chatId === 'string' ? message.chatId.trim() : '';
+        if (chatId && messageChatId && messageChatId !== chatId) {
+            continue;
+        }
+        if (message.role !== 'tool') {
+            continue;
+        }
+        const content = typeof message.content === 'string' ? message.content : '';
+        if (content.includes('<skill_context id="')) {
+            return true;
+        }
+    }
+    return false;
+}
+export function resolveSkillScriptParameters(parameters, runtimeSkillsRoot, options) {
+    const skillRootsSet = new Set();
+    const allowBareScriptsResolution = options?.allowBareScriptsResolution === true;
+    const resolvedParameters = parameters.map((param) => {
+        const parsed = extractSkillIdAndRemainder(param);
+        if (parsed) {
+            const hasExplicitSkillPrefix = SKILL_DIR_PREFIXES.some((prefix) => param.startsWith(prefix));
+            const sourcePath = getSkillSourcePath(parsed.skillId);
+            const hasRuntimeSkillDir = Boolean(runtimeSkillsRoot)
+                && existsSync(join(runtimeSkillsRoot, parsed.skillId));
+            const shouldAttemptExplicitResolution = hasExplicitSkillPrefix || Boolean(sourcePath) || hasRuntimeSkillDir;
+            if (shouldAttemptExplicitResolution) {
+                if (sourcePath) {
+                    const skillRoot = dirname(sourcePath);
+                    const absolutePath = resolveWithPrefixFallback(skillRoot, parsed.remainder, false);
+                    if (absolutePath && isPathWithinTrustedDirectory(absolutePath, skillRoot)) {
+                        skillRootsSet.add(skillRoot);
+                        return absolutePath;
+                    }
+                }
+                if (runtimeSkillsRoot) {
+                    const candidateSkillRoot = join(runtimeSkillsRoot, parsed.skillId);
+                    const candidatePath = resolveWithPrefixFallback(candidateSkillRoot, parsed.remainder);
+                    if (candidatePath) {
+                        skillRootsSet.add(candidateSkillRoot);
+                        return candidatePath;
+                    }
+                }
+                if (hasExplicitSkillPrefix) {
+                    return param;
+                }
+            }
+        }
+        if (!allowBareScriptsResolution) {
+            return param;
+        }
+        const bareMatch = resolveBareSkillPath(param, runtimeSkillsRoot);
+        if (bareMatch) {
+            skillRootsSet.add(bareMatch.skillRoot);
+            return bareMatch.absolutePath;
+        }
+        return param;
+    });
+    return { resolvedParameters, skillRoots: [...skillRootsSet] };
+}
 export function stopShellCommandsForChat(worldId, chatId) {
     return stopShellProcessesForChatScope(worldId, chatId);
 }
@@ -506,6 +887,7 @@ export async function executeShellCommand(command, parameters = [], directory, o
         let timedOut = false;
         let aborted = false;
         let processExited = false;
+        let timeoutForceKillHandle = null;
         let unsubscribeStatusListener = null;
         const result = {
             executionId,
@@ -545,17 +927,66 @@ export async function executeShellCommand(command, parameters = [], directory, o
             const childProcess = spawn(command, quotedParams, {
                 cwd: resolvedDirectory,
                 shell: true, // Use shell to enable PATH resolution and shell features
-                timeout: timeout
+                detached: process.platform !== 'win32',
             });
             attachShellProcessHandle(executionId, childProcess);
             transitionShellProcessExecution(executionId, 'running', {
                 startedAt: new Date().toISOString()
             });
+            const sendTerminationSignal = (signal) => {
+                const pid = childProcess.pid;
+                // On Unix-like systems, detached child uses its own process group;
+                // signaling negative PID targets the full group/tree.
+                if (pid && process.platform !== 'win32') {
+                    try {
+                        process.kill(-pid, signal);
+                        return;
+                    }
+                    catch {
+                        // Fall back to direct child signal below.
+                    }
+                }
+                if (process.platform === 'win32') {
+                    // Best effort process-tree termination on Windows.
+                    try {
+                        const taskkill = spawn('taskkill', ['/PID', String(pid), '/T', '/F'], {
+                            stdio: 'ignore',
+                            windowsHide: true,
+                        });
+                        taskkill.unref();
+                        return;
+                    }
+                    catch {
+                        // Fall back to direct child signal below.
+                    }
+                }
+                try {
+                    childProcess.kill(signal);
+                }
+                catch {
+                    // ignore if process already exited
+                }
+            };
+            const requestTermination = (source) => {
+                if (processExited)
+                    return;
+                sendTerminationSignal('SIGTERM');
+                if (source === 'timeout') {
+                    const graceMs = getShellTimeoutKillGraceMs();
+                    if (graceMs > 0) {
+                        timeoutForceKillHandle = setTimeout(() => {
+                            if (processExited)
+                                return;
+                            sendTerminationSignal('SIGKILL');
+                        }, graceMs);
+                    }
+                }
+            };
             // Set up timeout handler
             const timeoutHandle = setTimeout(() => {
                 if (!processExited) {
                     timedOut = true;
-                    childProcess.kill('SIGTERM');
+                    requestTermination('timeout');
                     logger.warn('Command execution timeout', { command, parameters, timeout, directory });
                 }
             }, timeout);
@@ -564,7 +995,7 @@ export async function executeShellCommand(command, parameters = [], directory, o
                     return;
                 aborted = true;
                 markShellProcessCancelRequested(executionId);
-                childProcess.kill('SIGTERM');
+                requestTermination('abort');
                 logger.info('Shell command aborted by request', {
                     executionId,
                     command,
@@ -611,6 +1042,10 @@ export async function executeShellCommand(command, parameters = [], directory, o
             childProcess.on('close', (code, signal) => {
                 processExited = true;
                 clearTimeout(timeoutHandle);
+                if (timeoutForceKillHandle) {
+                    clearTimeout(timeoutForceKillHandle);
+                    timeoutForceKillHandle = null;
+                }
                 options.abortSignal?.removeEventListener('abort', abortHandler);
                 unsubscribeStatusListener?.();
                 unsubscribeStatusListener = null;
@@ -691,6 +1126,10 @@ export async function executeShellCommand(command, parameters = [], directory, o
             childProcess.on('error', (error) => {
                 processExited = true;
                 clearTimeout(timeoutHandle);
+                if (timeoutForceKillHandle) {
+                    clearTimeout(timeoutForceKillHandle);
+                    timeoutForceKillHandle = null;
+                }
                 options.abortSignal?.removeEventListener('abort', abortHandler);
                 unsubscribeStatusListener?.();
                 unsubscribeStatusListener = null;
@@ -918,6 +1357,241 @@ export function formatStructuredResult(result, artifacts = [], options = {}) {
         ...(stderrSnippet.truncated ? { stderr_truncated: true } : {})
     };
 }
+export function formatMinimalShellResult(result) {
+    const timedOut = Boolean(result.timedOut || result.error?.includes('timed out'));
+    const canceled = Boolean(result.canceled || result.error?.toLowerCase().includes('canceled'));
+    const inferredFailureReason = result.failureReason || inferShellFailureReason(String(result.error || ''));
+    const failed = timedOut || canceled || result.exitCode !== 0 || Boolean(result.error) || Boolean(inferredFailureReason);
+    let reason;
+    if (timedOut) {
+        reason = 'timeout';
+    }
+    else if (canceled) {
+        reason = 'canceled';
+    }
+    else if (inferredFailureReason) {
+        reason = inferredFailureReason;
+    }
+    else if (result.exitCode !== null && result.exitCode !== 0) {
+        reason = 'non_zero_exit';
+    }
+    else if (result.error) {
+        reason = 'execution_error';
+    }
+    return {
+        status: failed ? 'failed' : 'success',
+        exit_code: result.exitCode,
+        timed_out: timedOut,
+        canceled,
+        ...(reason ? { reason } : {})
+    };
+}
+export function formatMinimalShellResultForLLM(result) {
+    return formatPreviewShellResultForLLM(result);
+}
+function containsImageDataUri(text) {
+    return /data:image\/[a-z0-9.+-]+;base64,/i.test(String(text || ''));
+}
+/**
+ * Strip ANSI escape sequences and terminal control characters from shell output
+ * before sending to the LLM. Raw terminal output often contains spinner animations
+ * (◒◐◓◑), cursor-control codes (\x1b[?25l, \x1b[999D\x1b[J), and ANSI color codes
+ * that confuse LLMs into thinking a process is still running when it has already
+ * completed successfully (exit_code: 0).
+ *
+ * Strips:
+ *  - CSI sequences: \x1b[ ... final-byte  (colors, cursor movement, erase, etc.)
+ *  - OSC sequences: \x1b] ... \x07 or \x1b\  (terminal title/hyperlinks)
+ *  - DCS/SOS/PM/APC sequences: \x1bP/\x1bX/\x1b^/\x1b_ ... \x1b\
+ *  - Single-char Fe escapes: \x1b followed by non-[ byte
+ *  - Bare carriage returns used by spinner overwrites
+ */
+export function stripAnsiFromShellOutput(text) {
+    // CSI sequences: ESC [ ... (any intermediate+final byte)
+    let stripped = text.replace(/\x1b\[[0-9;?!#]*[a-zA-Z@`]/g, '');
+    // OSC sequences: ESC ] ... BEL or ESC\
+    stripped = stripped.replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '');
+    // DCS/SOS/PM/APC: ESC [P X ^ _] ... ESC\
+    stripped = stripped.replace(/\x1b[PX\^_].*?\x1b\\/gs, '');
+    // Remaining single-char Fe escapes (ESC followed by one non-[ char)
+    stripped = stripped.replace(/\x1b[^[]/g, '');
+    // Carriage returns used by spinner-overwrite pattern (keep newlines)
+    stripped = stripped.replace(/\r(?!\n)/g, '\n');
+    // Collapse multiple blank lines from the cleanup
+    stripped = stripped.replace(/\n{3,}/g, '\n\n');
+    return stripped;
+}
+function buildLLMPreviewField(content, maxOutputChars) {
+    const normalized = String(content || '');
+    if (!normalized) {
+        return { text: '', truncated: false, redacted: false };
+    }
+    if (containsImageDataUri(normalized)) {
+        return {
+            text: `omitted from LLM context (contains image data URI output; ${normalized.length} chars).`,
+            truncated: false,
+            redacted: true,
+        };
+    }
+    // Strip ANSI sequences before truncating so the LLM receives clean text.
+    // Without this, spinner animations and cursor-control codes in raw terminal
+    // output make the LLM think a completed process (exit_code: 0) is still running.
+    const clean = stripAnsiFromShellOutput(normalized);
+    const snippet = buildOutputSnippet(clean, maxOutputChars);
+    return {
+        text: snippet.text,
+        truncated: snippet.truncated,
+        redacted: false,
+    };
+}
+export function formatPreviewShellResult(result, options = {}) {
+    const minimal = formatMinimalShellResult(result);
+    const maxOutputChars = options.maxOutputChars ?? DEFAULT_LLM_PREVIEW_OUTPUT_CHARS;
+    const stderrSource = String(result.stderr || result.error || '');
+    const stdoutPreview = buildLLMPreviewField(result.stdout, maxOutputChars);
+    const stderrPreview = buildLLMPreviewField(stderrSource, maxOutputChars);
+    return {
+        ...minimal,
+        ...(stdoutPreview.text ? { stdout_preview: stdoutPreview.text } : {}),
+        ...(stderrPreview.text ? { stderr_preview: stderrPreview.text } : {}),
+        ...(stdoutPreview.truncated ? { stdout_truncated: true } : {}),
+        ...(stderrPreview.truncated ? { stderr_truncated: true } : {}),
+        ...(stdoutPreview.redacted ? { stdout_redacted: true } : {}),
+        ...(stderrPreview.redacted ? { stderr_redacted: true } : {}),
+    };
+}
+export function formatPreviewShellResultForLLM(result, options = {}) {
+    const preview = formatPreviewShellResult(result, options);
+    const lines = [
+        `status: ${preview.status}`,
+        `exit_code: ${preview.exit_code === null ? 'null' : String(preview.exit_code)}`,
+        `timed_out: ${preview.timed_out ? 'true' : 'false'}`,
+        `canceled: ${preview.canceled ? 'true' : 'false'}`
+    ];
+    if (preview.reason) {
+        lines.push(`reason: ${preview.reason}`);
+    }
+    if (preview.stdout_preview) {
+        lines.push('stdout_preview:');
+        lines.push(preview.stdout_preview);
+    }
+    if (preview.stdout_truncated) {
+        lines.push('stdout_truncated: true');
+    }
+    if (preview.stdout_redacted) {
+        lines.push('stdout_redacted: true');
+    }
+    if (preview.stderr_preview) {
+        lines.push('stderr_preview:');
+        lines.push(preview.stderr_preview);
+    }
+    if (preview.stderr_truncated) {
+        lines.push('stderr_truncated: true');
+    }
+    if (preview.stderr_redacted) {
+        lines.push('stderr_redacted: true');
+    }
+    return lines.join('\n');
+}
+export function formatShellToolErrorResultForLLM(options) {
+    const errorMessage = options.error instanceof Error ? options.error.message : String(options.error);
+    const parameters = Array.isArray(options.parameters)
+        ? options.parameters.map((parameter) => String(parameter))
+        : [];
+    return formatPreviewShellResultForLLM({
+        executionId: 'shell-tool-error',
+        command: typeof options.command === 'string' && options.command.trim()
+            ? options.command
+            : '<shell_cmd>',
+        parameters,
+        stdout: '',
+        stderr: errorMessage,
+        exitCode: null,
+        signal: null,
+        error: errorMessage,
+        failureReason: options.failureReason || inferShellFailureReason(errorMessage) || 'execution_error',
+        executedAt: new Date(),
+        duration: 0,
+    });
+}
+function buildShellToolResultContent(result, options) {
+    if (options.llmResultMode === 'minimal') {
+        if (options.outputFormat === 'json') {
+            return JSON.stringify(formatPreviewShellResult(result), null, 2);
+        }
+        return formatPreviewShellResultForLLM(result);
+    }
+    if (options.outputFormat === 'json') {
+        return JSON.stringify(formatStructuredResult(result, options.artifacts || [], { detail: options.outputDetail }), null, 2);
+    }
+    return formatResultForLLM(result, { detail: options.outputDetail });
+}
+function buildShellToolPreviewEnvelope(result, options) {
+    const resultContent = buildShellToolResultContent(result, {
+        llmResultMode: options.llmResultMode,
+        outputFormat: options.outputFormat,
+        outputDetail: options.outputDetail,
+        artifacts: options.artifacts,
+    });
+    const previewItems = [
+        createTextToolPreview(options.outputFormat === 'json'
+            ? resultContent
+            : formatResultForLLM(result, { detail: options.outputDetail }), { markdown: options.outputFormat !== 'json', title: 'shell_cmd result' }),
+        ...(options.artifacts || []).map((artifact) => createArtifactToolPreview({
+            path: artifact.path,
+            bytes: artifact.bytes,
+            display_name: artifact.path,
+            ...(options.worldId ? { url: buildToolArtifactPreviewUrl({ path: artifact.path, worldId: options.worldId }) } : {}),
+        })),
+    ];
+    return {
+        __type: 'tool_execution_envelope',
+        version: 1,
+        tool: 'shell_cmd',
+        ...(options.toolCallId ? { tool_call_id: options.toolCallId } : {}),
+        status: result.exitCode === 0 && !result.error && !result.timedOut && !result.canceled ? 'completed' : 'failed',
+        preview: previewItems,
+        result: resultContent,
+    };
+}
+function formatShellToolReturnContent(result, options) {
+    if (!options.persistToolEnvelope) {
+        return buildShellToolResultContent(result, {
+            llmResultMode: options.llmResultMode,
+            outputFormat: options.outputFormat,
+            outputDetail: options.outputDetail,
+            artifacts: options.artifacts,
+        });
+    }
+    return serializeToolExecutionEnvelope(buildShellToolPreviewEnvelope(result, options));
+}
+export function formatShellToolErrorEnvelopeContent(options) {
+    const errorMessage = options.error instanceof Error ? options.error.message : String(options.error);
+    const parameters = Array.isArray(options.parameters)
+        ? options.parameters.map((parameter) => String(parameter))
+        : [];
+    const result = {
+        executionId: 'shell-tool-error',
+        command: typeof options.command === 'string' && options.command.trim()
+            ? options.command
+            : '<shell_cmd>',
+        parameters,
+        stdout: '',
+        stderr: errorMessage,
+        exitCode: null,
+        signal: null,
+        error: errorMessage,
+        failureReason: options.failureReason || inferShellFailureReason(errorMessage) || 'execution_error',
+        executedAt: new Date(),
+        duration: 0,
+    };
+    return serializeToolExecutionEnvelope(buildShellToolPreviewEnvelope(result, {
+        llmResultMode: 'minimal',
+        outputFormat: 'markdown',
+        outputDetail: 'minimal',
+        toolCallId: options.toolCallId,
+    }));
+}
 /**
  * Format command execution result for LLM consumption
  * Provides a human-readable summary of the execution with improved markdown formatting
@@ -1076,81 +1750,219 @@ export function createShellCmdToolDefinition() {
                 },
                 required: ['command']
             };
+            const llmResultMode = typeof context?.llmResultMode === 'string'
+                ? context.llmResultMode === 'verbose' ? 'verbose' : 'minimal'
+                : 'verbose';
+            const persistToolEnvelope = context?.persistToolEnvelope === true;
             const validation = validateToolParameters(args, toolSchema, 'shell_cmd');
             if (!validation.valid) {
-                return formatResultForLLM({
+                const validationResult = {
                     executionId: 'validation-error',
                     command: args?.command || '<invalid>',
                     parameters: [],
-                    exitCode: 1,
+                    exitCode: null,
                     signal: null,
                     error: validation.error,
+                    failureReason: 'validation_error',
                     stdout: '',
                     stderr: '',
                     executedAt: new Date(),
                     duration: 0
+                };
+                const validationOutputFormat = validation.correctedArgs?.output_format === 'json' ? 'json' : 'markdown';
+                return formatShellToolReturnContent(validationResult, {
+                    llmResultMode,
+                    outputFormat: validationOutputFormat,
+                    outputDetail: 'minimal',
+                    toolCallId: typeof context?.toolCallId === 'string' ? context.toolCallId : undefined,
+                    persistToolEnvelope,
+                    worldId: typeof context?.world?.id === 'string' ? context.world.id : undefined,
                 });
             }
             const { command, parameters = [], timeout, output_format: outputFormat = 'markdown', output_detail: outputDetail = 'minimal', artifact_paths: artifactPaths = [] } = validation.correctedArgs;
             // Ensure parameters is always an array
-            const validParameters = Array.isArray(parameters) ?
+            const rawParameters = Array.isArray(parameters) ?
                 parameters.filter((p) => typeof p === 'string') :
                 [];
+            const chatIdRaw = typeof context?.chatId === 'string' ? context.chatId.trim() : '';
+            const chatId = chatIdRaw || undefined;
+            // Resolve skill-relative script paths (e.g. <skill-id>/scripts/foo.py) to absolute paths
+            const resolvedDirectory = resolveTrustedShellWorkingDirectory(context);
+            const runtimeSkillsRoot = join(resolveDirectory(resolvedDirectory), '.agents', 'skills');
+            const skillOriginatedRequest = hasActiveSkillContext(context?.messages, chatId);
+            const { resolvedParameters: validParameters, skillRoots } = resolveSkillScriptParameters(rawParameters, runtimeSkillsRoot, { allowBareScriptsResolution: skillOriginatedRequest });
             // Extract world and messageId from context for streaming
             const world = context?.world;
             const currentMessageId = context?.toolCallId;
-            const chatId = context?.chatId ? String(context.chatId) : undefined;
             const abortSignal = context?.abortSignal;
-            const resolvedDirectory = resolveTrustedShellWorkingDirectory(context);
+            const streamAgentName = typeof context?.agentName === 'string' && context.agentName.trim()
+                ? context.agentName.trim()
+                : 'assistant';
+            const hasToolStreamContext = Boolean(world
+                && chatId
+                && typeof currentMessageId === 'string'
+                && currentMessageId.trim());
+            const streamBaseMessageId = hasToolStreamContext ? String(currentMessageId).trim() : '';
+            const stdoutMessageId = streamBaseMessageId ? `${streamBaseMessageId}-stdout` : '';
             const directoryValidation = validateShellDirectoryRequest(validation.correctedArgs.directory, resolvedDirectory);
             if (!directoryValidation.valid) {
                 throw new Error(directoryValidation.error);
             }
-            const scopeValidation = validateShellCommandScope(command, validParameters, resolvedDirectory);
+            const scopeValidation = validateShellCommandScope(command, validParameters, resolvedDirectory, skillRoots);
             if (!scopeValidation.valid) {
                 throw new Error(scopeValidation.error);
             }
-            // Execute command with streaming callbacks if world is available
+            const riskAssessment = classifyShellCommandRisk(command, validParameters);
+            if (riskAssessment.tier === 'block') {
+                throw new Error(`Blocked dangerous operation: ${riskAssessment.reason}. This shell command cannot be executed.`);
+            }
+            // Check world-level tool permission
+            const toolPermission = getEnvValueFromText(world?.variables, 'tool_permission') ?? 'auto';
+            if (toolPermission === 'read') {
+                const blockedResult = {
+                    executionId: 'permission-blocked',
+                    command,
+                    parameters: validParameters,
+                    exitCode: null,
+                    signal: null,
+                    error: 'shell_cmd is blocked by the current permission level (read).',
+                    failureReason: 'validation_error',
+                    stdout: '',
+                    stderr: '',
+                    executedAt: new Date(),
+                    duration: 0,
+                };
+                return formatShellToolReturnContent(blockedResult, {
+                    llmResultMode,
+                    outputFormat: outputFormat === 'json' ? 'json' : 'markdown',
+                    outputDetail: 'minimal',
+                    toolCallId: typeof currentMessageId === 'string' ? currentMessageId : undefined,
+                    persistToolEnvelope,
+                    worldId: typeof world?.id === 'string' ? world.id : undefined,
+                });
+            }
+            // At 'ask' level, every shell_cmd invocation requires HITL approval regardless of risk tier.
+            if (toolPermission === 'ask' && riskAssessment.tier !== 'hitl_required') {
+                if (!world) {
+                    throw new Error('Approval required: world-level permission is "ask" but HITL approval context is unavailable.');
+                }
+                const askApproval = await requestShellCommandRiskApproval({
+                    world,
+                    chatId: chatId ?? null,
+                    command,
+                    parameters: validParameters,
+                    resolvedDirectory,
+                    risk: { tier: 'hitl_required', reason: 'world permission level is "ask"', tags: ['ask-permission'] },
+                    toolCallId: typeof currentMessageId === 'string' ? currentMessageId : undefined,
+                    agentName: streamAgentName,
+                    messages: Array.isArray(context?.messages) ? context.messages : undefined,
+                });
+                if (!askApproval.approved) {
+                    throw new Error(`Command not executed: world permission is "ask" and the request was not approved (${askApproval.reason}).`);
+                }
+            }
+            if (riskAssessment.tier === 'hitl_required') {
+                if (!world) {
+                    throw new Error(`Approval required: command classified as ${riskAssessment.reason}. HITL approval context is unavailable.`);
+                }
+                const approval = await requestShellCommandRiskApproval({
+                    world,
+                    chatId: chatId ?? null,
+                    command,
+                    parameters: validParameters,
+                    resolvedDirectory,
+                    risk: riskAssessment,
+                    toolCallId: typeof currentMessageId === 'string' ? currentMessageId : undefined,
+                    agentName: streamAgentName,
+                    messages: Array.isArray(context?.messages) ? context.messages : undefined,
+                });
+                if (!approval.approved) {
+                    throw new Error(`Command not executed: approval required for ${riskAssessment.reason} and request was not approved (${approval.reason}).`);
+                }
+            }
+            let stdoutStartEmitted = false;
+            const emitStdoutToolStreamChunk = (chunk) => {
+                if (!hasToolStreamContext)
+                    return;
+                if (!chunk)
+                    return;
+                if (!stdoutMessageId)
+                    return;
+                if (!stdoutStartEmitted) {
+                    publishSSE(world, {
+                        type: 'start',
+                        toolName: 'shell_cmd',
+                        messageId: stdoutMessageId,
+                        agentName: streamAgentName,
+                        chatId
+                    });
+                    stdoutStartEmitted = true;
+                }
+                publishSSE(world, {
+                    type: 'chunk',
+                    toolName: 'shell_cmd',
+                    content: chunk,
+                    stream: 'stdout',
+                    messageId: stdoutMessageId,
+                    agentName: streamAgentName,
+                    chatId
+                });
+            };
+            const emitStderrToolStreamChunk = (chunk) => {
+                if (!world || !chatId || !chunk)
+                    return;
+                publishSSE(world, {
+                    type: 'tool-stream',
+                    toolName: 'shell_cmd',
+                    content: chunk,
+                    stream: 'stderr',
+                    messageId: currentMessageId,
+                    agentName: 'shell_cmd',
+                    chatId
+                });
+            };
+            // Execute command with tool-streaming callbacks when world context is available
             const result = await executeShellCommand(command, validParameters, resolvedDirectory, {
                 timeout,
                 abortSignal,
                 worldId: world?.id,
                 chatId,
                 trustedWorkingDirectory: resolvedDirectory,
-                onStdout: world ? (chunk) => {
-                    // Publish streaming events to world event system
-                    publishSSE(world, {
-                        type: 'tool-stream',
-                        toolName: 'shell_cmd',
-                        content: chunk,
-                        stream: 'stdout',
-                        messageId: currentMessageId,
-                        agentName: 'shell_cmd'
-                    });
+                onStdout: hasToolStreamContext ? (chunk) => {
+                    emitStdoutToolStreamChunk(chunk);
                 } : undefined,
                 onStderr: world ? (chunk) => {
-                    // Publish streaming events to world event system
-                    publishSSE(world, {
-                        type: 'tool-stream',
-                        toolName: 'shell_cmd',
-                        content: chunk,
-                        stream: 'stderr',
-                        messageId: currentMessageId,
-                        agentName: 'shell_cmd'
-                    });
+                    emitStderrToolStreamChunk(chunk);
                 } : undefined
             });
             if (isCommandExecutionCanceled(result)) {
                 throw new DOMException('Shell command execution canceled by user', 'AbortError');
             }
+            // Emit SSE end only. Durable completion state now comes from the final tool result.
+            if (hasToolStreamContext && stdoutMessageId && stdoutStartEmitted) {
+                publishSSE(world, {
+                    type: 'end',
+                    toolName: 'shell_cmd',
+                    messageId: stdoutMessageId,
+                    agentName: streamAgentName,
+                    chatId
+                });
+            }
             const validatedArtifactPaths = Array.isArray(artifactPaths)
                 ? artifactPaths.filter((artifactPath) => typeof artifactPath === 'string')
                 : [];
-            const artifacts = await collectCommandArtifacts(validatedArtifactPaths, resolvedDirectory);
-            if (outputFormat === 'json') {
-                return JSON.stringify(formatStructuredResult(result, artifacts, { detail: outputDetail }), null, 2);
-            }
-            return formatResultForLLM(result, { detail: outputDetail });
+            const artifacts = llmResultMode === 'minimal'
+                ? []
+                : await collectCommandArtifacts(validatedArtifactPaths, resolvedDirectory);
+            return formatShellToolReturnContent(result, {
+                llmResultMode,
+                outputFormat,
+                outputDetail,
+                toolCallId: typeof context?.toolCallId === 'string' ? context.toolCallId : undefined,
+                persistToolEnvelope,
+                artifacts,
+                worldId: typeof context?.world?.id === 'string' ? context.world.id : undefined,
+            });
         }
     };
 }