agent-world 0.13.0 → 0.15.0

package/dist/core/load-skill-tool.js

@@ -18,9 +18,19 @@
  * - Keeps payload format deterministic for stable downstream parsing
  *
  * Recent Changes:
- * - 2026-02-16: Treat non-zero exit status from instruction-referenced skill scripts as execution errors so UI receives tool-error feedback.
- * - 2026-02-15: Reject `load_skill` script execution when a referenced script resolves outside the active execution working directory.
- * - 2026-02-15: Execute skill scripts in the project working directory (from context) instead of the skill root.
+ * - 2026-03-12: Added `read` permission level guard to script execution — instructions load normally but all script execution steps are blocked with an inline note when toolPermission is 'read'.
+ * - 2026-03-06: Removed `world.currentChatId` fallback from interactive approval/result scoping; interactive `load_skill` now requires explicit `context.chatId`.
+ * - 2026-03-01: Removed minimal-check mode branch so `load_skill` always runs script/reference preflight consistently and keeps script-root execution guidance available.
+ * - 2026-03-01: Relaxed execution-directive narration requirements to avoid mandatory pre-tool plan text and reduce token overhead.
+ * - 2026-03-01: Added skill-description thread-through and acknowledgment-first execution directive requirements after successful `load_skill`, including unconditional pre-execution plan narration.
+ * - 2026-02-28: Updated `<execution_directive>` to require concise tool-use intent text before tool calls and to allow mixed text + tool-call turns when supported by the provider.
+ * - 2026-02-27: Run-scoped `load_skill` cache now stores only successful outcomes so declined/error/not-found paths remain retryable in the same run.
+ * - 2026-02-27: Added run-scoped `load_skill` result caching keyed by latest user-turn marker so repeated same-skill calls are auto-suppressed across assistant/tool hops.
+ * - 2026-02-27: Replaced `[load_skill:hitl]` console logs with structured category logger events (`load_skill.hitl`).
+ * - 2026-02-27: Added same-turn `yes_once` approval reuse + in-flight approval dedupe so repeated/concurrent `load_skill` calls for the same skill do not spam duplicate HITL prompts.
+ * - 2026-02-25: Added persisted synthetic HITL tool-call/response messages for `load_skill` approval so frontends can reconstruct prompts from memory without relying on transient event timing.
+ * - 2026-02-24: Surface non-zero script exits as informational output instead of blocking errors (scripts may be CLI tools requiring args).
+ * - 2026-02-24: Execute skill scripts with cwd set to trusted working directory when provided, otherwise use the skill root.
  * - 2026-02-14: Strip SKILL.md YAML front matter from injected `<instructions>` content.
  * - 2026-02-14: Omit `<active_resources>` from `load_skill` payloads when no instruction-referenced scripts are present.
  * - 2026-02-14: Added skill-level HITL gating so `load_skill` requires approval even when no script references are present.
@@ -29,14 +39,25 @@
 import { promises as fs } from 'fs';
 import * as path from 'path';
 import { getSkill, getSkillSourcePath, getSkillSourceScope, waitForInitialSkillSync, } from './skill-registry.js';
+import { createStorageWithWrappers } from './storage/storage-factory.js';
 import { executeShellCommand, formatResultForLLM, validateShellCommandScope, } from './shell-cmd-tool.js';
+import { buildToolArtifactPreviewUrl, createArtifactToolPreview, createTextToolPreview, createUrlToolPreview, guessMediaTypeFromPath, parseToolExecutionEnvelopeContent, serializeToolExecutionEnvelope, } from './tool-execution-envelope.js';
+import { createCategoryLogger } from './logger.js';
 import { parseSkillIdListFromEnv } from './skill-settings.js';
-import { requestWorldOption } from './hitl.js';
+import { generateId, getEnvValueFromText } from './utils.js';
+import { requestToolApproval } from './tool-approval.js';
 const APPROVAL_OPTION_YES_ONCE = 'yes_once';
 const APPROVAL_OPTION_YES_IN_SESSION = 'yes_in_session';
 const APPROVAL_OPTION_NO = 'no';
 const SCRIPT_TIMEOUT_MS = 120_000;
+const LOAD_SKILL_RUN_RESULT_CACHE_LIMIT = 256;
 const skillSessionApprovals = new Set();
