theorum 1.0.0 → 1.1.3

package/esm/src/kernel/tools/execute.js

@@ -4,19 +4,80 @@
  * @module
  */
 import { throwIfAborted } from '../../guardrails/error.js';
+import { lexiconText } from '../../guardrails/lexicon.js';
+import { resolveGuardrailPolicy } from '../../guardrails/policy.js';
 import { sanitizeText } from '../../guardrails/sanitize.js';
+import { checkTaintGate, composeToolText, guardToolFailureText, guardToolResult, inspectToolArguments, toolCallEvent, } from '../../guardrails/tool-result.js';
+import { isAwaitingUserInput } from '../stages.js';
+import { failureEvent, messageOf, startToolExecution, toolEvent } from './events.js';
+import { checkPermission, isGateResumeDenied, isResumeContinuation } from './permission.js';
 import { getTool } from './registry.js';
+import { executeHttpTool, executeMcpTool, modelResultFromOutput, parseToolOutput, } from './remote.js';
 import { promoteLoadedTools } from './resolve.js';
+import { plainToolInput } from './schema.js';
+import { emitGateSettlement, runPostToolStages, runPreToolPipeline, } from './stage-run.js';
+export { checkPermission, isGateResumeGranted, isResumeContinuation, permissionGranted, } from './permission.js';
+/** Map a registered tool's type onto the origin its bytes carry. */
+function originOfTool(type) {
+    if (type === 'http')
+        return 'http';
+    if (type === 'mcp')
+        return 'mcp';
+    if (type === 'builtin')
+        return 'builtin';
+    return 'local';
+}
+function provenanceFor(tool, depth = 1) {
+    return { origin: originOfTool(tool.type), tool: tool.name, depth };
+}
 function isStreamHandler(handler) {
     return (typeof handler === 'function' &&
         Object.prototype.toString.call(handler) === '[object AsyncGeneratorFunction]');
 }
