@slopus/happy-agent-base 0.0.3 → 0.0.5

package/dist/AgentBase.js

@@ -2,10 +2,11 @@ import { areProviderModelsCompatible } from "@slopus/happy-providers";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { Value } from "@sinclair/typebox/value";
 import { asyncLock, createContextNamespace, deterministicStringify, withLifetime, } from "@steve.kite/stdlib";
-import { withAgentContext, withAgentKV, withAgentRunKV } from "./AgentContexts.js";
+import { withAgentContext, withAgentKV, withAgentPermissionMode, withAgentRunKV, } from "./AgentContexts.js";
 import { taskContextBeforeToolCall, withAgentTaskContext } from "./AgentTaskContext.js";
 import { AgentKV } from "./AgentKV.js";
 import { AGENT_BASE_PENDING_KEY, agentBasePendingStateOf, } from "./AgentBasePending.js";
+import { DEFAULT_AGENT_PERMISSION_MODE, isAgentPermissionMode, } from "./AgentPermissionMode.js";
 import { AgentProviders } from "./AgentProviders.js";
 /** Race winner when an abort interrupts a wait on the stream or a running tool. */
 const ABORTED = Symbol("aborted");
@@ -103,6 +104,20 @@ const INSIDE_CLOSE_REPORT_MS = 15;
  * capability released when the hook returns, so it cannot be retained to bypass the lock later.
  * A failing handoff rejects an incompatible switch outright rather than costing the history.
  *
+ * ## Permission modes
+ *
+ * How much of the machine the agent may touch travels with its messages, exactly like its model,
+ * and takes effect when the message is consumed rather than when it is queued: a response and the
+ * tools it dispatched are already running under the mode they were started with, and are left to
+ * finish under it. The mode is durable, so a restart resumes in the mode the conversation reached,
+ * and it is carried on every context the agent derives, so a hook or a tool reads what it is
+ * running under rather than being told.
+ *
+ * The loop enforces nothing. It has no idea what any particular tool touches, and a runtime that
+ * guessed would be wrong about tools it has never seen. Enforcement belongs to the features and
+ * tools that do know; the loop's whole part is to carry the mode, make its changes durable, and
+ * report them.
+ *
  * ## Recovery
  *
  * Whether a restart owes a response is decided by the last durable record: a consumed message, a