+const skillTurnApprovals = new Set();
+const inFlightSkillApprovals = new Map();
+const loadSkillRunResultCache = new Map();
+const inFlightLoadSkillRunResults = new Map();
+const loggerLoadSkillHitl = createCategoryLogger('load_skill.hitl');
+const LOAD_SKILL_PREVIEW_SCRIPT_OUTPUT_CHARS = 800;
 class SkillScriptExecutionError extends Error {
     constructor(message) {
         super(message);
@@ -92,6 +113,13 @@ function buildDisabledBySettingsResult(skillId) {
         '</skill_context>',
     ].join('\n');
 }
+function truncatePreviewText(text, maxChars = LOAD_SKILL_PREVIEW_SCRIPT_OUTPUT_CHARS) {
+    const normalized = String(text || '').trim();
+    if (normalized.length <= maxChars) {
+        return normalized;
+    }
+    return `${normalized.slice(0, maxChars)}\n...[truncated ${normalized.length - maxChars} chars]`;
+}
 function isSkillEnabledBySettings(skillId) {
     const includeGlobalSkills = String(process.env.AGENT_WORLD_ENABLE_GLOBAL_SKILLS ?? 'true').toLowerCase() !== 'false';
     const includeProjectSkills = String(process.env.AGENT_WORLD_ENABLE_PROJECT_SKILLS ?? 'true').toLowerCase() !== 'false';
@@ -110,14 +138,33 @@ function isSkillEnabledBySettings(skillId) {
 function normalizeScriptPath(scriptPath) {
     return scriptPath.replace(/\\/g, '/').replace(/^\.\//, '').trim();
 }
+function normalizeComparablePath(targetPath) {
+    const resolvedPath = path.resolve(targetPath).replace(/\\/g, '/');
+    return process.platform === 'win32'
+        ? resolvedPath.replace(/\/+/g, '/').replace(/\/$/, '')
+        : resolvedPath.replace(/\/+/g, '/').replace(/\/$/, '') || '/';
+}
+function normalizeAbsoluteLocalPath(targetPath) {
+    return normalizeComparablePath(targetPath);
+}
+function toRootRelativePath(rootPath, targetPath) {
+    const normalizedRoot = normalizeComparablePath(rootPath);
+    const normalizedTarget = normalizeComparablePath(targetPath);
+    if (normalizedTarget === normalizedRoot) {
+        return '';
+    }
+    if (normalizedTarget.startsWith(`${normalizedRoot}/`)) {
+        return normalizedTarget.slice(normalizedRoot.length + 1);
+    }
+    return normalizedTarget.replace(/^\/+/, '');
+}
 function stripYamlFrontMatter(markdown) {
     const frontMatterPattern = /^\uFEFF?---\s*\r?\n[\s\S]*?\r?\n---\s*(?:\r?\n|$)/;
     return markdown.replace(frontMatterPattern, '');
 }
 function isPathWithinRoot(skillRoot, targetPath) {
-    const normalize = (value) => path.resolve(value).replace(/\\/g, '/').replace(/\/+/g, '/').replace(/\/$/, '');
-    const normalizedRoot = normalize(skillRoot);
-    const normalizedTarget = normalize(targetPath);
+    const normalizedRoot = normalizeComparablePath(skillRoot);
+    const normalizedTarget = normalizeComparablePath(targetPath);
     return normalizedTarget === normalizedRoot || normalizedTarget.startsWith(`${normalizedRoot}/`);
 }
 function extractReferencedScriptPaths(markdown) {
@@ -160,14 +207,14 @@ async function collectReferenceFiles(skillRoot, markdown) {
         if (linkedPath.startsWith('#')) {
             continue;
         }
-        const absolutePath = path.resolve(skillRoot, linkedPath);
+        const absolutePath = normalizeAbsoluteLocalPath(path.resolve(skillRoot, linkedPath));
         if (!isPathWithinRoot(skillRoot, absolutePath)) {
             continue;
         }
         try {
             const stat = await fs.stat(absolutePath);
             if (stat.isFile()) {
-                collected.add(path.relative(skillRoot, absolutePath).replace(/\\/g, '/'));
+                collected.add(toRootRelativePath(skillRoot, absolutePath));
             }
         }
         catch {
@@ -197,12 +244,12 @@ async function collectReferenceFiles(skillRoot, markdown) {
         }
         entries.sort((left, right) => left.name.localeCompare(right.name));
         for (const entry of entries) {
-            const absolutePath = path.join(currentPath, entry.name);
+            const absolutePath = normalizeAbsoluteLocalPath(path.join(currentPath, entry.name));
             if (entry.isDirectory()) {
                 queue.push(absolutePath);
             }
             else if (entry.isFile()) {
-                collected.add(path.relative(skillRoot, absolutePath).replace(/\\/g, '/'));
+                collected.add(toRootRelativePath(skillRoot, absolutePath));
             }
         }
     }
@@ -230,54 +277,442 @@ function formatReferenceFilesBlock(referenceFiles) {
 function createSessionApprovalKey(worldId, chatId, skillId) {
     return `${worldId}::${chatId ?? 'global'}::${skillId}`;
 }
+function getExplicitContextChatId(context) {
+    const chatId = typeof context?.chatId === 'string' ? context.chatId.trim() : '';
+    return chatId || null;
+}
+function getCurrentTurnMarker(context) {
+    const chatId = getExplicitContextChatId(context);
+    const messages = Array.isArray(context?.messages) ? context.messages : [];
+    if (!chatId || messages.length === 0) {
+        return null;
+    }
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (message?.role !== 'user') {
+            continue;
+        }
+        const messageChatId = message?.chatId ? String(message.chatId).trim() : null;
+        if (messageChatId && messageChatId !== chatId) {
+            continue;
+        }
+        const messageId = String(message?.messageId || '').trim();
+        if (messageId) {
+            return `msg:${messageId}`;
+        }
+        const createdAt = message?.createdAt ? new Date(message.createdAt) : null;
+        if (createdAt && Number.isFinite(createdAt.valueOf())) {
+            return `ts:${createdAt.toISOString()}`;
+        }
+        const content = String(message?.content || '').trim();
+        if (content) {
+            return `content:${content.slice(0, 80)}`;
+        }
+        return `idx:${index}`;
+    }
+    return null;
+}
+function createTurnApprovalKey(worldId, chatId, skillId, turnMarker) {
+    return `${worldId}::${chatId ?? 'global'}::${skillId}::turn::${turnMarker}`;
+}
+function createRunResultKey(worldId, chatId, skillId, turnMarker) {
+    return `${worldId}::${chatId ?? 'global'}::${skillId}::run::${turnMarker}`;
+}
+/**
+ * Reconstruct skill approval caches from persisted message history.
+ * Called during chat restore so that `yes_in_session` and `yes_once` grants
+ * survive app restarts without re-prompting the user.
+ *
+ * Scans `role: 'tool'` messages whose JSON content contains `skillId` and
+ * `optionId` fields (written by `persistLoadSkillApprovalResolutionMessage`).
+ *
+ * - `yes_in_session` grants are restored unconditionally (session-scoped).
+ * - `yes_once` grants are restored only when they belong to the current turn
+ *   (i.e. appear after the last `role: 'user'` message in the history).
+ */
+export function reconstructSkillApprovalsFromMessages(worldId, chatId, messages) {
+    if (!worldId || !Array.isArray(messages) || messages.length === 0) {
+        return 0;
+    }
+    // Find the index of the last user message for this chat (turn boundary).
+    let lastUserMessageIndex = -1;
+    let turnMarker = null;
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const msg = messages[i];
+        if (msg?.role !== 'user')
+            continue;
+        const msgChatId = msg?.chatId ? String(msg.chatId).trim() : null;
+        if (msgChatId && msgChatId !== (chatId ?? 'global'))
+            continue;
+        lastUserMessageIndex = i;
+        // Derive turn marker using same precedence as getCurrentTurnMarker.
+        const messageId = String(msg?.messageId || '').trim();
+        if (messageId) {
+            turnMarker = `msg:${messageId}`;
+        }
+        else {
+            const createdAt = msg?.createdAt ? new Date(msg.createdAt) : null;
+            if (createdAt && Number.isFinite(createdAt.valueOf())) {
+                turnMarker = `ts:${createdAt.toISOString()}`;
+            }
+            else {
+                const content = String(msg?.content || '').trim();
+                if (content) {
+                    turnMarker = `content:${content.slice(0, 80)}`;
+                }
+                else {
+                    turnMarker = `idx:${i}`;
+                }
+            }
+        }
+        break;
+    }
+    let restored = 0;
+    for (let i = 0; i < messages.length; i += 1) {
+        const msg = messages[i];
+        if (msg?.role !== 'tool')
+            continue;
+        let payload = null;
+        try {
+            const content = typeof msg.content === 'string' ? msg.content : null;
+            if (content)
+                payload = JSON.parse(content);
+        }
+        catch {
+            continue;
+        }
+        if (!payload
+            || typeof payload.requestId !== 'string'
+            || !payload.requestId.includes('load_skill_approval')
+            || typeof payload.skillId !== 'string'
+            || typeof payload.optionId !== 'string') {
+            continue;
+        }
+        const { skillId, optionId } = payload;
+        if (optionId === APPROVAL_OPTION_YES_IN_SESSION) {
+            skillSessionApprovals.add(createSessionApprovalKey(worldId, chatId, skillId));
+            restored += 1;
+        }
+        else if (optionId === APPROVAL_OPTION_YES_ONCE && turnMarker && i > lastUserMessageIndex) {
+            skillTurnApprovals.add(createTurnApprovalKey(worldId, chatId, skillId, turnMarker));
+            restored += 1;
+        }
+    }
+    if (restored > 0) {
+        loggerLoadSkillHitl.debug('Reconstructed skill approvals from message history', {
+            worldId,
+            chatId: chatId || null,
+            restored,
+        });
+    }
+    return restored;
+}
+/**
+ * Clear cached skill approvals and run results scoped to a specific chat.
+ * Must be called when messages are removed (e.g. edit+resubmit) so that
+ * HITL approval prompts fire again for the reprocessed message.
+ */
+export function clearChatSkillApprovals(worldId, chatId) {
+    const chatToken = chatId ?? 'global';
+    const prefix = `${worldId}::${chatToken}::`;
+    for (const key of skillSessionApprovals) {
+        if (key.startsWith(prefix)) {
+            skillSessionApprovals.delete(key);
+        }
+    }
+    for (const key of skillTurnApprovals) {
+        if (key.startsWith(prefix)) {
+            skillTurnApprovals.delete(key);
+        }
+    }
+    for (const key of inFlightSkillApprovals.keys()) {
+        if (key.includes(prefix)) {
+            inFlightSkillApprovals.delete(key);
+        }
+    }
+    for (const key of loadSkillRunResultCache.keys()) {
+        if (key.startsWith(prefix)) {
+            loadSkillRunResultCache.delete(key);
+        }
+    }
+    for (const key of inFlightLoadSkillRunResults.keys()) {
+        if (key.startsWith(prefix)) {
+            inFlightLoadSkillRunResults.delete(key);
+        }
+    }
+}
+function getRunScopedLoadSkillResultKey(skillId, context) {
+    const worldId = String(context?.world?.id || '').trim();
+    if (!worldId) {
+        return null;
+    }
+    const chatId = getExplicitContextChatId(context);
+    if (!chatId) {
+        return null;
+    }
+    const turnMarker = getCurrentTurnMarker(context);
+    if (!turnMarker) {
+        return null;
+    }
+    return createRunResultKey(worldId, chatId, skillId, turnMarker);
+}
+function rememberRunScopedLoadSkillResult(cacheKey, result) {
+    if (loadSkillRunResultCache.has(cacheKey)) {
+        loadSkillRunResultCache.delete(cacheKey);
+    }
+    loadSkillRunResultCache.set(cacheKey, result);
+    while (loadSkillRunResultCache.size > LOAD_SKILL_RUN_RESULT_CACHE_LIMIT) {
+        const oldestKey = loadSkillRunResultCache.keys().next().value;
+        if (!oldestKey) {
+            break;
+        }
+        loadSkillRunResultCache.delete(oldestKey);
+    }
+}
+function getLoadSkillApprovalRequestId(context, skillId) {
+    const parentToolCallId = String(context?.toolCallId || '').trim();
+    if (parentToolCallId) {
+        return `${parentToolCallId}::load_skill_approval`;
+    }
+    const normalizedSkillId = String(skillId || '').trim() || 'skill';
+    return `load_skill_approval::${normalizedSkillId}::${generateId()}`;
+}
+async function persistAgentMemoryIfAvailable(context) {
+    const worldId = String(context?.world?.id || '').trim();
+    const agentName = String(context?.agentName || '').trim();
+    const messages = Array.isArray(context?.messages) ? context.messages : null;
+    const world = context?.world;
+    if (!worldId || !agentName || !messages || !world?.agents || typeof world.agents.get !== 'function') {
+        return;
+    }
+    const agent = world.agents.get(agentName);
+    if (!agent) {
+        return;
+    }
+    const storage = await createStorageWithWrappers();
+    await storage.saveAgent(worldId, agent);
+}
+async function persistLoadSkillApprovalPromptMessage(options) {
+    const messages = Array.isArray(options.context?.messages) ? options.context.messages : null;
+    if (!messages) {
+        return;
+    }
+    const existing = messages.some((message) => message?.role === 'assistant'
+        && Array.isArray(message?.tool_calls)
+        && message.tool_calls.some((toolCall) => String(toolCall?.id || '').trim() === options.requestId));
+    if (existing) {
+        return;
+    }
+    const question = `Skill "${options.skillId}" requested execution.${options.scriptPaths.length > 0 ? ` Referenced scripts:\n${options.scriptPaths.map((scriptPath) => `- ${scriptPath}`).join('\n')}` : ''}\n\nApprove applying this skill now?`;
+    const toolArguments = {
+        question,
+        options: [
+            { id: APPROVAL_OPTION_YES_ONCE, label: 'Yes once' },
+            { id: APPROVAL_OPTION_YES_IN_SESSION, label: 'Yes in this session' },
+            { id: APPROVAL_OPTION_NO, label: 'No' },
+        ],
+        defaultOptionId: APPROVAL_OPTION_NO,
+        defaultOption: 'No',
+        metadata: {
+            tool: 'human_intervention_request',
+            toolCallId: options.requestId,
+            source: 'load_skill',
+            skillId: options.skillId,
+            scriptPaths: options.scriptPaths,
+        },
+    };
+    const chatId = getExplicitContextChatId(options.context);
+    if (!chatId) {
+        return;
+    }
+    const agentName = String(options.context?.agentName || '').trim() || 'assistant';
+    messages.push({
+        role: 'assistant',
+        content: `Calling tool: human_intervention_request (skill_id: "${options.skillId}")`,
+        tool_calls: [{
+                id: options.requestId,
+                type: 'function',
+                function: {
+                    name: 'human_intervention_request',
+                    arguments: JSON.stringify(toolArguments),
+                },
+            }],
+        sender: agentName,
+        createdAt: new Date(),
+        chatId,
+        messageId: generateId(),
+        replyToMessageId: options.context?.toolCallId,
+        agentId: agentName,
+    });
+    await persistAgentMemoryIfAvailable(options.context);
+    loggerLoadSkillHitl.debug('Persisted load_skill approval tool-call message', {
+        chatId: chatId || null,
+        agentName,
+        requestId: options.requestId,
+        skillId: options.skillId,
+    });
+}
+async function persistLoadSkillApprovalResolutionMessage(options) {
+    const messages = Array.isArray(options.context?.messages) ? options.context.messages : null;
+    if (!messages) {
+        return;
+    }
+    const existing = messages.some((message) => message?.role === 'tool'
+        && String(message?.tool_call_id || '').trim() === options.requestId);
+    if (existing) {
+        return;
+    }
+    const chatId = getExplicitContextChatId(options.context);
+    if (!chatId) {
+        return;
+    }
+    const agentName = String(options.context?.agentName || '').trim() || 'assistant';
+    const payload = {
+        requestId: options.resolution.requestId,
+        optionId: options.resolution.optionId,
+        source: options.resolution.source,
+        skillId: options.skillId,
+    };
+    messages.push({
+        role: 'tool',
+        content: JSON.stringify(payload),
+        tool_call_id: options.requestId,
+        sender: agentName,
+        createdAt: new Date(),
+        chatId,
+        messageId: generateId(),
+        agentId: agentName,
+    });
+    await persistAgentMemoryIfAvailable(options.context);
+    loggerLoadSkillHitl.debug('Persisted load_skill approval tool-result message', {
+        chatId: chatId || null,
+        agentName,
+        requestId: options.requestId,
+        optionId: options.resolution.optionId,
+    });
+}
 async function requestSkillExecutionApproval(options) {
-    const worldId = String(options.context?.world?.id || '').trim();
-    const chatId = options.context?.chatId ?? options.context?.world?.currentChatId ?? null;
-    if (!worldId || !options.context?.world) {
+    const worldContext = options.context?.world;
+    const worldId = String(worldContext?.id || '').trim();
+    const chatId = getExplicitContextChatId(options.context);
+    const requestId = getLoadSkillApprovalRequestId(options.context, options.skillId);
+    if (!worldId || !worldContext) {
         return true;
     }
+    if (!chatId) {
+        return false;
+    }
     const sessionApprovalKey = createSessionApprovalKey(worldId, chatId, options.skillId);
+    const turnMarker = getCurrentTurnMarker(options.context);
+    const turnApprovalKey = turnMarker
+        ? createTurnApprovalKey(worldId, chatId, options.skillId, turnMarker)
+        : null;
     if (skillSessionApprovals.has(sessionApprovalKey)) {
         return true;
     }
-    const scriptSummary = options.scriptPaths.length > 0
-        ? `The skill references local scripts:\n${options.scriptPaths.map((scriptPath) => `- ${scriptPath}`).join('\n')}`
-        : 'No instruction-referenced local scripts were detected for this skill.';
-    const approval = await requestWorldOption(options.context.world, {
-        title: `Run skill ${options.skillId}?`,
-        message: [
-            `Skill "${options.skillId}" requested execution.`,
-            scriptSummary,
-            'Approve applying this skill now?',
-        ].join('\n\n'),
-        chatId,
-        defaultOptionId: APPROVAL_OPTION_NO,
-        options: [
-            { id: APPROVAL_OPTION_YES_ONCE, label: 'Yes once', description: 'Allow this skill for this call only.' },
-            {
-                id: APPROVAL_OPTION_YES_IN_SESSION,
-                label: 'Yes in this session',
-                description: 'Allow this skill for the current chat session.',
+    if (turnApprovalKey && skillTurnApprovals.has(turnApprovalKey)) {
+        return true;
+    }
+    const inFlightApprovalKey = turnApprovalKey
+        ? `turn::${turnApprovalKey}`
+        : `session::${sessionApprovalKey}`;
+    const existingInFlightApproval = inFlightSkillApprovals.get(inFlightApprovalKey);
+    if (existingInFlightApproval) {
+        return await existingInFlightApproval;
+    }
+    const approvalPromise = (async () => {
+        const scriptSummary = options.scriptPaths.length > 0
+            ? `The skill references local scripts:\n${options.scriptPaths.map((scriptPath) => `- ${scriptPath}`).join('\n')}`
+            : 'No instruction-referenced local scripts were detected for this skill.';
+        await persistLoadSkillApprovalPromptMessage({
+            context: options.context,
+            requestId,
+            skillId: options.skillId,
+            scriptPaths: options.scriptPaths,
+        });
+        const approvalResult = await requestToolApproval({
+            world: worldContext,
+            requestId,
+            title: `Run skill ${options.skillId}?`,
+            message: [
+                `Skill "${options.skillId}" requested execution.`,
+                scriptSummary,
+                'Approve applying this skill now?',
+            ].join('\n\n'),
+            chatId,
+            defaultOptionId: APPROVAL_OPTION_NO,
+            options: [
+                { id: APPROVAL_OPTION_YES_ONCE, label: 'Yes once', description: 'Allow this skill for this call only.' },
+                {
+                    id: APPROVAL_OPTION_YES_IN_SESSION,
+                    label: 'Yes in this session',
+                    description: 'Allow this skill for the current chat session.',
+                },
+                { id: APPROVAL_OPTION_NO, label: 'No', description: 'Do not apply this skill now.' },
+            ],
+            approvedOptionIds: [APPROVAL_OPTION_YES_ONCE, APPROVAL_OPTION_YES_IN_SESSION],
+            metadata: {
+                tool: 'human_intervention_request',
+                toolCallId: requestId,
+                source: 'load_skill',
+                skillId: options.skillId,
+                scriptPaths: options.scriptPaths,
             },
-            { id: APPROVAL_OPTION_NO, label: 'No', description: 'Do not apply this skill now.' },
-        ],
-        metadata: { skillId: options.skillId, scriptPaths: options.scriptPaths },
-    });
-    if (approval.optionId === APPROVAL_OPTION_NO) {
-        return false;
+            agentName: options.context?.agentName ?? null,
+        });
+        const approval = {
+            requestId,
+            worldId,
+            chatId,
+            optionId: approvalResult.optionId,
+            source: approvalResult.source,
+        };
+        await persistLoadSkillApprovalResolutionMessage({
+            context: options.context,
+            requestId,
+            resolution: approval,
+            skillId: options.skillId,
+        });
+        if (!approvalResult.approved) {
+            return false;
+        }
+        if (approval.optionId === APPROVAL_OPTION_YES_IN_SESSION) {
+            skillSessionApprovals.add(sessionApprovalKey);
+            if (turnApprovalKey) {
+                skillTurnApprovals.add(turnApprovalKey);
+            }
+        }
+        else if (approval.optionId === APPROVAL_OPTION_YES_ONCE && turnApprovalKey) {
+            skillTurnApprovals.add(turnApprovalKey);
+        }
+        return true;
+    })();
+    inFlightSkillApprovals.set(inFlightApprovalKey, approvalPromise);
+    try {
+        return await approvalPromise;
     }
-    if (approval.optionId === APPROVAL_OPTION_YES_IN_SESSION) {
-        skillSessionApprovals.add(sessionApprovalKey);
+    finally {
+        const currentInFlightApproval = inFlightSkillApprovals.get(inFlightApprovalKey);
+        if (currentInFlightApproval === approvalPromise) {
+            inFlightSkillApprovals.delete(inFlightApprovalKey);
+        }
     }
-    return true;
 }
 async function executeSkillScripts(options) {
     const scriptPaths = options.scriptPaths;
     if (scriptPaths.length === 0) {
         return [];
     }
+    // Check world-level tool permission: 'read' blocks all script execution steps.
+    const toolPermission = getEnvValueFromText(options.context?.world?.variables, 'tool_permission') ?? 'auto';
+    if (toolPermission === 'read') {
+        return scriptPaths.map((scriptPath) => ({
+            source: scriptPath,
+            output: 'Script execution is blocked by the current permission level (read).',
+        }));
+    }
     const worldId = String(options.context?.world?.id || '').trim();
-    const chatId = options.context?.chatId ?? options.context?.world?.currentChatId ?? null;
+    const chatId = getExplicitContextChatId(options.context);
     const executionDirectory = options.context?.workingDirectory || options.skillRoot;
     if (!worldId || !options.context?.world) {
         return [{
@@ -329,13 +764,6 @@ async function executeSkillScripts(options) {
             continue;
         }
         const absoluteCommandSpec = resolveScriptCommand(normalizedAbsoluteScriptPath);
-        if (!isPathWithinRoot(executionDirectory, normalizedAbsoluteScriptPath)) {
-            scriptOutputs.push({
-                source: relativeScriptPath,
-                output: `Script path rejected: "${relativeScriptPath}" resolves outside execution working directory "${executionDirectory}".`,
-            });
-            continue;
-        }
         const executionResult = await executeShellCommand(absoluteCommandSpec.command, absoluteCommandSpec.parameters, executionDirectory, {
             timeout: SCRIPT_TIMEOUT_MS,
             abortSignal: options.context?.abortSignal,
@@ -346,8 +774,17 @@ async function executeSkillScripts(options) {
         if (executionResult.exitCode !== 0 || executionResult.error) {
             const exitCode = executionResult.exitCode === null ? 'unknown' : String(executionResult.exitCode);
             const stderr = executionResult.stderr.trim();
-            const stderrSuffix = stderr ? ` stderr: ${stderr}` : '';
-            throw new SkillScriptExecutionError(`Skill script "${relativeScriptPath}" failed with exit code ${exitCode}.${stderrSuffix}`);
+            const stdoutPreview = executionResult.stdout.trim();
+            const detail = [
+                `exit code ${exitCode}`,
+                stderr ? `stderr: ${stderr}` : '',
+                stdoutPreview ? `stdout: ${stdoutPreview}` : '',
+            ].filter(Boolean).join(' | ');
+            scriptOutputs.push({
+                source: relativeScriptPath,
+                output: `Script exited with ${detail}`,
+            });
+            continue;
         }
         scriptOutputs.push({
             source: relativeScriptPath,
@@ -356,10 +793,161 @@ async function executeSkillScripts(options) {
     }
     return scriptOutputs;
 }
+function isYouTubeUrl(value) {
+    return /https?:\/\/(?:www\.)?(?:youtube\.com|youtu\.be)\//i.test(String(value || ''));
+}
+function extractUrlsFromText(text) {
+    const matches = String(text || '').match(/https?:\/\/[^\s)>\]}]+/gi) || [];
+    return [...new Set(matches.map((match) => match.replace(/[),.;!?]+$/g, '')))];
+}
+function extractArtifactPathCandidates(text) {
+    const matches = String(text || '').match(/(?:\/[^\s"'`<>]+|\.[/\\][^\s"'`<>]+|[A-Za-z0-9_.-]+\.(?:svg|png|jpg|jpeg|gif|webp|mp3|wav|ogg|m4a|mp4|webm|mov|md|txt))/gi) || [];
+    return [...new Set(matches)];
+}
+async function resolvePreviewArtifactFromCandidate(candidate, roots, options = {}) {
+    const normalizedCandidate = String(candidate || '').trim();
+    if (!normalizedCandidate) {
+        return null;
+    }
+    for (const root of roots) {
+        const absolutePath = path.isAbsolute(normalizedCandidate)
+            ? normalizeAbsoluteLocalPath(normalizedCandidate)
+            : normalizeAbsoluteLocalPath(path.resolve(root, normalizedCandidate));
+        const isAllowedPath = roots.some((allowedRoot) => isPathWithinRoot(allowedRoot, absolutePath));
+        if (!isAllowedPath) {
+            continue;
+        }
+        try {
+            const stat = await fs.stat(absolutePath);
+            if (!stat.isFile()) {
+                continue;
+            }
+            const mediaType = guessMediaTypeFromPath(absolutePath);
+            return createArtifactToolPreview({
+                path: absolutePath,
+                bytes: stat.size,
+                media_type: mediaType,
+                display_name: path.basename(absolutePath),
+                url: buildToolArtifactPreviewUrl({ path: absolutePath, worldId: options.worldId }),
+            });
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+async function collectLoadSkillPreviewArtifacts(options) {
+    const previews = [];
+    const seen = new Set();
+    const roots = [
+        options.skillRoot,
+        ...(options.context?.workingDirectory ? [options.context.workingDirectory] : []),
+    ];
+    for (const referenceFile of options.referenceFiles) {
+        const absolutePath = path.isAbsolute(referenceFile)
+            ? normalizeAbsoluteLocalPath(referenceFile)
+            : normalizeAbsoluteLocalPath(path.resolve(options.skillRoot, referenceFile));
+        try {
+            const stat = await fs.stat(absolutePath);
+            if (!stat.isFile()) {
+                continue;
+            }
+            const key = `path:${absolutePath}`;
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            previews.push(createArtifactToolPreview({
+                path: absolutePath,
+                bytes: stat.size,
+                media_type: guessMediaTypeFromPath(absolutePath),
+                display_name: path.basename(referenceFile),
+                title: referenceFile,
+                url: buildToolArtifactPreviewUrl({
+                    path: absolutePath,
+                    worldId: typeof options.context?.world?.id === 'string' ? options.context.world.id : undefined,
+                }),
+            }));
+        }
+        catch {
+            continue;
+        }
+    }
+    for (const output of options.scriptOutputs) {
+        for (const url of extractUrlsFromText(output.output)) {
+            const key = `url:${url}`;
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            previews.push(createUrlToolPreview(url, {
+                renderer: isYouTubeUrl(url) ? 'youtube' : undefined,
+                text: output.source,
+                title: output.source,
+            }));
+        }
+        for (const candidate of extractArtifactPathCandidates(output.output)) {
+            const preview = await resolvePreviewArtifactFromCandidate(candidate, roots, {
+                worldId: typeof options.context?.world?.id === 'string' ? options.context.world.id : undefined,
+            });
+            if (!preview) {
+                continue;
+            }
+            if (!('artifact' in preview)) {
+                continue;
+            }
+            const key = `artifact:${JSON.stringify(preview.artifact)}`;
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            previews.push(preview);
+        }
+    }
+    return previews;
+}
+async function buildLoadSkillSuccessPreview(options) {
+    const summaryLines = [
+        `Loaded skill \`${options.skillId}\`.`,
+        '',
+        `${options.skillDescription}`,
+        '',
+        `Referenced scripts: ${options.scriptPaths.length > 0 ? options.scriptPaths.join(', ') : '(none)'}`,
+        `Reference files: ${options.referenceFiles.length > 0 ? options.referenceFiles.join(', ') : '(none)'}`,
+    ];
+    if (options.scriptOutputs.length > 0) {
+        summaryLines.push('');
+        summaryLines.push('Script outputs:');
+        for (const scriptOutput of options.scriptOutputs) {
+            summaryLines.push(`- ${scriptOutput.source}: ${truncatePreviewText(scriptOutput.output)}`);
+        }
+    }
+    const previews = [
+        createTextToolPreview(summaryLines.join('\n'), {
+            markdown: true,
+            title: `load_skill ${options.skillId}`,
+        }),
+    ];
+    previews.push(...await collectLoadSkillPreviewArtifacts(options));
+    return previews;
+}
+function wrapLoadSkillToolResult(options) {
+    return serializeToolExecutionEnvelope({
+        __type: 'tool_execution_envelope',
+        version: 1,
+        tool: 'load_skill',
+        ...(options.toolCallId ? { tool_call_id: options.toolCallId } : {}),
+        status: /<error>/i.test(options.result) ? 'failed' : 'completed',
+        preview: options.preview,
+        result: options.result,
+    });
+}
 function buildSuccessResult(options) {
-    const { skillId, skillName, markdown, scriptOutputs, referenceFiles } = options;
+    const { skillId, skillName, skillDescription, skillRoot, markdown, scriptOutputs, referenceFiles, scriptPaths, } = options;
     const escapedSkillId = escapeXmlText(skillId);
     const escapedSkillName = escapeXmlText(skillName);
+    const escapedSkillDescription = escapeXmlText(skillDescription);
     const hasActiveResources = scriptOutputs.length > 0;
     const scriptBlocks = scriptOutputs.flatMap((scriptOutput) => ([
         `    <script_output source="${escapeXmlText(scriptOutput.source)}">`,
@@ -379,14 +967,21 @@ function buildSuccessResult(options) {
             '',
         ]
         : [];
+    const hasReferencedScripts = scriptPaths.length > 0;
     const executionDirective = [
         '  <execution_directive>',
         `    You are now operating under the specialized ${escapedSkillName} protocol.`,
-        '    1. Prioritize the logic in <instructions> over generic behavior.',
+        `    Skill purpose: ${escapedSkillDescription}`,
+        '    1. Acknowledge which skill was loaded and apply it directly to the user request.',
+        '    2. Prioritize the logic in <instructions> over generic behavior.',
         hasActiveResources
-            ? '    2. Use the data in <active_resources> to complete the user\'s specific request.'
-            : '    2. Use the skill instructions to complete the user\'s specific request.',
-        '    3. If the workflow is multi-step, explicitly state your plan before executing.',
+            ? '    3. Use the data in <active_resources> to complete the user\'s specific request.'
+            : '    3. Use the skill instructions to complete the user\'s specific request.',
+        '    4. Execute required steps directly; avoid unnecessary planning narration unless the user explicitly asks for a plan.',
+        '    5. Keep tool-related assistant text concise and result-focused.',
+        ...(hasReferencedScripts
+            ? [`    6. Scripts referenced in <instructions> are located at skill root: ${escapeXmlText(skillRoot)}. When invoking them via shell commands, construct the absolute path (e.g., ${escapeXmlText(skillRoot)}/scripts/example.py) since they may not be accessible via relative paths from the project directory.`]
+            : []),
         '  </execution_directive>',
     ];
     return [
@@ -402,7 +997,7 @@ function buildSuccessResult(options) {
 }
 export function createLoadSkillToolDefinition() {
     return {
-        description: 'Load full SKILL.md instructions by skill_id from the skill registry. Use this when a request matches a listed skill.',
+        description: 'Load full SKILL.md instructions by skill_id from the skill registry. Use this when a request matches a listed skill. After loading, apply the skill instructions directly to the user request.',
         parameters: {
             type: 'object',
             properties: {
@@ -416,51 +1011,170 @@ export function createLoadSkillToolDefinition() {
         },
         execute: async (args, _sequenceId, _parentToolCall, context) => {
             await waitForInitialSkillSync();
+            const persistToolEnvelope = context?.persistToolEnvelope === true;
+            const toolCallId = typeof context?.toolCallId === 'string' ? context.toolCallId : undefined;
             const requestedSkillId = typeof args?.skill_id === 'string' ? args.skill_id.trim() : '';
             if (!requestedSkillId) {
-                return buildReadErrorResult('', 'Missing required parameter: skill_id');
+                const result = buildReadErrorResult('', 'Missing required parameter: skill_id');
+                return persistToolEnvelope
+                    ? wrapLoadSkillToolResult({
+                        result,
+                        preview: createTextToolPreview('Missing required parameter: skill_id'),
+                        toolCallId,
+                    })
+                    : result;
             }
-            const entry = getSkill(requestedSkillId);
-            const sourcePath = getSkillSourcePath(requestedSkillId);
-            if (!entry || !sourcePath) {
-                return buildNotFoundResult(requestedSkillId);
+            const runScopedResultKey = getRunScopedLoadSkillResultKey(requestedSkillId, context);
+            if (runScopedResultKey) {
+                const cachedResult = loadSkillRunResultCache.get(runScopedResultKey);
+                if (cachedResult !== undefined) {
+                    loggerLoadSkillHitl.debug('Returning cached run-scoped load_skill result', {
+                        skillId: requestedSkillId,
+                        runScopedResultKey,
+                    });
+                    return cachedResult;
+                }
+                const inFlightResult = inFlightLoadSkillRunResults.get(runScopedResultKey);
+                if (inFlightResult) {
+                    return await inFlightResult;
+                }
             }
-            if (!isSkillEnabledBySettings(requestedSkillId)) {
-                return buildDisabledBySettingsResult(requestedSkillId);
+            const computeResult = async () => {
+                const entry = getSkill(requestedSkillId);
+                const sourcePath = getSkillSourcePath(requestedSkillId);
+                if (!entry || !sourcePath) {
+                    const result = buildNotFoundResult(requestedSkillId);
+                    return {
+                        result,
+                        cacheableForRun: false,
+                    };
+                }
+                if (!isSkillEnabledBySettings(requestedSkillId)) {
+                    const result = buildDisabledBySettingsResult(requestedSkillId);
+                    return {
+                        result,
+                        cacheableForRun: false,
+                    };
+                }
+                try {
+                    const markdown = await fs.readFile(sourcePath, 'utf8');
+                    const instructionsMarkdown = stripYamlFrontMatter(markdown);
+                    const skillRoot = path.dirname(sourcePath);
+                    const scriptPaths = extractReferencedScriptPaths(instructionsMarkdown);
+                    const toolPermission = getEnvValueFromText(context?.world?.variables, 'tool_permission') ?? 'auto';
+                    if (context?.world && !getExplicitContextChatId(context)) {
+                        const result = buildReadErrorResult(requestedSkillId, 'Interactive load_skill execution requires an explicit chatId.');
+                        return {
+                            result,
+                            cacheableForRun: false,
+                        };
+                    }
+                    if (toolPermission === 'ask') {
+                        const isApproved = await requestSkillExecutionApproval({
+                            skillId: requestedSkillId,
+                            scriptPaths,
+                            context,
+                        });
+                        if (!isApproved) {
+                            const result = buildDeclinedResult(requestedSkillId);
+                            return {
+                                result,
+                                cacheableForRun: false,
+                            };
+                        }
+                    }
+                    const scriptOutputs = await executeSkillScripts({
+                        scriptPaths,
+                        skillRoot,
+                        context,
+                    });
+                    const referenceFiles = await collectReferenceFiles(skillRoot, instructionsMarkdown);
+                    const result = buildSuccessResult({
+                        skillId: requestedSkillId,
+                        skillName: entry.skill_id,
+                        skillDescription: entry.description?.trim() || entry.skill_id,
+                        skillRoot,
+                        markdown: instructionsMarkdown,
+                        scriptOutputs,
+                        referenceFiles,
+                        scriptPaths,
+                    });
+                    if (!persistToolEnvelope) {
+                        return {
+                            result,
+                            cacheableForRun: true,
+                        };
+                    }
+                    const preview = await buildLoadSkillSuccessPreview({
+                        skillId: requestedSkillId,
+                        skillDescription: entry.description?.trim() || entry.skill_id,
+                        skillRoot,
+                        scriptOutputs,
+                        referenceFiles,
+                        scriptPaths,
+                        context,
+                    });
+                    return {
+                        result: wrapLoadSkillToolResult({
+                            result,
+                            preview,
+                            toolCallId,
+                        }),
+                        cacheableForRun: true,
+                    };
+                }
+                catch (error) {
+                    if (error instanceof SkillScriptExecutionError) {
+                        throw error;
+                    }
+                    const message = error instanceof Error ? error.message : String(error);
+                    const result = buildReadErrorResult(requestedSkillId, message);
+                    return {
+                        result: persistToolEnvelope
+                            ? wrapLoadSkillToolResult({
+                                result,
+                                preview: createTextToolPreview(message),
+                                toolCallId,
+                            })
+                            : result,
+                        cacheableForRun: false,
+                    };
+                }
+            };
+            if (!runScopedResultKey) {
+                const outcome = await computeResult();
+                if (persistToolEnvelope && !parseToolExecutionEnvelopeContent(outcome.result)) {
+                    return wrapLoadSkillToolResult({
+                        result: outcome.result,
+                        preview: createTextToolPreview(truncatePreviewText(outcome.result, 1600)),
+                        toolCallId,
+                    });
+                }
+                return outcome.result;
             }
+            const runScopedPromise = computeResult().then((outcome) => {
+                if (outcome.cacheableForRun) {
+                    rememberRunScopedLoadSkillResult(runScopedResultKey, outcome.result);
+                }
+                return outcome.result;
+            });
+            inFlightLoadSkillRunResults.set(runScopedResultKey, runScopedPromise);
             try {
-                const markdown = await fs.readFile(sourcePath, 'utf8');
-                const instructionsMarkdown = stripYamlFrontMatter(markdown);
-                const skillRoot = path.dirname(sourcePath);
-                const scriptPaths = extractReferencedScriptPaths(instructionsMarkdown);
-                const isApproved = await requestSkillExecutionApproval({
-                    skillId: requestedSkillId,
-                    scriptPaths,
-                    context,
-                });
-                if (!isApproved) {
-                    return buildDeclinedResult(requestedSkillId);
+                const result = await runScopedPromise;
+                if (persistToolEnvelope && !parseToolExecutionEnvelopeContent(result)) {
+                    return wrapLoadSkillToolResult({
+                        result,
+                        preview: createTextToolPreview(truncatePreviewText(result, 1600)),
+                        toolCallId,
+                    });
                 }
-                const scriptOutputs = await executeSkillScripts({
-                    scriptPaths,
-                    skillRoot,
-                    context,
-                });
-                const referenceFiles = await collectReferenceFiles(skillRoot, instructionsMarkdown);
-                return buildSuccessResult({
-                    skillId: requestedSkillId,
-                    skillName: entry.skill_id,
-                    markdown: instructionsMarkdown,
-                    scriptOutputs,
-                    referenceFiles,
-                });
+                return result;
             }
-            catch (error) {
-                if (error instanceof SkillScriptExecutionError) {
-                    throw error;
+            finally {
+                const inFlightResult = inFlightLoadSkillRunResults.get(runScopedResultKey);
+                if (inFlightResult === runScopedPromise) {
+                    inFlightLoadSkillRunResults.delete(runScopedResultKey);
                 }
-                const message = error instanceof Error ? error.message : String(error);
-                return buildReadErrorResult(requestedSkillId, message);
             }
         },
     };