-export function isResumeContinuation(resume) {
-    return resume?.value !== undefined || resume?.granted === true;
+const MEDIA_PART_TYPES = new Set(['image', 'audio', 'video', 'document']);
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+/** Validate host-emitted InteractionPart shapes; drop invalid entries. */
+export function coerceToolResultParts(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    const parts = [];
+    for (const item of raw) {
+        if (!isRecord(item) || typeof item.type !== 'string')
+            continue;
+        if (item.type === 'text' && typeof item.text === 'string') {
+            parts.push({ type: 'text', text: item.text });
+            continue;
+        }
+        if (MEDIA_PART_TYPES.has(item.type) &&
+            typeof item.mimeType === 'string' &&
+            item.mimeType.trim() &&
+            typeof item.data === 'string' &&
+            item.data.length > 0) {
+            parts.push({
+                type: item.type,
+                mimeType: item.mimeType,
+                data: item.data,
+            });
+        }
+    }
+    return parts.length > 0 ? parts : undefined;
+}
+/** Copy tool output for model `data`, omitting media `parts`. */
+export function leanToolResultData(output) {
+    if (!isRecord(output))
+        return output;
+    const { parts: _parts, ...rest } = output;
+    return rest;
 }
+/** @deprecated Gates use `ToolGate` / `phase: 'gate'`. Kept for type narrowing during migration. */
 export function isToolPause(value) {
     return ('kind' in value &&
-        (value.kind === 'interactive' || value.kind === 'confirmation' || value.kind === 'permission'));
+        (value.kind === 'interactive' ||
+            value.kind === 'confirmation' ||
+            value.kind === 'permission' ||
+            value.kind === 'auth'));
 }
 export function* yieldHandlerSideEvent(base, event) {
     if (event.kind === 'progress') {
@@ -50,214 +111,304 @@ async function* runHandler(handler, input, ctx, base) {
     const output = await handler(input, ctx);
     return output;
 }
-export function permissionGranted(toolName, sessionPermissions) {
-    if (!sessionPermissions) {
-        return false;
-    }
-    return sessionPermissions.includes('*') || sessionPermissions.includes(toolName);
-}
-export function checkPermission(toolName, permission, sessionPermissions, resume) {
-    if (permission === 'auto') {
-        return null;
-    }
-    if (permission === 'always_confirm') {
-        if (resume?.granted === true) {
-            return null;
-        }
-        return {
-            kind: 'permission',
-            tool: toolName,
-            permission,
-            input: {},
-        };
-    }
-    if (permissionGranted(toolName, sessionPermissions)) {
-        return null;
-    }
-    return {
-        kind: 'permission',
-        tool: toolName,
-        permission,
-        input: {},
-    };
-}
-function toolEvent(base, patch) {
-    return {
-        type: 'tool',
-        tool: { ...base, ...patch },
-    };
-}
-function failureEvent(base, failure) {
-    return toolEvent(base, { phase: 'error', failure });
-}
 export function projectForModel(tool, output) {
     if (tool.exposeToModel === false) {
         return { finding: 'Completed.' };
     }
+    if (isAwaitingUserInput(output)) {
+        return {
+            finding: lexiconText('tool.awaiting_user', { kind: output.kind, prompt: output.prompt }),
+            data: leanToolResultData(output),
+        };
+    }
     const finding = typeof output === 'object' && output !== null && 'finding' in output
         ? String(output.finding)
         : JSON.stringify(output);
+    const parts = isRecord(output) && 'parts' in output ? coerceToolResultParts(output.parts) : undefined;
     return {
         finding: sanitizeText(finding),
-        data: output,
+        data: leanToolResultData(output),
+        ...(parts ? { parts } : {}),
     };
 }
-/** Format model-facing tool output for provider history continuation. */
+/**
+ * Format model-facing tool output for provider history continuation.
+ *
+ * Text projection only — never embeds `parts[].data`; media travels on
+ * `TurnHistoryMessage.parts` and adapters wire it from there.
+ *
+ * `executeRegisteredTool` guards at the boundary and leaves `modelText` behind, so
+ * the common path returns already-fenced text. A result recorded elsewhere — a
+ * host replaying a transcript — is guarded here instead, under full detection.
+ */
 export function formatToolResult(result) {
-    if (result.data !== undefined) {
-        return sanitizeText(`${result.finding}\n${JSON.stringify(result.data)}`);
+    if (result.modelText !== undefined) {
+        return result.modelText;
     }
-    return sanitizeText(result.finding);
+    return sanitizeText(composeToolText(result.finding, result.data));
 }
-/** Format a tool failure for provider history — structured so the model (or host) sees the code. */
-export function formatToolFailureForModel(failure) {
+/**
+ * Format a tool failure for provider history — structured so the model (or host)
+ * sees the code.
+ *
+ * The message is remote-authored on HTTP and MCP tools, so it is redacted before
+ * the kernel frames it as a system report.
+ */
+export function formatToolFailureForModel(failure, provenance, policy = resolveGuardrailPolicy(undefined)) {
+    const safe = provenance
+        ? guardToolFailureText(failure.message, provenance, policy).text
+        : sanitizeText(failure.message);
     return {
-        finding: `Tool error (${failure.code}): ${failure.message}`,
+        finding: `Tool error (${failure.code}): ${safe}`,
         data: {
             ok: false,
             code: failure.code,
-            message: failure.message,
+            message: safe,
             ...(failure.details !== undefined ? { details: failure.details } : {}),
         },
     };
 }
-export function* startToolExecution(tool, rawInput, ctx, base) {
-    yield toolEvent(base, { phase: 'running' });
-    throwIfAborted(ctx.signal);
-    const parsed = tool.input.safeParse(rawInput);
-    if (!parsed.success) {
-        yield failureEvent(base, {
-            code: 'invalid_input',
-            message: 'Tool input validation failed',
-            details: parsed.error.flatten(),
-        });
-        return { ok: false };
+/** True when this tool is the profile's T2 loader: its output drives the snapshot. */
+function loadsT2(tool, ctx) {
+    if (ctx.profile.type === 'speech' || ctx.profile.type === 'live' || ctx.profile.type === 'host') {
+        return false;
     }
-    return { ok: true, data: parsed.data };
+    return ctx.profile.tools.t2Loader === tool.name;
 }
-export async function* executeFunction(tool, rawInput, ctx, base, snapshot) {
-    const parsed = yield* startToolExecution(tool, rawInput, ctx, base);
-    if (!parsed.ok)
-        return undefined;
-    const input = parsed.data;
-    const permissionPause = checkPermission(tool.name, tool.permission, ctx.sessionPermissions, ctx.resume);
-    if (permissionPause) {
-        permissionPause.input = input;
-        yield toolEvent(base, { phase: 'pause', pause: permissionPause });
-        return undefined;
+function applyT2LoaderPromotion(tool, checkedData, ctx, snapshot) {
+    if (!loadsT2(tool, ctx)) {
+        return { ok: true, output: checkedData };
     }
-    throwIfAborted(ctx.signal);
-    if (tool.canExecute) {
-        try {
-            const allowed = await tool.canExecute(input, ctx);
-            if (!allowed) {
-                yield failureEvent(base, {
-                    code: 'not_authorized',
-                    message: 'Tool execution not authorized',
-                });
-                return undefined;
-            }
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            yield failureEvent(base, {
-                code: 'not_authorized',
-                message: `Authorization failed for '${tool.name}': ${msg}`,
-            });
-            return undefined;
-        }
-    }
-    if (tool.preflight) {
-        const pre = await tool.preflight(input, ctx);
-        if (pre) {
-            if (isToolPause(pre)) {
-                const pausePayload = { ...pre, input: pre.input ?? input };
-                yield toolEvent(base, { phase: 'pause', pause: pausePayload });
-                return undefined;
-            }
-            yield failureEvent(base, pre);
-            return undefined;
-        }
+    if (!snapshot) {
+        return {
+            ok: false,
+            failure: {
+                code: 'invalid_output',
+                message: lexiconText('tool.t2_loader_needs_snapshot', { tool: tool.name }),
+            },
+        };
     }
-    if (tool.interactive && ctx.resume?.value === undefined) {
-        const render = tool.interactive.render(input);
-        const interactivePause = {
-            kind: 'interactive',
-            tool: tool.name,
-            render,
-            input,
+    const loaded = extractLoadedIds(checkedData);
+    if (!loaded) {
+        return {
+            ok: false,
+            failure: {
+                code: 'invalid_output',
+                message: lexiconText('tool.t2_loader_shape', { tool: tool.name }),
+            },
         };
-        yield toolEvent(base, { phase: 'pause', pause: interactivePause });
-        return undefined;
     }
-    throwIfAborted(ctx.signal);
-    try {
-        const output = yield* runHandler(tool.handler, input, ctx, base);
-        if (output === undefined) {
-            yield failureEvent(base, { code: 'invalid_output', message: 'Handler returned no output' });
-            return undefined;
-        }
-        const checked = tool.output.safeParse(output);
-        if (!checked.success) {
-            yield failureEvent(base, {
+    const { promoted, failure: promoteFailure } = promoteLoadedTools(snapshot, loaded, ctx.profile);
+    if (promoteFailure) {
+        return { ok: false, failure: promoteFailure };
+    }
+    const finalOutput = { ...checkedData, loaded: promoted };
+    const rechecked = tool.output.safeParse(finalOutput);
+    if (!rechecked.success) {
+        return {
+            ok: false,
+            failure: {
                 code: 'invalid_output',
-                message: 'Tool output validation failed',
-                details: checked.error.flatten(),
-            });
-            return undefined;
+                message: lexiconText('tool.t2_loader_output_invalid'),
+                details: rechecked.error.flatten(),
+            },
+        };
+    }
+    return { ok: true, output: rechecked.data };
+}
+/**
+ * Settle a tool call, once, for every transport: guard the provisional result,
+ * run `post_tool`, apply a host `deny` or `mutate` (re-projected and re-guarded),
+ * then emit the single terminal `tool` event with what the model actually gets.
+ * `reproject` is absent when the kernel owns the output (the T2 loader), which
+ * makes `mutate` a warning instead of a replacement.
+ */
+async function* settleToolCall(args) {
+    const { base, toolName, callId, input, stages, provisional, guard, reproject } = args;
+    let modelResult = yield* guard(provisional.modelResult);
+    let failure = 'failure' in provisional ? provisional.failure : undefined;
+    let outputRaw = 'outputRaw' in provisional ? provisional.outputRaw : undefined;
+    const callNotStarted = 'callNotStarted' in provisional ? provisional.callNotStarted : undefined;
+    let awaiting = !failure && isAwaitingUserInput(outputRaw);
+    let post;
+    if (stages) {
+        // Do not applyInject here — the text runner records the tool result first.
+        const { applyInject: _apply, ...rest } = stages;
+        post = yield* runPostToolStages({
+            stages: rest,
+            toolName,
+            callId,
+            input,
+            callNotStarted,
+            outputRaw,
+            outputModel: modelResult,
+            failure,
+            awaiting: awaiting || undefined,
+            mutable: !failure && reproject !== undefined,
+        });
+        if (post.deny) {
+            failure = { code: post.deny.code, message: post.deny.message };
+            modelResult = yield* guard(formatToolFailureForModel(failure));
+            outputRaw = undefined;
+            awaiting = false;
         }
-        let finalOutput = checked.data;
-        if (ctx.profile.type !== 'speech' && ctx.profile.tools.t2Loader === tool.name) {
-            if (!snapshot) {
-                yield failureEvent(base, {
-                    code: 'invalid_output',
-                    message: `tools.t2Loader '${tool.name}' requires a turn tool snapshot`,
-                });
-                return undefined;
-            }
-            const loaded = extractLoadedIds(checked.data);
-            if (!loaded) {
-                yield failureEvent(base, {
-                    code: 'invalid_output',
-                    message: `T2 loader '${tool.name}' must return { loaded: string[] }`,
-                });
-                return undefined;
+        else if (post.mutate && reproject) {
+            const next = reproject(plainToolInput(post.mutate.output));
+            if (next.ok) {
+                failure = undefined;
+                outputRaw = next.outputRaw;
+                modelResult = yield* guard(next.modelResult);
+                awaiting = isAwaitingUserInput(outputRaw);
             }
-            const { promoted, failure: promoteFailure } = promoteLoadedTools(snapshot, loaded, ctx.profile);
-            if (promoteFailure) {
-                yield failureEvent(base, promoteFailure);
-                return undefined;
+            else {
+                failure = next.failure;
+                modelResult = yield* guard(formatToolFailureForModel(next.failure));
+                outputRaw = undefined;
+                awaiting = false;
             }
-            finalOutput = { ...checked.data, loaded: promoted };
-            const rechecked = tool.output.safeParse(finalOutput);
-            if (!rechecked.success) {
-                yield failureEvent(base, {
+        }
+    }
+    yield failure
+        ? failureEvent(base, failure)
+        : toolEvent(base, { phase: 'complete', output: outputRaw });
+    return {
+        modelResult,
+        ...(failure ? { failure } : { outputRaw }),
+        ...(callNotStarted ? { callNotStarted: true } : {}),
+        ...(awaiting ? { awaiting: true } : {}),
+        ...(post?.abort !== undefined ? { aborted: post.abort } : {}),
+        ...(post?.inject?.length ? { pendingInject: post.inject } : {}),
+    };
+}
+/** Settle a call that failed before or during its body. */
+function settleToolFailure(guard, base, failure, stages, args) {
+    return settleToolCall({
+        base,
+        toolName: args.toolName,
+        callId: args.callId,
+        input: args.input,
+        stages,
+        guard,
+        provisional: {
+            failure,
+            modelResult: formatToolFailureForModel(failure),
+            ...(args.callNotStarted ? { callNotStarted: true } : {}),
+        },
+    });
+}
+/** The one guard every model-facing tool result passes through, bound to this call. */
+function resultGuard(tool, ctx, snapshot) {
+    const provenance = provenanceFor(tool);
+    const policy = resolveGuardrailPolicy(ctx.profile.guardrails);
+    const callableTools = snapshot?.executable ?? [];
+    return (result) => guardResult(result, provenance, policy, callableTools);
+}
+/** Tool `preTool` + host `pre_tool` + mutate re-parse, mapped onto a function-tool settlement. */
+async function* runFunctionPreBodyStages(args) {
+    const { tool, base, stages, guard } = args;
+    const pre = yield* runPreToolPipeline(args);
+    if (pre.ok)
+        return pre;
+    if (pre.kind === 'aborted') {
+        return { aborted: pre.aborted, callNotStarted: true };
+    }
+    if (pre.kind === 'gated') {
+        return { gated: pre.gate, callNotStarted: true };
+    }
+    return yield* settleToolFailure(guard, base, pre.failure, stages, {
+        toolName: tool.name,
+        callId: base.callId ?? '',
+        input: args.input,
+        callNotStarted: true,
+    });
+}
+function makeReproject(parse, project) {
+    return (output) => {
+        const checked = parse(output);
+        if (!checked.success) {
+            return {
+                ok: false,
+                failure: {
                     code: 'invalid_output',
-                    message: 'T2 loader output validation failed after promotion',
-                    details: rechecked.error.flatten(),
-                });
-                return undefined;
-            }
-            finalOutput = rechecked.data;
+                    message: lexiconText('tool.output_invalid_after_mutate'),
+                    details: checked.error.flatten(),
+                },
+            };
         }
-        const modelResult = projectForModel(tool, finalOutput);
-        yield toolEvent(base, { phase: 'complete', output: finalOutput });
-        return modelResult;
+        return { ok: true, outputRaw: checked.data, modelResult: project(checked.data) };
+    };
+}
+export async function* executeFunction(tool, rawInput, ctx, base, snapshot, stages) {
+    const guard = resultGuard(tool, ctx, snapshot);
+    const callId = base.callId ?? '';
+    const parsed = yield* startToolExecution(tool, rawInput, ctx, base);
+    if (!parsed.ok) {
+        return yield* settleToolFailure(guard, base, { code: 'invalid_input', message: lexiconText('tool.input_invalid') }, stages, { toolName: tool.name, callId, callNotStarted: true });
+    }
+    let input = parsed.data;
+    const permissionGate = checkPermission(tool.name, tool.permission, ctx.sessionPermissions, ctx.resume);
+    if (permissionGate) {
+        yield* emitGateSettlement({ base, gate: permissionGate, callId, toolName: tool.name });
+        return { gated: permissionGate, callNotStarted: true };
+    }
+    throwIfAborted(ctx.signal);
+    const preBody = yield* runFunctionPreBodyStages({ tool, input, ctx, base, stages, guard });
+    if (!('ok' in preBody)) {
+        return preBody;
+    }
+    input = preBody.input;
+    throwIfAborted(ctx.signal);
+    const fail = (failure) => settleToolFailure(guard, base, failure, stages, { toolName: tool.name, callId, input });
+    let output;
+    try {
+        output = yield* runHandler(tool.handler, input, ctx, base);
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        yield failureEvent(base, { code: 'handler_error', message: msg });
-        return undefined;
+        return yield* fail({ code: 'handler_error', message: messageOf(err) });
+    }
+    if (output === undefined) {
+        return yield* fail({ code: 'invalid_output', message: lexiconText('tool.handler_no_output') });
     }
+    const checked = tool.output.safeParse(output);
+    if (!checked.success) {
+        return yield* fail({
+            code: 'invalid_output',
+            message: lexiconText('tool.output_invalid'),
+            details: checked.error.flatten(),
+        });
+    }
+    const promoted = applyT2LoaderPromotion(tool, checked.data, ctx, snapshot);
+    if (!promoted.ok) {
+        return yield* fail(promoted.failure);
+    }
+    // The T2 loader's output drives the snapshot; the kernel owns it, so no mutate.
+    const ownsOutput = loadsT2(tool, ctx);
+    return yield* settleToolCall({
+        base,
+        toolName: tool.name,
+        callId,
+        input,
+        stages,
+        guard,
+        provisional: {
+            outputRaw: promoted.output,
+            modelResult: projectForModel(tool, promoted.output),
+        },
+        ...(ownsOutput
+            ? {}
+            : {
+                reproject: makeReproject((v) => tool.output.safeParse(v), (data) => projectForModel(tool, data)),
+            }),
+    });
 }
 export function notLoadedMessage(tool) {
     if (tool.loadTier === 'T1') {
-        return `Tool '${tool.name}' is not wired — profile.tools.t1Policy must select it`;
+        return lexiconText('tool.not_wired_t1', { tool: tool.name });
     }
     if (tool.loadTier === 'T2') {
-        return `Tool '${tool.name}' is not loaded — run profile.tools.t2Loader first`;
+        return lexiconText('tool.not_loaded_t2', { tool: tool.name });
     }
-    return `Tool '${tool.name}' is not visible this turn`;
+    return lexiconText('tool.not_visible', { tool: tool.name });
 }
 export function extractLoadedIds(output) {
     if (!output || typeof output !== 'object' || Array.isArray(output)) {
@@ -269,41 +420,84 @@ export function extractLoadedIds(output) {
     }
     return loaded;
 }
-/** Strip prototype-pollution keys from provider/host tool args before validation. */
-export function plainToolInput(input) {
-    if (input === null || typeof input !== 'object') {
-        return input;
-    }
-    if (Array.isArray(input)) {
-        return input.map(plainToolInput);
-    }
-    const out = {};
-    for (const key of Object.keys(input)) {
-        if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
-            continue;
-        }
-        out[key] = plainToolInput(input[key]);
-    }
-    return out;
+function earlyFailure(failure) {
+    return { failure, callNotStarted: true, modelResult: formatToolFailureForModel(failure) };
 }
 export async function* executeBuiltin(tool, ctx, base, snapshot) {
     yield toolEvent(base, { phase: 'running' });
     throwIfAborted(ctx.signal);
     if (!snapshot.builtins.includes(tool.name)) {
-        yield failureEvent(base, {
+        const failure = {
             code: 'not_loaded',
-            message: `Builtin '${tool.name}' is not enabled this turn`,
-        });
-        return undefined;
+            message: lexiconText('tool.builtin_not_enabled', { tool: tool.name }),
+        };
+        yield failureEvent(base, failure);
+        return earlyFailure(failure);
     }
-    yield failureEvent(base, {
+    const failure = {
         code: 'provider_native',
-        message: `Tool '${tool.name}' is a provider builtin — execution is handled by the model provider, not the kernel`,
-    });
+        message: lexiconText('tool.provider_native', { tool: tool.name }),
+    };
+    yield failureEvent(base, failure);
+    return earlyFailure(failure);
+}
+/** Snapshot / allowlist / load-tier checks before body execution. */
+function registeredEligibilityFailure(args) {
+    const { tool, profile, name, resume, snapshot } = args;
+    if (profile.type === 'speech' || !profile.tools.allow.includes(name)) {
+        return {
+            code: 'not_allowed',
+            message: lexiconText('tool.not_allowed', { tool: name, profile: profile.id }),
+        };
+    }
+    if (!snapshot)
+        return undefined;
+    const continuing = isResumeContinuation(resume);
+    if (!continuing && !snapshot.gated.includes(name)) {
+        return { code: 'not_gated', message: lexiconText('tool.not_eligible', { tool: name }) };
+    }
+    if (!snapshot.visible.includes(name)) {
+        const skipLoadCheck = continuing && tool.loadTier === 'T0';
+        if (!skipLoadCheck) {
+            return { code: 'not_loaded', message: notLoadedMessage(tool) };
+        }
+    }
     return undefined;
 }
+async function* settleRemoteOutcome(args) {
+    const { outcome, tool, base, callId, safeInput, stages, guard } = args;
+    const name = tool.name;
+    if (outcome.kind === 'gated') {
+        if (outcome.gate.kind === 'confirmation') {
+            return { gated: outcome.gate, callNotStarted: true };
+        }
+        yield* emitGateSettlement({ base, gate: outcome.gate, callId, toolName: name });
+        return { gated: outcome.gate, callNotStarted: true };
+    }
+    if (outcome.kind === 'aborted') {
+        return { aborted: outcome.aborted, callNotStarted: true };
+    }
+    if (outcome.kind === 'failed') {
+        return yield* settleToolFailure(guard, base, outcome.failure, stages, {
+            toolName: name,
+            callId,
+            input: safeInput,
+            callNotStarted: outcome.callNotStarted,
+        });
+    }
+    return yield* settleToolCall({
+        base,
+        toolName: name,
+        callId,
+        input: safeInput,
+        stages,
+        guard,
+        provisional: { outputRaw: outcome.outputRaw, modelResult: outcome.modelResult },
+        reproject: makeReproject((v) => parseToolOutput(tool.output, v), modelResultFromOutput),
+    });
+}
 export async function* executeRegisteredTool(args) {
-    const { profile, name, input, callId, ctx, snapshot } = args;
+    const { profile, name, input, callId, ctx, snapshot, stages } = args;
     const tool = getTool(name);
     const safeInput = plainToolInput(input);
     const base = {
@@ -314,50 +508,107 @@ export async function* executeRegisteredTool(args) {
             : { value: safeInput },
     };
     if (!tool) {
-        yield failureEvent(base, { code: 'unknown_tool', message: `Tool '${name}' is not registered` });
-        return undefined;
+        const failure = {
+            code: 'unknown_tool',
+            message: lexiconText('tool.not_registered', { tool: name }),
+        };
+        yield failureEvent(base, failure);
+        return earlyFailure(failure);
     }
     if (tool.type === 'builtin') {
         if (!snapshot) {
-            yield failureEvent(base, {
+            const failure = {
                 code: 'provider_native',
-                message: `Tool '${name}' is a provider builtin and requires a turn tool snapshot`,
-            });
-            return undefined;
+                message: lexiconText('tool.builtin_needs_snapshot', { tool: name }),
+            };
+            yield failureEvent(base, failure);
+            return earlyFailure(failure);
         }
         const fullCtx = { ...ctx, callId, profile };
         return yield* executeBuiltin(tool, fullCtx, base, snapshot);
     }
-    if (profile.type === 'speech' || !profile.tools.allow.includes(name)) {
-        yield failureEvent(base, {
-            code: 'not_allowed',
-            message: `Tool '${name}' is not allowed on ${profile.id}`,
-        });
-        return undefined;
+    const eligibility = registeredEligibilityFailure({
+        tool,
+        profile,
+        name,
+        resume: ctx.resume,
+        snapshot,
+    });
+    if (eligibility) {
+        yield failureEvent(base, eligibility);
+        return earlyFailure(eligibility);
     }
-    if (snapshot) {
-        const continuing = isResumeContinuation(ctx.resume);
-        if (!continuing && !snapshot.gated.includes(name)) {
-            yield failureEvent(base, {
-                code: 'not_gated',
-                message: `Tool '${name}' is not eligible on this turn (allow/path)`,
-            });
-            return undefined;
-        }
-        if (!snapshot.visible.includes(name)) {
-            const skipLoadCheck = continuing && tool.loadTier === 'T0';
-            if (!skipLoadCheck) {
-                yield failureEvent(base, {
-                    code: 'not_loaded',
-                    message: notLoadedMessage(tool),
-                });
-                return undefined;
-            }
-        }
+    // Host denied after a gate — synthetic failure + post_tool, no body.
+    if (isGateResumeDenied(ctx.resume)) {
+        return yield* settleToolFailure(resultGuard(tool, { ...ctx, callId, profile }, snapshot), base, { code: 'denied', message: lexiconText('session.tool_denied', { tool: name }) }, stages, { toolName: name, callId, input: safeInput, callNotStarted: true });
     }
     const fullCtx = { ...ctx, callId, profile };
-    return yield* executeFunction(tool, safeInput, fullCtx, base, snapshot);
+    const policy = resolveGuardrailPolicy(profile.guardrails);
+    const provenance = provenanceFor(tool);
+    const argEvent = toolCallEvent(inspectToolArguments(safeInput, policy), provenance);
+    if (argEvent) {
+        yield { type: 'guardrail', guardrail: argEvent };
+    }
+    const taintVerdict = checkTaintGate(ctx.turn?.taint, tool.access, policy);
+    const taintEvent = toolCallEvent(taintVerdict, provenance);
+    if (taintEvent) {
+        yield { type: 'guardrail', guardrail: taintEvent };
+    }
+    if (taintVerdict.action === 'block') {
+        const failure = {
+            code: 'tainted_turn',
+            message: taintVerdict.rejection,
+        };
+        yield failureEvent(base, failure);
+        return earlyFailure(failure);
+    }
+    return yield* settleByType(tool, safeInput, fullCtx, base, snapshot, stages);
+}
+/** Run the body for the tool's transport and settle it through `settleToolCall`. */
+async function* settleByType(tool, safeInput, fullCtx, base, snapshot, stages) {
+    const { name } = tool;
+    if (tool.type === 'function') {
+        return yield* executeFunction(tool, safeInput, fullCtx, base, snapshot, stages);
+    }
+    if (tool.type !== 'http' && tool.type !== 'mcp') {
+        return earlyFailure({
+            code: 'unknown_tool',
+            message: lexiconText('tool.unsupported_type', { tool: name }),
+        });
+    }
+    // HTTP / MCP: schema → permission → auth → preTool → body (inside remote).
+    const remoteOutcome = tool.type === 'http'
+        ? yield* executeHttpTool(tool, safeInput, fullCtx, base, stages)
+        : yield* executeMcpTool(tool, safeInput, fullCtx, base, stages);
+    return yield* settleRemoteOutcome({
+        outcome: remoteOutcome,
+        tool,
+        base,
+        callId: base.callId ?? '',
+        safeInput,
+        stages,
+        guard: resultGuard(tool, fullCtx, snapshot),
+    });
+}
+/**
+ * Guard a tool result before it becomes model context.
+ *
+ * Every tool returns through here, so the fence, the redaction, and the
+ * provenance label are applied once and cannot be skipped by adding a tool type.
+ */
+function* guardResult(result, provenance, policy, callableTools) {
+    const guarded = guardToolResult(result.finding, result.data, provenance, policy, callableTools);
+    if (guarded.event) {
+        yield { type: 'guardrail', guardrail: guarded.event };
+    }
+    return {
+        ...result,
+        modelText: guarded.text,
+        provenance,
+        ...(guarded.suspicious ? { suspicious: guarded.suspicious } : {}),
+    };
 }
+export { startToolExecution };
 export function newCallId(name) {
     return `call_${name}_${Date.now()}`;
 }