@@ -200,6 +215,11 @@ export class AgentBase {
     #effort;
     /** The service tier in force. */
     #serviceTier;
+    /**
+     * How much of the machine the agent may touch. Durable, so a restart resumes in the mode the
+     * conversation reached, and carried on every context the agent derives.
+     */
+    #permissionMode;
     /** The single set of hooks the run is observed by and its configuration extended from. */
     #hooks;
     /**
@@ -401,6 +421,7 @@ export class AgentBase {
         this.#model = options.model;
         this.#effort = options.effort;
         this.#serviceTier = options.serviceTier;
+        this.#permissionMode = options.permissionMode ?? DEFAULT_AGENT_PERMISSION_MODE;
         this.#kv = new AgentKV(this.#persistence, `kv.${options.id}.`);
         this.#runKV = this.#kv.scoped("run");
         // Everything the agent does — hooks and tool executions included — runs on a context
@@ -415,14 +436,19 @@ export class AgentBase {
      * the selection changes.
      */
     #deriveCtx() {
-        const ctx = withAgentContext(this.#baseCtx, {
+        const ctx = withAgentContext(this.#baseCtx, this.#selection());
+        return withAgentRunKV(withAgentKV(ctx, this.#kv), this.#runKV);
+    }
+    /** Everything about what the agent is currently running on, as one value to carry. */
+    #selection() {
+        return {
             id: this.id,
             provider: this.#providerId,
             model: this.#model,
             effort: this.#effort,
             serviceTier: this.#serviceTier,
-        });
-        return withAgentRunKV(withAgentKV(ctx, this.#kv), this.#runKV);
+            permissionMode: this.#permissionMode,
+        };
     }
     /**
      * Whether the agent has anything left to do. This is the only thing about an agent's state
@@ -439,9 +465,9 @@ export class AgentBase {
      * whatever else that transaction is writing, which is how a consumed message and the
      * inference it owes become durable as one fact rather than two.
      */
-    async #recordPending(ctx, pending) {
+    async #recordPending(ctx, pending, force = false) {
         const serialized = deterministicStringify(pending);
-        if (this.#pendingWritten === serialized)
+        if (!force && this.#pendingWritten === serialized)
             return;
         await this.#persistence.writeValue(ctx, AGENT_BASE_PENDING_KEY, pending);
         this.#pending = pending;
@@ -455,22 +481,38 @@ export class AgentBase {
      * is doing, and a run interrupted by a dead process would be indistinguishable from the one
      * starting here.
      */
-    async #enterStage(stage) {
+    async #enterStage(stage, transact) {
         const pending = { stage };
-        if (deterministicStringify(pending) === this.#pendingWritten && this.#inheritedRead)
-            return;
+        if (transact === undefined &&
+            deterministicStringify(pending) === this.#pendingWritten &&
+            this.#inheritedRead) {
+            return undefined;
+        }
         try {
-            await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
+            return await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
                 if (!this.#inheritedRead) {
                     this.#inheritedRead = true;
                     this.#inherited = await agentBasePendingStateOf(lockCtx, this.#persistence);
                 }
-                await this.#recordPending(lockCtx, pending);
+                if (transact === undefined) {
+                    await this.#recordPending(lockCtx, pending);
+                    return undefined;
+                }
+                return await this.#recordTransaction(lockCtx, async (txCtx) => {
+                    // The state is staged first. The callback then writes against this exact
+                    // transaction, so neither its conclusion nor the state it observed can land
+                    // without the other.
+                    await this.#recordPending(txCtx, pending, true);
+                    return await this.#withTransactionalContext(txCtx, transact);
+                });
             });
         }
-        catch {
+        catch (error) {
+            if (transact !== undefined)
+                throw error;
             // Losing the record costs recovery precision, never the work itself: the turn is
             // already running and will answer whatever it was going to answer.
+            return undefined;
         }
     }
     /**
@@ -901,7 +943,7 @@ export class AgentBase {
             // crash could interrupt. What it records is refined as the run reaches each stage;
             // what matters at this point is that the record exists at all, since its absence is
             // what a later process reads as an agent that finished.
-            await this.#enterStage("inference");
+            await this.#enterStage("inference", this.#hooks.beforeAgentLoopTransact);
             await this.#invokeHook(this.#hooks.beforeAgentLoop);
             do {
                 this.#turnAborted = false;
@@ -930,20 +972,29 @@ export class AgentBase {
                     });
                     break;
                 }
-                await this.#applyActions(this.#hooks.beforeTurn, abort.signal, {
+                const turnStart = {
                     contextTokens: this.#contextTokens,
-                });
+                };
+                await this.#enterStage("inference", this.#hooks.beforeTurnTransact === undefined
+                    ? undefined
+                    : (hookCtx) => this.#hooks.beforeTurnTransact?.(hookCtx, turnStart));
+                await this.#applyActions(this.#hooks.beforeTurn, abort.signal, turnStart);
                 await this.#runInference(abort);
-                await this.#applyActions(this.#hooks.afterTurn, abort.signal, {
+                const turn = {
                     contextTokens: this.#contextTokens,
                     aborted: this.#turnAborted,
-                });
+                };
+                await this.#enterStage("inference", this.#hooks.afterTurnTransact === undefined
+                    ? undefined
+                    : (hookCtx) => this.#hooks.afterTurnTransact?.(hookCtx, turn));
+                await this.#applyActions(this.#hooks.afterTurn, abort.signal, turn);
                 if (!this.#turnRequested || this.#closed)
                     break;
                 // Each turn cancels on its own scope. Reopening it here rather than at the top
                 // keeps the run's first turn under the scope its opening hook already ran in.
                 abort = this.#openAbortScope();
             } while (true);
+            await this.#enterStage("inference", this.#hooks.afterAgentLoopTransact);
             await this.#applyActions(this.#hooks.afterAgentLoop, abort.signal);
         } while (this.#turnRequested && !this.#closed);
         // Nothing is asked for any more, so the outstanding work is erased. That erasure is what
@@ -960,7 +1011,7 @@ export class AgentBase {
      */
     async #settleDurably() {
         try {
-            await this.#persistenceLock.runInLock(this.#ctx, (lockCtx) => this.#persistence.transaction(lockCtx, async (txCtx) => {
+            await this.#persistenceLock.runInLock(this.#ctx, (lockCtx) => this.#recordTransaction(lockCtx, async (txCtx) => {
                 await this.#clearPending(txCtx);
                 await this.#invokeTransactionalSettle(txCtx);
                 // The run store is erased last, so a settling hook can still read what the
@@ -985,15 +1036,7 @@ export class AgentBase {
         const hook = this.#hooks.afterAgentSettledTransact;
         if (hook === undefined)
             return;
-        const committed = new AbortController();
-        try {
-            const liveCtx = withLifetime(insideTurn.set(txCtx, []), committed.signal);
-            const hookCtx = withAgentKV(liveCtx, this.#kv);
-            await hook(withAgentRunKV(hookCtx, this.#runKV));
-        }
-        finally {
-            committed.abort();
-        }
+        await this.#withTransactionalContext(insideTurn.set(txCtx, []), hook);
     }
     /**
      * Erase everything the run wrote about itself, inside the transaction that settles the agent:
@@ -1044,6 +1087,21 @@ export class AgentBase {
     async #invokeHook(hook, ...args) {
         await this.#invokeHookOn(this.#ctx, hook, ...args);
     }
+    /**
+     * Lend a hook the transaction's context and feature stores for exactly one callback. Keeping
+     * the context after the callback cannot leak a transaction past its commit.
+     */
+    async #withTransactionalContext(txCtx, work) {
+        const lifetime = new AbortController();
+        try {
+            const liveCtx = withLifetime(txCtx, lifetime.signal);
+            const hookCtx = withAgentKV(liveCtx, this.#kv);
+            return await work(withAgentRunKV(hookCtx, this.#runKV));
+        }
+        finally {
+            lifetime.abort();
+        }
+    }
     /**
      * Ask a hook what to do next, on a scope that may be cancelled while the hook is still
      * thinking. An abort owns the whole of the turn it cancelled, including the answer of a hook
@@ -1177,9 +1235,9 @@ export class AgentBase {
                         this.#emit({ type: "done", state: "cancelled" });
                     break;
                 }
-                let injected = await this.#consumeQueue(this.#steering, this.#steeringMode, "steering.");
+                let injected = await this.#consumeQueue(this.#steering, this.#steeringMode, "steering");
                 if (!injected && !needsInference) {
-                    injected = await this.#consumeQueue(this.#sends, this.#sendMode, "send.");
+                    injected = await this.#consumeQueue(this.#sends, this.#sendMode, "send");
                 }
                 // Nothing to answer — a start() on an idle history, or the queues ran dry.
                 if (!injected && !needsInference)
@@ -1193,6 +1251,7 @@ export class AgentBase {
                 // either.
                 if ((await Promise.race([this.#settled(), abortPromise])) === ABORTED)
                     continue;
+                await this.#enterStage("inference", this.#hooks.beforeInferenceTransact);
                 await this.#invokeHook(this.#hooks.beforeInference);
                 const stream = session.run(this.#ctx, {
                     context: {
@@ -1206,14 +1265,21 @@ export class AgentBase {
                 const { content, state, errorMessage, tokens } = await this.#collect(stream, abortPromise);
                 // A cancelled or failed response measures nothing, so the conversation keeps
                 // the last real measurement instead of forgetting how large it had become.
-                if (tokens !== undefined) {
-                    await this.#recordContextTokens(tokens.input + tokens.output);
-                }
-                await this.#invokeHook(this.#hooks.afterInference, {
+                const inference = {
                     state,
                     tokens,
                     ...(errorMessage === undefined ? {} : { errorMessage }),
-                });
+                };
+                const afterInferenceTransact = this.#hooks.afterInferenceTransact === undefined
+                    ? undefined
+                    : (hookCtx) => this.#hooks.afterInferenceTransact?.(hookCtx, inference);
+                if (tokens === undefined) {
+                    await this.#enterStage("inference", afterInferenceTransact);
+                }
+                else {
+                    await this.#recordContextTokens(tokens.input + tokens.output, afterInferenceTransact);
+                }
+                await this.#invokeHook(this.#hooks.afterInference, inference);
                 if (content.length > 0) {
                     this.#messages.push({ role: "assistant", content });
                 }
@@ -1305,15 +1371,31 @@ export class AgentBase {
      * lets a restarted agent keep knowing how large the conversation is without inferring it;
      * a failed write costs only that knowledge and never the response that produced it.
      */
-    async #recordContextTokens(tokens) {
+    async #recordContextTokens(tokens, transact) {
+        const previousTokens = this.#contextTokens;
         this.#contextTokens = tokens;
         try {
-            await this.#persistenceLock.runInLock(this.#ctx, (lockCtx) => tokens === undefined
-                ? this.#persistence.deleteValue(lockCtx, "context")
-                : this.#persistence.writeValue(lockCtx, "context", { tokens }));
+            await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
+                const write = (writeCtx) => tokens === undefined
+                    ? this.#persistence.deleteValue(writeCtx, "context")
+                    : this.#persistence.writeValue(writeCtx, "context", { tokens });
+                if (transact === undefined) {
+                    await write(lockCtx);
+                    return;
+                }
+                await this.#recordTransaction(lockCtx, async (txCtx) => {
+                    await write(txCtx);
+                    await this.#withTransactionalContext(txCtx, transact);
+                });
+            });
         }
-        catch {
-            // A measurement is not worth failing a turn over; memory still carries it.
+        catch (error) {
+            // The prior committed measurement stays authoritative in memory. A transactional
+            // observer is part of the same durable conclusion and therefore fails the turn when
+            // that conclusion cannot commit; an ordinary best-effort measurement still does not.
+            this.#contextTokens = previousTokens;
+            if (transact !== undefined)
+                throw error;
         }
     }
     /**
@@ -1401,6 +1483,10 @@ export class AgentBase {
                 await this.#recordTransaction(lockCtx, async (txCtx) => {
                     for (const result of results) {
                         await this.#appendRecord(txCtx, { type: "tool", message: result });
+                        // A result the conversation records is a result the hook sees, however
+                        // little of a run produced it. A hook that fails here leaves the calls
+                        // unsettled, which is what lets a later attempt answer them properly.
+                        await this.#invokeToolTransactHook(txCtx, result.callId, this.#hooks.afterToolCallTransact, result);
                     }
                 });
                 this.#messages.push(...results);
@@ -1465,9 +1551,17 @@ export class AgentBase {
      * Move the oldest queued message — or, in "all" mode, every queued message — into the main
      * context store and the in-memory history. The moves run in one transaction, so a message
      * is never durable in both stores or neither, and memory changes only after the commit.
-     */
-    async #consumeQueue(queue, mode, prefix) {
-        return await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
+     *
+     * What the consumption has to announce is announced once the lock has been released. A hook
+     * told a message has landed may perfectly well answer by sending another one, and doing that
+     * while this still held the store lock would be the hook waiting for its own caller.
+     */
+    async #consumeQueue(queue, mode, kind) {
+        const prefix = `${kind}.`;
+        /** Filled in once the consumption has committed, and reported after the lock is released. */
+        const accepted = [];
+        let permissionChange;
+        const consumed = await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
             if (queue.length === 0)
                 return false;
             // The durable queue, not memory, decides what is left to consume after a restart.
@@ -1486,6 +1580,7 @@ export class AgentBase {
             let model = this.#model;
             let effort = this.#effort;
             let serviceTier = this.#serviceTier;
+            let permissionMode = this.#permissionMode;
             let changed = false;
             for (const entry of batch) {
                 if (entry.options.provider !== undefined) {
@@ -1504,7 +1599,17 @@ export class AgentBase {
                     serviceTier = entry.options.serviceTier;
                     changed = true;
                 }
+                if (entry.options.permissionMode !== undefined) {
+                    permissionMode = entry.options.permissionMode;
+                    changed = true;
+                }
             }
+            // The mode the messages make effective, kept apart from the rest because it is the one
+            // setting with hooks of its own: a change is announced, and what a feature concludes
+            // from it commits with the message that carried it.
+            const modeChange = permissionMode === this.#permissionMode
+                ? undefined
+                : { previousMode: this.#permissionMode, mode: permissionMode };
             // A provider or model change is checked against the provider-model compatibility
             // matrix. An incompatible change resets the conversation: the history is erased
             // completely, the old provider session is destroyed, and the `modelChanged` hook
@@ -1554,6 +1659,7 @@ export class AgentBase {
                             model,
                             effort,
                             serviceTier,
+                            permissionMode,
                         }), committed.signal);
                         const changeCtx = withAgentRunKV(withAgentKV(changeLifetime, this.#kv), this.#runKV);
                         try {
@@ -1614,13 +1720,28 @@ export class AgentBase {
                         ...(model === undefined ? {} : { model }),
                         ...(effort === undefined ? {} : { effort }),
                         ...(serviceTier === undefined ? {} : { serviceTier }),
+                        permissionMode,
                     });
                 }
                 // Consuming a message is precisely the act that makes an inference owed, so
                 // the two commit as one. A crash cannot land between them and leave a
                 // message in the conversation that nothing remembers having to answer.
                 await this.#recordPending(txCtx, { stage: "inference" });
+                // Last, so a hook writing its own account of the consumption sees a transaction
+                // holding all of it. The mode comes before the messages: it is what they were
+                // said under, and a listener recording them wants to know that first.
+                const selection = { provider, model, effort, serviceTier, permissionMode };
+                if (modeChange !== undefined) {
+                    await this.#invokeTransactHook(txCtx, selection, this.#hooks.permissionModeChangedTransact, modeChange);
+                }
+                for (const entry of batch) {
+                    await this.#invokeTransactHook(txCtx, selection, this.#hooks.messageAcceptedTransact, { kind, message: entry.message });
+                }
             });
+            // Committed: from here the messages are part of the conversation, so what has to be
+            // announced about them is decided now and reported once the lock is released.
+            permissionChange = modeChange;
+            accepted.push(...batch.map((entry) => ({ kind, message: entry.message })));
             queue.splice(0, count);
             if (reset) {
                 this.#messages = injected === undefined ? [] : [injected];
@@ -1640,10 +1761,31 @@ export class AgentBase {
                 this.#model = model;
                 this.#effort = effort;
                 this.#serviceTier = serviceTier;
+                this.#permissionMode = permissionMode;
                 this.#ctx = this.#deriveCtx();
             }
             return true;
         });
+        // Outside the lock, and on the agent's own context, which now carries whatever these
+        // messages made effective.
+        if (permissionChange !== undefined) {
+            await this.#invokeHook(this.#hooks.permissionModeChanged, permissionChange);
+        }
+        for (const message of accepted) {
+            await this.#invokeHook(this.#hooks.messageAccepted, message);
+        }
+        return consumed;
+    }
+    /**
+     * Call a hook that writes inside the consumption's transaction, on a context carrying the
+     * selection those messages made effective rather than the one they replaced. Its failure is
+     * not contained: it rolls the whole consumption back, leaving the messages queued.
+     */
+    async #invokeTransactHook(txCtx, selection, hook, argument) {
+        if (hook === undefined)
+            return;
+        const hookCtx = withAgentContext(txCtx, { id: this.id, ...selection });
+        await this.#withTransactionalContext(hookCtx, (liveCtx) => hook(liveCtx, argument));
     }
     /**
      * Replace the in-memory state with the durable one. The persistence lock guarantees every
@@ -1682,6 +1824,13 @@ export class AgentBase {
                 this.#model = persisted.model;
                 this.#effort = persisted.effort;
                 this.#serviceTier = persisted.serviceTier;
+                // The permission mode is the one setting whose absence is not a decision: a record
+                // written before any message carried a mode says nothing about it, and a value
+                // that is not a mode at all says nothing either. Both keep the mode the agent was
+                // built with rather than running under something nothing can interpret.
+                if (isAgentPermissionMode(persisted.permissionMode)) {
+                    this.#permissionMode = persisted.permissionMode;
+                }
                 this.#ctx = this.#deriveCtx();
             }
             this.#pendingTools = pendingTools.map(({ key, value }) => ({
@@ -1726,6 +1875,11 @@ export class AgentBase {
                 // then never find calls owed with no record of a run owing them, nor a run
                 // recorded as running tools that were never written.
                 await this.#recordPending(txCtx, { stage: "tools" });
+                // Last, so a hook noting a call about to happen sees a transaction holding
+                // the whole batch it belongs to.
+                for (const entry of entries) {
+                    await this.#invokeToolTransactHook(txCtx, entry.call.callId, this.#hooks.beforeToolCallTransact, entry.call);
+                }
             }));
         }
         else {
@@ -1761,6 +1915,7 @@ export class AgentBase {
                             // stays: that is the tool's state, not the batch's bookkeeping, and
                             // an owner may still want to read what a finished call recorded.
                             await this.#persistence.deleteValue(txCtx, entry.key);
+                            await this.#invokeToolTransactHook(txCtx, entry.call.callId, this.#hooks.afterToolCallTransact, result);
                         });
                         this.#messages.push(result);
                         committed += 1;
@@ -1857,6 +2012,30 @@ export class AgentBase {
     #toolKey(index, callId) {
         return `tool.${String(index).padStart(6, "0")}.${callId}`;
     }
+    /**
+     * The scope one call owns: state persists under its own call ID, never in another call's
+     * scope, and the task context ends where the call was made. The execution and all four tool
+     * hooks share it, so what one of them writes about a call is where the others look for it.
+     */
+    #callScoped(ctx, callId) {
+        return withAgentTaskContext(withAgentRunKV(withAgentKV(ctx, this.#kv.scoped("call", callId)), this.#runKV.scoped("call", callId)), taskContextBeforeToolCall(this.#messages, callId));
+    }
+    /**
+     * Call a tool hook that writes inside a transaction of its own call's. The lifetime ends with
+     * the callback, so a context kept afterwards cannot outlive the transaction it belongs to.
+     * Its failure is not contained: it rolls that transaction back.
+     */
+    async #invokeToolTransactHook(txCtx, callId, hook, argument) {
+        if (hook === undefined)
+            return;
+        const lifetime = new AbortController();
+        try {
+            await hook(this.#callScoped(withLifetime(txCtx, lifetime.signal), callId), argument);
+        }
+        finally {
+            lifetime.abort();
+        }
+    }
     /**
      * Run one tool call; every failure becomes an error tool result instead of an exception.
      * The context carries the turn's abort signal as its lifetime, so a running tool can
@@ -1886,34 +2065,77 @@ export class AgentBase {
         if (tool.parameters !== undefined && !Value.Check(tool.parameters, args)) {
             return failure(`The arguments for "${call.name}" did not match its schema.`);
         }
+        const callCtx = this.#callScoped(ctx, call.callId);
+        // From here the call is one the two tool hooks bracket: a tool that exists, a call that
+        // finished, and arguments its schema accepts. A call refused before that reaches neither
+        // hook, because there is nothing yet to decide about or to report.
+        let ran = tool;
+        let ranArguments = args;
+        let outcome;
         try {
-            // A tool execution persists under its own call ID, never in another call's scope.
-            const callCtx = withAgentTaskContext(withAgentRunKV(withAgentKV(ctx, this.#kv.scoped("call", call.callId)), this.#runKV.scoped("call", call.callId)), taskContextBeforeToolCall(this.#messages, call.callId));
-            let executed;
-            const execute = () => (executed ??= Promise.resolve().then(async () => await tool.execute(callCtx, args)));
-            const result = this.#hooks.aroundToolExecution === undefined
-                ? await execute()
-                : await this.#hooks.aroundToolExecution(callCtx, {
+            const decision = await this.#hooks.beforeToolCall?.(callCtx, {
+                callId: call.callId,
+                tool,
+                arguments: args,
+            });
+            if (decision?.type === "answer") {
+                // The hook answered the model itself, so the tool never runs and there is no
+                // structured result — only what the model is told.
+                outcome = {
                     callId: call.callId,
                     tool,
                     arguments: args,
-                    execute,
-                });
-            if (!Value.Check(tool.returnType, result)) {
-                return failure(`Tool "${call.name}" returned an invalid result.`);
+                    content: [...decision.content],
+                    isError: decision.isError === true,
+                };
+            }
+            else {
+                if (decision?.tool !== undefined)
+                    ran = decision.tool;
+                if (decision?.arguments !== undefined)
+                    ranArguments = decision.arguments;
+                // An amended call is validated again: the schema that mattered is the one belonging
+                // to the tool that is about to run, on the arguments it is about to receive.
+                if ((ran !== tool || ranArguments !== args) &&
+                    ran.parameters !== undefined &&
+                    !Value.Check(ran.parameters, ranArguments)) {
+                    throw new Error(`The arguments for "${ran.name}" did not match its schema.`);
+                }
+                const runCtx = decision?.permissionMode === undefined
+                    ? callCtx
+                    : withAgentPermissionMode(callCtx, decision.permissionMode);
+                const result = await ran.execute(runCtx, ranArguments);
+                if (!Value.Check(ran.returnType, result)) {
+                    throw new Error(`Tool "${ran.name}" returned an invalid result.`);
+                }
+                outcome = {
+                    callId: call.callId,
+                    tool: ran,
+                    arguments: ranArguments,
+                    content: [...ran.toLLM(result)],
+                    isError: ran.isError?.(result) === true,
+                    result,
+                };
             }
-            const content = tool.toLLM(result);
-            const isError = tool.isError?.(result) === true;
-            return {
-                role: "tool",
-                callId: call.callId,
-                content: [...content],
-                ...(isError ? { isError: true } : {}),
-            };
         }
         catch (error) {
-            return failure(error instanceof Error ? error.message : String(error));
+            outcome = {
+                callId: call.callId,
+                tool: ran,
+                arguments: ranArguments,
+                content: [
+                    { type: "text", text: error instanceof Error ? error.message : String(error) },
+                ],
+                isError: true,
+            };
         }
+        await this.#invokeHookOn(callCtx, this.#hooks.afterToolCall, outcome);
+        return {
+            role: "tool",
+            callId: call.callId,
+            content: outcome.content,
+            ...(outcome.isError ? { isError: true } : {}),
+        };
     }
     /**
      * A key that sorts after every entry the queue already holds. The order comes from the store
@@ -1946,11 +2168,21 @@ export class AgentBase {
         // in-memory assistant message never diverges from what a reload would rebuild.
         const persisted = [];
         const toolCallIndexes = new Map();
-        const persist = async (block) => {
-            if (block === undefined)
+        const persist = async (event) => {
+            if (event === undefined)
                 return;
-            await this.#persistenceLock.runInLock(this.#ctx, (lockCtx) => this.#appendRecord(lockCtx, { type: "block", block }));
-            persisted.push(block);
+            await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
+                if (this.#hooks.onEventTransact === undefined) {
+                    await this.#appendRecord(lockCtx, { type: "block", block: event.block });
+                }
+                else {
+                    await this.#recordTransaction(lockCtx, async (txCtx) => {
+                        await this.#appendRecord(txCtx, { type: "block", block: event.block });
+                        await this.#withTransactionalContext(txCtx, (hookCtx) => this.#hooks.onEventTransact?.(hookCtx, event));
+                    });
+                }
+            });
+            persisted.push(event.block);
         };
         const iterator = stream[Symbol.asyncIterator]();
         // A response usually ends before its stream does — at the done event, or at an abort —
@@ -1989,7 +2221,7 @@ export class AgentBase {
                     }
                     case "text_end": {
                         const last = content[content.length - 1];
-                        await persist(last?.type === "text" ? last : undefined);
+                        await persist(last?.type === "text" ? { ...event, block: last } : undefined);
                         break;
                     }
                     case "reasoning_start":
@@ -2015,7 +2247,7 @@ export class AgentBase {
                                     : { reasoning: event.reasoning }),
                             };
                             content[content.length - 1] = finished;
-                            await persist(finished);
+                            await persist({ ...event, block: finished });
                         }
                         break;
                     }
@@ -2045,7 +2277,7 @@ export class AgentBase {
                                     : { incomplete: event.incomplete }),
                             };
                             content[index] = finished;
-                            await persist(finished);
+                            await persist({ ...event, block: finished });
                         }
                         break;
                     }