@jini-ai/daemon 0.6.7 → 0.6.9

package/dist/tool-executor.js

@@ -46,8 +46,18 @@
  * answer gets back in.
  */
 import { randomUUID } from 'node:crypto';
-import { ToolInputError, } from '@jini-ai/core';
+import { ToolInputError, withNormalizationNotes, ToolInputNormalizationError, } from '@jini-ai/core';
 import { authorizeToolInvocation } from '@jini-ai/core/composition';
+import { toolCandidates } from './core/tool-candidates.js';
+/**
+ * Default cap on finished audit records kept for `getAuditRecord`. One record is added per tool
+ * execution and nothing else ever removed one, so a long-lived daemon grew the map for its whole
+ * uptime (memory investigation 2026-10-21). An in-flight execution's record is never evicted: its
+ * later transitions still have to land on it.
+ */
+export const DEFAULT_MAX_AUDIT_RECORDS = 1000;
+/** Phases after which an execution's audit record receives no further events. */
+const TERMINAL_AUDIT_PHASES = new Set(['denied', 'confirmation-denied', 'completed', 'failed', 'timed-out', 'cancelled']);
 /**
  * Enforces `maxOutputBytes` in BYTES, which is what the option is named for.
  *
@@ -81,14 +91,18 @@ function truncateOutput(output, maxOutputBytes) {
  * — the one and only caller of that internal export.
  * @param options.delegate - Transport-supplied authorize/confirm UI seam;
  * omit for a headless caller whose tools never need interactive gating.
- * @complexity Known-id `execute` is O(1) plus the handler's own cost; unknown ids scan O(n) descriptors for hints. `resumeConfirmation`/`cancel`/`getAuditRecord` are O(1) map lookups.
+ * @param options.maxAuditRecords - Finished audit records kept, see {@link DEFAULT_MAX_AUDIT_RECORDS}.
+ * @complexity Known-id `execute` adds schema-guided normalization to the handler's cost; unknown ids scan O(n) descriptors for hints. `resumeConfirmation`/`cancel`/`getAuditRecord` are O(1) map lookups.
  * @overallScore 100/100
  */
 export function createToolExecutor(requiredArgs, optionalArgs = {}) {
     const options = { ...requiredArgs, ...optionalArgs };
     const { registry, delegate = {} } = options;
     const now = options.now ?? Date.now;
+    const maxAuditRecords = options.maxAuditRecords ?? DEFAULT_MAX_AUDIT_RECORDS;
     const audits = new Map();
+    // Finished executionIds, oldest first (Set insertion order): the only records `retireAudit` evicts.
+    const finishedAudits = new Set();
     const pendingConfirmations = new Map();
     const activeControllers = new Map();
     /**
@@ -107,6 +121,19 @@ export function createToolExecutor(requiredArgs, optionalArgs = {}) {
         // defensive `if (!record) return` guard with no reachable path to hit it.
         const record = audits.get(executionId);
         record.events.push(detail === undefined ? { phase, at: now() } : { phase, at: now(), detail });
+        // A terminal transition is each execution's last append (`execute()` returns right after it),
+        // so evicting finished records can never pull one out from under a later `appendEvent`.
+        if (TERMINAL_AUDIT_PHASES.has(phase))
+            retireAudit(executionId);
+    }
+    /** Marks `executionId` finished and evicts the oldest finished records past `maxAuditRecords`. */
+    function retireAudit(executionId) {
+        finishedAudits.add(executionId);
+        while (finishedAudits.size > maxAuditRecords) {
+            const oldest = finishedAudits.values().next().value;
+            finishedAudits.delete(oldest);
+            audits.delete(oldest);
+        }
     }
     function requestConfirmation(request) {
         if (delegate.onConfirm) {
@@ -132,7 +159,7 @@ export function createToolExecutor(requiredArgs, optionalArgs = {}) {
         appendEvent(executionId, 'requested');
         return executionId;
     }
-    function authorize(principal, run, toolId, input) {
+    function authorize({ principal, run, toolId, input, registry }) {
         // `.bind(delegate)` rather than passing the bare method reference: `ExecutionDelegate` is
         // declared with method syntax, so a host may legitimately implement it as a class instance
         // whose `onAuthorize` reads `this`. Handing the detached function to `@jini-ai/core` would
@@ -159,135 +186,174 @@ export function createToolExecutor(requiredArgs, optionalArgs = {}) {
         handle.unref?.();
         return { handle, timedOut: () => timedOut };
     }
-    /** Classifies a handler rejection into its terminal result, recording the matching transition. */
-    function failureResult(executionId, err, timedOut, aborted) {
-        if (timedOut) {
-            appendEvent(executionId, 'timed-out');
-            return { executionId, status: 'timed-out' };
-        }
-        if (aborted) {
-            appendEvent(executionId, 'cancelled');
-            return { executionId, status: 'cancelled' };
-        }
-        const message = err instanceof Error ? err.message : String(err);
+    /** Records a terminal transition that carries no detail and returns its bare result. */
+    function terminal({ executionId, status }) {
+        appendEvent(executionId, status);
+        return { executionId, status };
+    }
+    /** Records an operational (non-decision) failure under a fixed message that never carries the exception text. */
+    function operationalFailure({ executionId, error }) {
+        appendEvent(executionId, 'failed', error);
+        return { executionId, status: 'failed', error };
+    }
+    /**
+     * Classifies a handler rejection into its terminal result, recording the matching transition.
+     * Prepared `guidance` is appended to a `failed` result's error (never to its audit detail) — a
+     * rejected write still returns a model-visible result; do not lose prepared guidance there.
+     */
+    function failureResult({ executionId, err, timedOut, aborted }, { normalizationNotes = [], guidance = '' } = {}) {
+        if (timedOut)
+            return terminal({ executionId, status: 'timed-out' });
+        if (aborted)
+            return terminal({ executionId, status: 'cancelled' });
+        const message = withNormalizationNotes({ output: err instanceof Error ? err.message : String(err), notes: normalizationNotes });
         appendEvent(executionId, 'failed', message);
         const errorKind = err instanceof ToolInputError ? 'validation' : 'internal';
-        return { executionId, status: 'failed', error: message, errorKind };
+        const error = guidance ? `${message}\n\n${guidance}` : message;
+        return { executionId, status: 'failed', error, errorKind, ...(normalizationNotes.length ? { normalizationNotes } : {}) };
     }
-    async function execute({ principal, run, toolId, input }, { signal, emitSurface } = {}) {
-        // Existence is checked separately from — and before — authorization so the audit record can
-        // be opened before the (possibly slow, possibly throwing) authorization gate runs, matching
-        // pre-authorizeToolInvocation timing: `requested` used to precede `policy.authorize`, and a
-        // policy that hangs or throws used to still leave a record behind. `has()` only confirms
-        // existence, never returns a handler, so this doesn't reopen the leak authorizeToolInvocation
-        // closed — that gate still runs, still unconditionally, inside the call below.
-        if (!registry.has({ toolId })) {
-            const candidates = registry.list({}).map((tool) => tool.id).filter((id) => id.startsWith(toolId)).slice(0, 8);
-            const hint = candidates.length > 0 ? `; did you mean ${candidates.join(', ')}?` : '';
-            throw new ToolInputError({ message: `ToolExecutor: unknown tool "${toolId}"${hint}` });
+    /** Throws the typed unknown-tool input error, naming up to eight registered prefix matches. */
+    function assertKnownTool({ registry: invocationRegistry, toolId }) {
+        if (invocationRegistry.has({ toolId }))
+            return;
+        const candidates = toolCandidates({ toolId, tools: invocationRegistry.list({}) });
+        const hint = candidates.length > 0 ? `; did you mean ${candidates.join(', ')}?` : '';
+        throw new ToolInputError({ message: `ToolExecutor: unknown tool "${toolId}"${hint}` });
+    }
+    /**
+     * Routes a transport `signal` firing into `cancel(executionId)` and returns the function that
+     * detaches it again. A no-op pair when the transport supplied no signal.
+     */
+    function watchTransportAbort({ executionId, signal }) {
+        if (!signal)
+            return () => undefined;
+        const onTransportAbort = () => cancel({ executionId: executionId });
+        signal.addEventListener('abort', onTransportAbort, { once: true });
+        return () => signal.removeEventListener('abort', onTransportAbort);
+    }
+    /** Terminal result for an authorization gate that threw, keeping a typed normalization error's message. */
+    function authorizationFailure({ executionId, error }) {
+        if (error instanceof ToolInputNormalizationError)
+            return failureResult({ executionId, err: error, timedOut: false, aborted: false });
+        return operationalFailure({ executionId, error: 'authorization failed' });
+    }
+    /**
+     * Acts on the authorization outcome synchronously: `{ refusal }` if the call ends here
+     * (cancelled meanwhile, or denied), otherwise records `authorized` and returns `{ allowed }`.
+     */
+    function admitAuthorized({ executionId, resolved, signal }) {
+        // `authorize()` isn't itself signal-aware — it's typically a fast policy check, not a
+        // human-in-the-loop wait — so this is a post-await check rather than a mid-flight abort, the
+        // same idiom the post-handler check below already uses: a signal that fired while `authorize()`
+        // was in flight is caught here, before its (now-moot) decision is acted on.
+        if (signal?.aborted)
+            return { refusal: terminal({ executionId, status: 'cancelled' }) };
+        if (resolved.decision !== 'allow')
+            return { refusal: terminal({ executionId, status: 'denied' }) };
+        const { normalizationNotes } = resolved;
+        appendEvent(executionId, 'authorized', normalizationNotes.length ? `normalized: ${normalizationNotes.join('; ')}` : undefined);
+        return { allowed: resolved };
+    }
+    /**
+     * Runs the confirmation gate: `undefined` once confirmed (recorded), otherwise the terminal result.
+     *
+     * Only ever awaited on the confirmation path. It was once kept inline in `execute()` because
+     * hoisting it into an `async` function that every call awaited added microtask ticks to the
+     * *un*-confirmed path too, and callers observe that timing — a test cancels an in-flight
+     * execution after a fixed number of ticks and needs the handler to have already started by then.
+     * `execute()` awaits this only inside its `requiresConfirmation` branch, so the un-confirmed path
+     * keeps its tick count, and `requestConfirmation()` still runs synchronously on entry.
+     */
+    async function confirmGate(request) {
+        const { executionId } = request;
+        let confirmation;
+        try {
+            confirmation = await requestConfirmation(request);
         }
-        const executionId = openAudit(principal, run, toolId);
-        // Observes `signal` for this execution's ENTIRE remaining lifetime, not just the handler-run
-        // phase. `requestConfirmation()`'s wait below is unbounded — it settles only when a human
-        // answers or `resumeConfirmation`/`cancel` is called — so a transport disconnect or run-cancel
-        // that only reached a handler-phase `AbortController` (this file's previous design) had no way
-        // to end a still-parked confirmation; `execute()` simply never settled. Routed through the
-        // existing `cancel(executionId)` rather than a bespoke handler, so every trigger — an explicit
-        // `cancel()` call, a run cancellation, and now a transport disconnect — resolves a pending
-        // confirmation and an in-flight handler the exact same way.
-        let onTransportAbort;
-        function detachTransportAbort() {
-            if (onTransportAbort)
-                signal?.removeEventListener('abort', onTransportAbort);
+        catch {
+            // Same reasoning as the authorization gate: terminal, recorded, and generic.
+            return operationalFailure({ executionId, error: 'confirmation failed' });
         }
-        if (signal) {
-            if (signal.aborted) {
-                appendEvent(executionId, 'cancelled');
-                return { executionId, status: 'cancelled' };
-            }
-            onTransportAbort = () => cancel({ executionId: executionId });
-            signal.addEventListener('abort', onTransportAbort, { once: true });
+        if (confirmation === 'confirm') {
+            appendEvent(executionId, 'confirmed');
+            return undefined;
         }
-        // Both gates below can throw on INFRASTRUCTURE failure — a policy that rejects, a confirmation
-        // transport that drops. Those throws used to escape `execute` entirely, which cost two things:
-        // the audit record stayed open forever at `requested`/`authorized` with no terminal transition
-        // (the comment above only ever guarded against leaving NO record, not against leaving an
-        // unfinished one), and the raw exception text travelled outward to become tool-result content
-        // an agent reads — an authorization or transport internal surfaced to the model verbatim.
-        //
-        // Recorded terminal and returned as `failed` with a fixed message. `failed` is the right state:
-        // this execution ended, and it ended for an operational reason rather than a decision. The real
-        // exception stays server-side. Deliberately narrower than the `unknown tool` throw above, which
-        // stays a typed input-error throw because no tool execution exists to settle.
-        let resolved;
+        // `cancel(executionId)` (called directly, or via the transport-abort listener) resolves a
+        // pending confirmation the same way a human `deny` does, but the two are not the same OUTCOME:
+        // `confirmation-denied` asserts a decision was made, which is false when the requester vanished
+        // before answering. `cancelledConfirmations` distinguishes them so the audit trail never
+        // reports a decision nobody made.
+        if (cancelledConfirmations.delete(executionId))
+            return terminal({ executionId, status: 'cancelled' });
+        return terminal({ executionId, status: 'confirmation-denied' });
+    }
+    /** Advisory guidance for an authorized call. A failure is fail-open: it yields no guidance. */
+    async function prepareGuidanceSafely({ principal, run, tool, signal }, { emitSurface }) {
         try {
-            resolved = await authorize(principal, run, toolId, input);
+            return await options.prepareGuidance({ principal, run, tool, signal,
+                ...(emitSurface ? { emitSurface } : {}) }, {});
         }
         catch {
-            detachTransportAbort();
-            appendEvent(executionId, 'failed', 'authorization failed');
-            return { executionId, status: 'failed', error: 'authorization failed' };
+            // Guidance availability must never convert an authorized write into a tool failure.
+            return '';
         }
-        // `authorize()` isn't itself signal-aware — it's typically a fast policy check, not a
-        // human-in-the-loop wait — so this is a post-await check rather than a mid-flight abort, the
-        // same idiom the post-handler check below already uses: a signal that fired while `authorize()`
-        // was in flight is caught here, before its (now-moot) decision is acted on.
-        if (signal?.aborted) {
-            detachTransportAbort();
-            appendEvent(executionId, 'cancelled');
-            return { executionId, status: 'cancelled' };
-        }
-        // `registry.has({ toolId })` above already confirmed the tool exists, and `ToolRegistry` is
-        // append-only (no unregister — see `createToolRegistry`'s doc), so `authorizeToolInvocation`
-        // resolving the same `toolId` against the same `registry` cannot come back `undefined` here.
-        const { descriptor } = resolved;
-        if (resolved.decision !== 'allow') {
-            detachTransportAbort();
-            appendEvent(executionId, 'denied');
-            return { executionId, status: 'denied' };
+    }
+    /** Whether `prepareGuidance` applies to this tool — checked synchronously so the no-guidance path adds no tick. */
+    function wantsGuidance(descriptor) {
+        return Boolean(options.prepareGuidance && descriptor.metadata?.guidanceCapabilities?.length);
+    }
+    /** `{ emitSurface }` when the transport supplied one, else `{}` — see `runHandler` for why it is never defaulted. */
+    function surfaceOption(emitSurface) {
+        return emitSurface !== undefined ? { emitSurface } : {};
+    }
+    /** The handler's `invokeTool` port: a nested call through this same executor and its gates. */
+    function nestedInvoker({ principal, run, toolId, invocationRegistry, signal }, { emitSurface }) {
+        return async ({ toolId: nestedToolId, input: nestedInput }, { registry: nestedRegistry = invocationRegistry } = {}) => {
+            const selectedRegistry = nestedToolId === toolId || invocationRegistry.has({ toolId: nestedToolId }) ? invocationRegistry : nestedRegistry;
+            const result = await execute({ principal, run, toolId: nestedToolId, input: nestedInput }, { signal, ...surfaceOption(emitSurface), invocationRegistry: selectedRegistry });
+            if (result.status === 'completed')
+                return result.output;
+            // `failed` results always carry `error` (and only they carry `errorKind`); the bare terminal
+            // statuses carry none, so they are named by tool id and status instead.
+            const message = result.error ?? `${nestedToolId}: ${result.status}`;
+            throw result.errorKind === 'validation' ? new ToolInputError({ message }) : new Error(message);
+        };
+    }
+    /**
+     * Turns a resolved handler output into the terminal result: `completed` with the (guidance-
+     * annotated, normalization-noted, truncated) output, or the terminal state the call already
+     * reached when the handler resolved after it.
+     */
+    function settleOutput({ executionId, rawOutput, descriptor, timedOut, aborted }, { guidance, normalizationNotes }) {
+        // A handler is not OBLIGED to honour `signal` — it is handed one, not policed by one. A
+        // handler that ignores it and resolves normally after the timer fired (or after `cancel`)
+        // used to land here and be recorded `completed`, because the timeout/abort state was only
+        // ever consulted in the `catch`. That reports success for a call the contract has already
+        // declared terminal in the other direction: the caller was told `timed-out`/`cancelled` is
+        // final (see this module's state-machine doc), the audit trail said `completed`, and the two
+        // disagreed. Whether the handler cooperated does not change what happened to the CALL.
+        if (timedOut || aborted) {
+            return failureResult({ executionId, err: new Error('handler resolved after the execution was already terminal'), timedOut, aborted });
         }
-        appendEvent(executionId, 'authorized');
-        const { handler } = resolved;
-        // Kept inline rather than extracted into a helper: hoisting this into an `async` function adds
-        // microtask ticks to the *un*-confirmed path too, and callers observe that timing — a test
-        // cancels an in-flight execution after a fixed number of ticks and needs the handler to have
-        // already started by then.
-        if (descriptor.requiresConfirmation) {
-            let confirmation;
-            try {
-                confirmation = await requestConfirmation({ executionId, principal, run, tool: descriptor, input });
-            }
-            catch {
-                // Same reasoning as the authorization gate above: terminal, recorded, and generic.
-                detachTransportAbort();
-                appendEvent(executionId, 'failed', 'confirmation failed');
-                return { executionId, status: 'failed', error: 'confirmation failed' };
-            }
-            if (confirmation !== 'confirm') {
-                detachTransportAbort();
-                // `cancel(executionId)` (called directly, or via the transport-abort listener above)
-                // resolves a pending confirmation the same way a human `deny` does, but the two are not the
-                // same OUTCOME: `confirmation-denied` asserts a decision was made, which is false when the
-                // requester vanished before answering. `cancelledConfirmations` distinguishes them so the
-                // audit trail never reports a decision nobody made.
-                if (cancelledConfirmations.delete(executionId)) {
-                    appendEvent(executionId, 'cancelled');
-                    return { executionId, status: 'cancelled' };
-                }
-                appendEvent(executionId, 'confirmation-denied');
-                return { executionId, status: 'confirmation-denied' };
-            }
-            appendEvent(executionId, 'confirmed');
+        const { output, truncated } = truncateOutput(withNormalizationNotes({ output: attachToolGuidance({ output: rawOutput, guidance }), notes: normalizationNotes }), descriptor.maxOutputBytes);
+        appendEvent(executionId, 'completed');
+        return { executionId, status: 'completed', output, truncated, ...(normalizationNotes.length ? { normalizationNotes } : {}) };
+    }
+    /**
+     * Prepares guidance, arms the timeout and runs the handler. Runs synchronously up to the handler
+     * call when no guidance applies, so the handler has started by the time `execute()`'s caller
+     * observes the same tick count as before this was extracted.
+     */
+    async function runHandler(call, { emitSurface }) {
+        const { executionId, controller, principal, run, input, descriptor, handler, normalizationNotes } = call;
+        const guidance = wantsGuidance(descriptor)
+            ? await prepareGuidanceSafely({ principal, run, tool: descriptor, signal: controller.signal }, { emitSurface })
+            : '';
+        if (controller.signal.aborted) {
+            return terminal({ executionId, status: 'cancelled' });
         }
-        const controller = new AbortController();
-        activeControllers.set(executionId, controller);
-        // `signal` doesn't need linking here — the listener registered above already reaches this
-        // controller via `cancel()`'s `activeControllers` branch as soon as `activeControllers.set`
-        // ran. A second direct link (this file used to have one, `linkAbortSignal`) was redundant for
-        // this phase and, worse, gave the impression `signal` was fully handled when it was only wired
-        // to the phase after the one that actually needed it — see the confirmation block above.
         const timeout = startTimeout(controller, descriptor.timeoutMs);
-        // Cleanup (clear the timeout, drop the abort controller) is repeated at
+        // Cleanup (clear the timeout) is repeated at
         // each return below rather than centralized in a `finally` — a
         // try/finally here produced a synthetic "abrupt completion" branch
         // istanbul/v8 instruments for the finally block itself, which is
@@ -298,7 +364,6 @@ export function createToolExecutor(requiredArgs, optionalArgs = {}) {
         const cleanup = () => {
             if (timeout.handle)
                 clearTimeout(timeout.handle);
-            activeControllers.delete(executionId);
         };
         appendEvent(executionId, 'started');
         try {
@@ -311,30 +376,89 @@ export function createToolExecutor(requiredArgs, optionalArgs = {}) {
                 run,
                 input,
                 signal: controller.signal,
-            }, { ...(emitSurface !== undefined ? { emitSurface } : {}) });
-            // A handler is not OBLIGED to honour `signal` — it is handed one, not policed by one. A
-            // handler that ignores it and resolves normally after the timer fired (or after `cancel`)
-            // used to land here and be recorded `completed`, because the timeout/abort state was only
-            // ever consulted in the `catch`. That reports success for a call the contract has already
-            // declared terminal in the other direction: the caller was told `timed-out`/`cancelled` is
-            // final (see this module's state-machine doc), the audit trail said `completed`, and the two
-            // disagreed. Whether the handler cooperated does not change what happened to the CALL.
-            if (timeout.timedOut() || controller.signal.aborted) {
-                cleanup();
-                detachTransportAbort();
-                return failureResult(executionId, new Error('handler resolved after the execution was already terminal'), timeout.timedOut(), controller.signal.aborted);
-            }
-            const { output, truncated } = truncateOutput(rawOutput, descriptor.maxOutputBytes);
-            appendEvent(executionId, 'completed');
+            }, {
+                ...surfaceOption(emitSurface),
+                invokeTool: nestedInvoker({ principal, run, toolId: call.toolId, invocationRegistry: call.invocationRegistry, signal: controller.signal }, { emitSurface }),
+            });
             cleanup();
-            detachTransportAbort();
-            return { executionId, status: 'completed', output, truncated };
+            return settleOutput({ executionId, rawOutput, descriptor, timedOut: timeout.timedOut(), aborted: controller.signal.aborted }, { guidance, normalizationNotes });
         }
         catch (err) {
             cleanup();
+            return failureResult({ executionId, err, timedOut: timeout.timedOut(), aborted: controller.signal.aborted }, { normalizationNotes, guidance });
+        }
+    }
+    async function execute({ principal, run, toolId, input }, { signal, emitSurface, invocationRegistry = registry } = {}) {
+        // Existence is checked separately from — and before — authorization so the audit record can
+        // be opened before the (possibly slow, possibly throwing) authorization gate runs, matching
+        // pre-authorizeToolInvocation timing: `requested` used to precede `policy.authorize`, and a
+        // policy that hangs or throws used to still leave a record behind. `has()` only confirms
+        // existence, never returns a handler, so this doesn't reopen the leak authorizeToolInvocation
+        // closed — that gate still runs, still unconditionally, inside the call below.
+        assertKnownTool({ registry: invocationRegistry, toolId });
+        const executionId = openAudit(principal, run, toolId);
+        // Observes `signal` for this execution's ENTIRE remaining lifetime, not just the handler-run
+        // phase. `requestConfirmation()`'s wait below is unbounded — it settles only when a human
+        // answers or `resumeConfirmation`/`cancel` is called — so a transport disconnect or run-cancel
+        // that only reached a handler-phase `AbortController` (this file's previous design) had no way
+        // to end a still-parked confirmation; `execute()` simply never settled. Routed through the
+        // existing `cancel(executionId)` rather than a bespoke handler, so every trigger — an explicit
+        // `cancel()` call, a run cancellation, and now a transport disconnect — resolves a pending
+        // confirmation and an in-flight handler the exact same way.
+        if (signal?.aborted)
+            return terminal({ executionId, status: 'cancelled' });
+        const controller = new AbortController();
+        activeControllers.set(executionId, controller);
+        // `signal` doesn't need linking in `runHandler` — the listener registered here reaches this
+        // controller via `cancel()`'s `activeControllers` branch as soon as `activeControllers.set`
+        // ran. A second direct link (this file used to have one, `linkAbortSignal`) was redundant for
+        // that phase and, worse, gave the impression `signal` was fully handled when it was only wired
+        // to the phase after the one that actually needed it. Register here so cancellation also
+        // survives the microtask gap after confirmation settles and before `runHandler()` starts.
+        const detachTransportAbort = watchTransportAbort({ executionId, signal });
+        const cleanupCancellation = () => {
             detachTransportAbort();
-            return failureResult(executionId, err, timeout.timedOut(), controller.signal.aborted);
+            activeControllers.delete(executionId);
+        };
+        // Both gates below can throw on INFRASTRUCTURE failure — a policy that rejects, a confirmation
+        // transport that drops. Those throws used to escape `execute` entirely, which cost two things:
+        // the audit record stayed open forever at `requested`/`authorized` with no terminal transition
+        // (the comment above only ever guarded against leaving NO record, not against leaving an
+        // unfinished one), and the raw exception text travelled outward to become tool-result content
+        // an agent reads — an authorization or transport internal surfaced to the model verbatim.
+        //
+        // Recorded terminal and returned as `failed` with a fixed message. `failed` is the right state:
+        // this execution ended, and it ended for an operational reason rather than a decision. The real
+        // exception stays server-side. Deliberately narrower than the `unknown tool` throw above, which
+        // stays a typed input-error throw because no tool execution exists to settle.
+        let resolved;
+        try {
+            resolved = await authorize({ principal, run, toolId, input, registry: invocationRegistry });
+        }
+        catch (error) {
+            cleanupCancellation();
+            return authorizationFailure({ executionId, error });
+        }
+        // `invocationRegistry.has({ toolId })` above already confirmed the tool exists, and `ToolRegistry` is
+        // append-only (no unregister — see `createToolRegistry`'s doc), so `authorizeToolInvocation`
+        // resolving the same `toolId` against the same `registry` cannot come back `undefined` here.
+        const gate = admitAuthorized({ executionId, resolved: resolved, signal: controller.signal });
+        if ('refusal' in gate) {
+            cleanupCancellation();
+            return gate.refusal;
+        }
+        const admitted = gate.allowed;
+        const { descriptor } = admitted;
+        if (descriptor.requiresConfirmation) {
+            const declined = await confirmGate({ executionId, principal, run, tool: descriptor, input: admitted.input });
+            if (declined) {
+                cleanupCancellation();
+                return declined;
+            }
         }
+        const result = await runHandler({ executionId, controller, principal, run, toolId, input: admitted.input, descriptor, handler: admitted.handler, normalizationNotes: admitted.normalizationNotes, invocationRegistry }, { emitSurface });
+        cleanupCancellation();
+        return result;
     }
     function resumeConfirmation({ executionId, decision }) {
         const resolve = pendingConfirmations.get(executionId);
@@ -348,8 +472,8 @@ export function createToolExecutor(requiredArgs, optionalArgs = {}) {
         const controller = activeControllers.get(executionId);
         if (controller) {
             controller.abort();
-            return;
         }
+        // The controller also exists while confirmation is pending; aborting must still unblock it.
         const resolve = pendingConfirmations.get(executionId);
         if (resolve) {
             pendingConfirmations.delete(executionId);
@@ -362,4 +486,18 @@ export function createToolExecutor(requiredArgs, optionalArgs = {}) {
     }
     return { execute, resumeConfirmation, cancel, getAuditRecord };
 }
+/** Preserve ordinary object fields while adding model-facing guidance to this tool result. */
+function attachToolGuidance({ output, guidance }) {
+    if (!guidance)
+        return output;
+    if (typeof output === 'string')
+        return `${output}\n\n${guidance}`;
+    if (output && typeof output === 'object' && !Array.isArray(output)) {
+        // MCP envelopes are projected by their content blocks; an extra JSON property may be ignored.
+        if ('content' in output && Array.isArray(output.content))
+            return { ...output, content: [...output.content, { type: 'text', text: guidance }] };
+        return { ...output, agentPluginGuidance: guidance };
+    }
+    return { result: output, agentPluginGuidance: guidance };
+}
 //# sourceMappingURL=tool-executor.js.map