@code-yeongyu/senpi-agent-core 2026.9.29 → 2026.10.1-2

package/README.md

@@ -130,27 +130,54 @@ The `beforeToolCall` hook runs after `tool_execution_start` and validated argume
 
 Tools, blocked `beforeToolCall` results, and `afterToolCall` overrides can return `terminate: true` to hint that the automatic follow-up LLM call should be skipped. The loop only stops early when every finalized tool result in that batch sets `terminate: true`. Mixed batches continue normally.
 
-The `Agent` class accepts `shouldStopAfterTurn` in `AgentOptions`. Low-level loop callers can set the same hook in `AgentLoopConfig`:
+When you use the `Agent` class, assistant `message_end` processing is treated as a barrier before tool preflight begins. That means `beforeToolCall` sees agent state that already includes the assistant message that requested the tool call.
+
+### Request preparation and turn finalization
+
+`prepareRequest` runs immediately before every conversational provider request, including the first. Use it to install canonical persisted context after pending input has been emitted:
 
 ```typescript
-const stream = agentLoop(
-  prompts,
-  context,
-  {
-    model,
-    convertToLlm,
-    shouldStopAfterTurn: async ({ message, toolResults, context, newMessages }) => {
-      return shouldCompactBeforeNextTurn(context.messages);
-    },
-  },
-  undefined,
-  models.streamSimple.bind(models),
-);
+agent.prepareRequest = async ({ context }) => ({
+  context: { ...context, messages: await session.loadModelContext() },
+});
 ```
 
-`shouldStopAfterTurn` runs after `turn_end` is emitted and after the assistant response and any tool executions have completed normally. If it returns `true`, the loop emits `agent_end` and exits before polling steering or follow-up queues, and before starting another LLM call. It does not abort the provider stream, does not cancel running tools, and does not alter the assistant message stop reason. The `AgentOptions` callback also receives the active run's `AbortSignal` as its second argument.
+`prepareRequest` does not poll queues. Steering queued while it runs waits for the next normal steering poll.
 
-When you use the `Agent` class, assistant `message_end` processing is treated as a barrier before tool preflight begins. That means `beforeToolCall` sees agent state that already includes the assistant message that requested the tool call.
+`finishTurn` runs after the assistant message and all tool results are finalized, but before `turn_end`. It runs for normal, error, and aborted responses:
+
+```typescript
+agent.finishTurn = async ({ message }) => {
+  if (message.stopReason === "error" || message.stopReason === "aborted") return;
+  if (shouldEndRun(message)) return { action: "end" };
+  return needsAnotherResponse(message) ? { action: "continue" } : undefined;
+};
+```
+
+Returning `undefined` keeps normal scheduling. `{ action: "end" }` stops right after `turn_end`, before polling steering or follow-up queues or preparing another request. On a normal response, `{ action: "continue" }` makes sure one more provider request happens: tool results, steering, or a follow-up that already cause that request satisfy it, and otherwise the loop makes one context-only request. Error and aborted responses stay hard exits, so their decisions are ignored. `finishTurn` runs again after the next request, so returning `{ action: "continue" }` unconditionally loops forever. Low-level loop callers set the same hooks in `AgentLoopConfig`.
+
+To migrate from the removed `shouldStopAfterTurn`, return `{ action: "end" }` and guard error and aborted responses to keep the old normal-response-only invocation:
+
+```typescript
+finishTurn: async (turn, signal) => {
+  if (turn.message.stopReason === "error" || turn.message.stopReason === "aborted") return;
+  return (await shouldStop(turn, signal)) ? { action: "end" } : undefined;
+},
+```
+
+Each provider turn follows this lifecycle:
+
+```text
+selected input events
+→ prepareRequest
+→ provider response
+→ tool results
+→ finishTurn
+→ turn_end
+→ existing continuation scheduling or agent_end
+```
+
+`agent.peekQueuedMessages()` previews the next queue-selected batch, respecting the queue modes, without consuming it.
 
 ### continue() Event Sequence
 
@@ -247,9 +274,10 @@ const agent = new Agent({
     }
   },
 
-  // Stop gracefully after a completed turn, before queued messages are polled.
-  shouldStopAfterTurn: async ({ context }, signal) => {
-    return shouldCompactBeforeNextTurn(context.messages, signal);
+  // End the run gracefully after a completed turn, before queued messages are polled.
+  finishTurn: async ({ message, context }, signal) => {
+    if (message.stopReason === "error" || message.stopReason === "aborted") return;
+    return (await shouldCompactBeforeNextTurn(context.messages, signal)) ? { action: "end" } : undefined;
   },
 
   // Custom thinking budgets for token-based providers
@@ -316,7 +344,8 @@ agent.state.tools = [myTool];
 agent.toolExecution = "sequential";
 agent.beforeToolCall = async ({ toolCall }) => undefined;
 agent.afterToolCall = async ({ toolCall, result }) => undefined;
-agent.shouldStopAfterTurn = async ({ context }) => shouldCompactBeforeNextTurn(context.messages);
+agent.prepareRequest = async ({ context }) => undefined;
+agent.finishTurn = async () => undefined;
 agent.state.messages = newMessages; // top-level array is copied
 agent.state.messages.push(message);
 agent.reset();

package/dist/agent-loop.d.ts

@@ -2,9 +2,9 @@
  * Agent loop that works with AgentMessage throughout.
  * Transforms to Message[] only at the LLM call boundary.
  */
-import { type Context, EventStream } from "@earendil-works/pi-ai";
+import { type AssistantMessage, EventStream, type TranscriptContext } from "@earendil-works/pi-ai";
 import { prepareAgentToolCallArguments } from "./tool-arguments.ts";
-import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, AgentTool, AgentToolCall, StreamFn } from "./types.ts";
+import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, AgentTool, AgentToolCall, AgentToolCallOutcome, AgentToolResult, StreamFn } from "./types.ts";
 export type AgentEventSink = (event: AgentEvent) => Promise<void> | void;
 /**
  * Start an agent loop with a new prompt message.
@@ -26,7 +26,10 @@ export declare class StreamStartTimeoutError extends Error {
     constructor(timeoutMs: number);
 }
 /** Build the provider context using the same transform and conversion pipeline as an agent request. */
-export declare function buildProviderContext(context: AgentContext, config: Pick<AgentLoopConfig, "convertToLlm" | "transformContext"> & Partial<Pick<AgentLoopConfig, "model">>, signal?: AbortSignal): Promise<Context>;
+export declare function buildProviderContext(context: AgentContext, config: Pick<AgentLoopConfig, "convertToLlm" | "transformContext"> & Partial<Pick<AgentLoopConfig, "model">>, signal?: AbortSignal): Promise<TranscriptContext>;
+/** The `beforeToolCall` and `afterToolCall` hooks of {@link AgentLoopConfig}. */
+export type ToolCallHooks = Pick<AgentLoopConfig, "beforeToolCall" | "afterToolCall">;
+type ToolUpdateSink = (partialResult: AgentToolResult<any>) => Promise<void> | void;
 export interface PreparedAgentToolCall {
     toolCall: AgentToolCall;
     tool: AgentTool;
@@ -34,4 +37,25 @@ export interface PreparedAgentToolCall {
 }
 export { prepareAgentToolCallArguments };
 export declare function prepareAgentToolCall(tool: AgentTool, toolCall: AgentToolCall): PreparedAgentToolCall;
+/** Options for {@link runToolCall}. */
+export interface RunToolCallOptions extends ToolCallHooks {
+    /** Tools the call resolves against. */
+    tools: readonly AgentTool<any>[];
+    /** Passed to the hooks as the message that issued the call. */
+    assistantMessage: AssistantMessage;
+    /** Passed to the hooks as the current agent context. */
+    context: AgentContext;
+    signal?: AbortSignal;
+    onUpdate?: ToolUpdateSink;
+}
+/**
+ * Run one tool call through the same steps as a model-issued call: argument preparation, schema
+ * validation, `beforeToolCall`, execution, and `afterToolCall`. Emits no events and adds no
+ * messages. Tools that call other tools use this so the hooks (for example permission checks)
+ * apply to those calls too.
+ *
+ * Never rejects for tool failures: unknown tools, validation errors, blocked calls, and thrown
+ * errors come back as `isError: true`.
+ */
+export declare function runToolCall(toolCall: AgentToolCall, options: RunToolCallOptions): Promise<AgentToolCallOutcome>;
 //# sourceMappingURL=agent-loop.d.ts.map

package/dist/agent-loop.js

@@ -2,7 +2,7 @@
  * Agent loop that works with AgentMessage throughout.
  * Transforms to Message[] only at the LLM call boundary.
  */
-import { EventStream, isCursorExecResolved, supportsAllowedToolChoice, validateToolArguments, } from "@earendil-works/pi-ai";
+import { createInitialSystemMessage, EventStream, getCurrentTools, getToolStateChanges, isCursorExecResolved, normalizeContext, supportsAllowedToolChoice, validateToolArguments, } from "@earendil-works/pi-ai";
 import { createTerminalFailureAssistantMessage, demoteToolUseWithoutToolCalls, isStreamIdleTimeoutError, normalizeTerminalAssistantMessage, promoteStopWithPendingToolCalls, shouldFinalizeIdleAsStop, shouldTerminateAssistantTurn, } from "./assistant-terminal-state.js";
 import { getDefaultStreamFn, withEmptyAssistantRecovery } from "./stream-fn.js";
 import { prepareAgentToolCallArguments } from "./tool-arguments.js";
@@ -44,16 +44,17 @@ export function agentLoopContinue(context, config, signal, streamFn) {
     return stream;
 }
 export async function runAgentLoop(prompts, context, config, emit, signal, streamFn) {
-    const newMessages = [...prompts];
+    const initialMessages = declareToolChanges(context, prompts, config.model);
+    const newMessages = [...initialMessages];
     const currentContext = {
         ...context,
-        messages: [...context.messages, ...prompts],
+        messages: [...context.messages, ...initialMessages],
     };
     await emit({ type: "agent_start" });
     await emit({ type: "turn_start" });
-    for (const prompt of prompts) {
-        await emit({ type: "message_start", message: prompt });
-        await emit({ type: "message_end", message: prompt });
+    for (const message of initialMessages) {
+        await emit({ type: "message_start", message });
+        await emit({ type: "message_end", message });
     }
     await runLoop(currentContext, newMessages, config, signal, emit, streamFn ?? getDefaultStreamFn());
     return newMessages;
@@ -100,6 +101,10 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
     let firstProviderRequest = true;
     let drainedTerminatingQueue;
     let turnStartAlreadyEmitted = false;
+    // Set by a `finishTurn` `{ action: "continue" }`; cleared once a natural request is scheduled.
+    let explicitContinuation = false;
+    // Messages from `prepareNextTurn`, appended before the next provider request.
+    let preparedMessages = [];
     const refreshTerminatingQueueDrain = async () => {
         if (!drainedTerminatingQueue || !config.restorePendingMessages)
             return;
@@ -129,21 +134,29 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
             }
             if (drainedTerminatingQueue) {
                 await refreshTerminatingQueueDrain();
-                if (pendingMessages.length === 0) {
+                if (pendingMessages.length === 0 && !explicitContinuation) {
                     await emit({ type: "agent_end", messages: newMessages });
                     return;
                 }
                 drainedTerminatingQueue = undefined;
             }
-            // Process pending messages (inject before next assistant response)
-            if (pendingMessages.length > 0) {
-                for (const message of pendingMessages) {
-                    await emit({ type: "message_start", message });
-                    await emit({ type: "message_end", message });
-                    currentContext.messages.push(message);
-                    newMessages.push(message);
-                }
-                pendingMessages = [];
+            // Process prepared and queued messages before the next assistant response.
+            for (const message of declareToolChanges(currentContext, [...preparedMessages, ...pendingMessages], config.model)) {
+                await emit({ type: "message_start", message });
+                await emit({ type: "message_end", message });
+                currentContext.messages.push(message);
+                newMessages.push(message);
+            }
+            preparedMessages = [];
+            pendingMessages = [];
+            const requestUpdate = await config.prepareRequest?.({
+                context: currentContext,
+                model: config.model,
+                thinkingLevel: config.reasoning ?? "off",
+            }, signal);
+            if (requestUpdate) {
+                currentContext = requestUpdate.context ?? currentContext;
+                config = applyLoopUpdate(config, requestUpdate);
             }
             // Stream assistant response
             const isInitialProviderRequest = firstProviderRequest;
@@ -168,6 +181,8 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
                 toolResults.push(result);
             }
             if (shouldTerminateAssistantTurn(message)) {
+                // Hard exit: the decision is ignored, but the hook still sees the finished turn before turn_end.
+                await config.finishTurn?.({ message, toolResults, context: currentContext, newMessages }, signal);
                 await emit({ type: "turn_end", message, toolResults });
                 await emit({ type: "agent_end", messages: newMessages });
                 return;
@@ -191,21 +206,23 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
                     newMessages.push(result);
                 }
             }
-            await emit({ type: "turn_end", message, toolResults });
-            if (signal?.aborted) {
-                await emit({ type: "agent_end", messages: newMessages });
-                return;
-            }
             const nextTurnContext = {
                 message,
                 toolResults,
                 context: currentContext,
                 newMessages,
             };
-            if (await config.shouldStopAfterTurn?.(nextTurnContext)) {
+            const decision = await config.finishTurn?.(nextTurnContext, signal);
+            await emit({ type: "turn_end", message, toolResults });
+            if (signal?.aborted) {
+                await emit({ type: "agent_end", messages: newMessages });
+                return;
+            }
+            if (decision?.action === "end") {
                 await emit({ type: "agent_end", messages: newMessages });
                 return;
             }
+            explicitContinuation = decision?.action === "continue";
             if (toolBatchTerminated) {
                 pendingMessages = (await config.getSteeringMessages?.()) || [];
                 if (pendingMessages.length > 0)
@@ -215,14 +232,16 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
                     if (pendingMessages.length > 0)
                         drainedTerminatingQueue = "followUp";
                 }
-                if (pendingMessages.length === 0) {
+                if (pendingMessages.length === 0 && !explicitContinuation) {
                     await emit({ type: "agent_end", messages: newMessages });
                     return;
                 }
-                // Give queue owners a boundary before preparation refreshes the drained
-                // snapshot, so a clear or replacement wins before admission.
-                await emit({ type: "turn_start" });
-                turnStartAlreadyEmitted = true;
+                if (pendingMessages.length > 0) {
+                    // Give queue owners a boundary before preparation refreshes the drained
+                    // snapshot, so a clear or replacement wins before admission.
+                    await emit({ type: "turn_start" });
+                    turnStartAlreadyEmitted = true;
+                }
             }
             let nextTurnSnapshot;
             try {
@@ -235,19 +254,8 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
             }
             if (nextTurnSnapshot) {
                 currentContext = nextTurnSnapshot.context ?? currentContext;
-                config = {
-                    ...config,
-                    model: nextTurnSnapshot.model ?? config.model,
-                    reasoning: nextTurnSnapshot.thinkingLevel === undefined
-                        ? config.reasoning
-                        : nextTurnSnapshot.thinkingLevel === "off"
-                            ? undefined
-                            : nextTurnSnapshot.thinkingLevel,
-                    thinkingSelection: nextTurnSnapshot.thinkingSelection === undefined
-                        ? config.thinkingSelection
-                        : (nextTurnSnapshot.thinkingSelection ?? undefined),
-                    abortServerSideFallback: nextTurnSnapshot.abortServerSideFallback ?? config.abortServerSideFallback,
-                };
+                preparedMessages = nextTurnSnapshot.messages ?? [];
+                config = applyLoopUpdate(config, nextTurnSnapshot);
             }
             if (signal?.aborted) {
                 if (drainedTerminatingQueue)
@@ -257,7 +265,7 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
             }
             if (drainedTerminatingQueue) {
                 await refreshTerminatingQueueDrain();
-                if (pendingMessages.length === 0) {
+                if (pendingMessages.length === 0 && !explicitContinuation) {
                     await emit({ type: "agent_end", messages: newMessages });
                     return;
                 }
@@ -266,19 +274,115 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
             if (!toolBatchTerminated) {
                 pendingMessages = (await config.getSteeringMessages?.()) || [];
             }
+            if (hasMoreToolCalls || pendingMessages.length > 0) {
+                explicitContinuation = false;
+            }
         }
         // Agent would stop here. Check for follow-up messages.
         const followUpMessages = (await config.getFollowUpMessages?.()) || [];
         if (followUpMessages.length > 0) {
             // Set as pending so inner loop processes them
+            explicitContinuation = false;
             pendingMessages = followUpMessages;
             continue;
         }
+        // No natural request was selected, so fulfill the continuation decision with one context-only turn.
+        if (explicitContinuation) {
+            explicitContinuation = false;
+            continue;
+        }
         // No more messages, exit
         break;
     }
     await emit({ type: "agent_end", messages: newMessages });
 }
+/** Apply a `prepareNextTurn` or `prepareRequest` update to the loop config for this and later requests. */
+function applyLoopUpdate(config, update) {
+    return {
+        ...config,
+        model: update.model ?? config.model,
+        reasoning: update.thinkingLevel === undefined
+            ? config.reasoning
+            : update.thinkingLevel === "off"
+                ? undefined
+                : update.thinkingLevel,
+        thinkingSelection: update.thinkingSelection === undefined ? config.thinkingSelection : (update.thinkingSelection ?? undefined),
+        abortServerSideFallback: update.abortServerSideFallback ?? config.abortServerSideFallback,
+    };
+}
+/**
+ * Declare tool loadout changes to the model.
+ *
+ * The provider tools (senpi#2095 `providerTools`) are what the model may call; the transcript's system
+ * messages declare them. Before each request the difference becomes `toolsAdded` and `toolsRemoved` on a
+ * system message. When a pending system message exists, its tool fields are treated as intent and replaced
+ * with the delta between the committed transcript and the provider tools, so replay always yields exactly
+ * those tools. Otherwise a new system message is inserted before the first non-system pending message.
+ *
+ * Fork: `buildProviderContext` folds `context.systemPrompt` and the provider tools into the leading system
+ * message through `normalizeContext()`, so that shorthand declaration counts as committed. A context that
+ * carries its tools only through that shorthand therefore never gains a duplicate declaration.
+ */
+function declareToolChanges(context, pendingMessages, model) {
+    let systemIndex = -1;
+    for (let i = pendingMessages.length - 1; i >= 0; i--) {
+        if (pendingMessages[i].role === "system") {
+            systemIndex = i;
+            break;
+        }
+    }
+    const pending = pendingMessages[systemIndex];
+    const baseline = pending
+        ? pendingMessages.map((message, index) => index === systemIndex ? withToolChanges(pending, NO_CHANGES) : message)
+        : pendingMessages;
+    const declared = (providerTools(context, model).tools ?? []).map(toProviderToolDeclaration);
+    const shorthand = createInitialSystemMessage(context.systemPrompt, declared);
+    const committed = shorthand ? [shorthand, ...context.messages, ...baseline] : [...context.messages, ...baseline];
+    const delta = getToolStateChanges(getCurrentTools(committed), declared);
+    // `getToolStateChanges` compares through upstream `toToolDeclaration`, which drops the fork `freeform` field;
+    // announce the fork declaration itself so a delta-added tool keeps its full provider shape.
+    const declaredByName = new Map(declared.map((tool) => [tool.name, tool]));
+    const changes = {
+        toolsAdded: delta.toolsAdded.map((tool) => declaredByName.get(tool.name) ?? tool),
+        toolsRemoved: delta.toolsRemoved,
+    };
+    const unchanged = changes.toolsAdded.length === 0 && changes.toolsRemoved.length === 0;
+    if (pending) {
+        // Keep the caller's message object when it already declares no tool changes.
+        if (unchanged && !pending.toolsAdded?.length && !pending.toolsRemoved?.length)
+            return pendingMessages;
+        return baseline.map((message, index) => (index === systemIndex ? withToolChanges(pending, changes) : message));
+    }
+    if (unchanged)
+        return pendingMessages;
+    const update = withToolChanges({ role: "system", content: "", timestamp: Date.now() }, changes);
+    const insertIndex = pendingMessages.findIndex((message) => message.role !== "system");
+    const index = insertIndex === -1 ? pendingMessages.length : insertIndex;
+    return [...pendingMessages.slice(0, index), update, ...pendingMessages.slice(index)];
+}
+const NO_CHANGES = { toolsAdded: [], toolsRemoved: [] };
+/**
+ * The provider-facing declaration of a tool: every `Tool` field (fork `freeform` included) and nothing executable,
+ * so transcripts stay cloneable and serializable. Upstream `toToolDeclaration` would drop `freeform`.
+ */
+function toProviderToolDeclaration(tool) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+        ...(tool.freeform === undefined ? {} : { freeform: tool.freeform }),
+        ...(tool.constrainedSampling === undefined ? {} : { constrainedSampling: tool.constrainedSampling }),
+    };
+}
+/** Copy a system message with its tool fields replaced by `changes`; empty lists omit the field. */
+function withToolChanges(message, { toolsAdded, toolsRemoved }) {
+    const { toolsAdded: _added, toolsRemoved: _removed, ...rest } = message;
+    return {
+        ...rest,
+        ...(toolsAdded.length > 0 ? { toolsAdded } : {}),
+        ...(toolsRemoved.length > 0 ? { toolsRemoved } : {}),
+    };
+}
 /**
  * senpi#2095: a model that accepts an allowed-tools restriction receives every declared tool plus the
  * callable subset by name; any other model receives the callable tools alone, as before.
@@ -300,11 +404,13 @@ export async function buildProviderContext(context, config, signal) {
     let messages = context.messages;
     if (config.transformContext)
         messages = await config.transformContext(messages, signal);
-    return {
+    const { tools, activeToolNames } = providerTools(context, config.model);
+    return normalizeContext({
         systemPrompt: context.systemPrompt,
         messages: await config.convertToLlm(messages),
-        ...providerTools(context, config.model),
-    };
+        ...(tools === undefined ? {} : { tools: tools.map(toProviderToolDeclaration) }),
+        ...(activeToolNames === undefined ? {} : { activeToolNames }),
+    });
 }
 /**
  * Stream an assistant response from the LLM.
@@ -367,6 +473,8 @@ async function streamAssistantResponse(context, config, signal, emit, streamFunc
                 }
                 : {}),
         });
+        // Record the requested level, whichever stream function answered.
+        const result = async () => Object.assign(await response.result(), { thinkingLevel: config.reasoning ?? "off" });
         const iterator = response[Symbol.asyncIterator]();
         const eventReader = createAssistantEventReader(iterator, streamIdleTimeoutMs, requestAbortController.signal, (error) => requestAbortController.abort(error), config.streamStartTimeoutMs, response);
         try {
@@ -423,7 +531,7 @@ async function streamAssistantResponse(context, config, signal, emit, streamFunc
                         break;
                     case "done":
                     case "error": {
-                        const finalMessage = normalizeTerminalAssistantMessage(await response.result(), event);
+                        const finalMessage = normalizeTerminalAssistantMessage(await result(), event);
                         propagateThinkingTiming(finalMessage);
                         if (addedPartial) {
                             context.messages[context.messages.length - 1] = finalMessage;
@@ -446,7 +554,7 @@ async function streamAssistantResponse(context, config, signal, emit, streamFunc
         finally {
             eventReader.dispose();
         }
-        const finalMessage = await response.result();
+        const finalMessage = await result();
         propagateThinkingTiming(finalMessage);
         if (addedPartial) {
             context.messages[context.messages.length - 1] = finalMessage;
@@ -672,7 +780,7 @@ async function executeToolCallsSequential(currentContext, assistantMessage, tool
             };
         }
         else {
-            const executed = await executePreparedToolCall(preparation, signal, emit);
+            const executed = await executePreparedToolCall(preparation, signal, emitToolExecutionUpdate(preparation.toolCall, emit));
             finalized = await finalizeExecutedToolCall(currentContext, assistantMessage, preparation, executed, config, signal);
         }
         await emitToolExecutionEnd(finalized, emit);
@@ -767,7 +875,7 @@ async function runPreparedToolCall(currentContext, assistantMessage, preparation
             isError: preparation.isError,
         };
     }
-    const executed = await executePreparedToolCall(preparation, signal, emit);
+    const executed = await executePreparedToolCall(preparation, signal, emitToolExecutionUpdate(preparation.toolCall, emit));
     return finalizeExecutedToolCall(currentContext, assistantMessage, preparation, executed, config, signal);
 }
 function isSequentialToolCall(currentContext, toolCall) {
@@ -884,20 +992,42 @@ function abortReleasePromise(signal) {
         signal.addEventListener("abort", () => resolve(ABORTED), { once: true });
     });
 }
-async function executePreparedToolCall(prepared, signal, emit) {
+function emitToolExecutionUpdate(toolCall, emit) {
+    return (partialResult) => emit({
+        type: "tool_execution_update",
+        toolCallId: toolCall.id,
+        toolName: toolCall.name,
+        args: toolCall.arguments,
+        partialResult,
+    });
+}
+/**
+ * Run one tool call through the same steps as a model-issued call: argument preparation, schema
+ * validation, `beforeToolCall`, execution, and `afterToolCall`. Emits no events and adds no
+ * messages. Tools that call other tools use this so the hooks (for example permission checks)
+ * apply to those calls too.
+ *
+ * Never rejects for tool failures: unknown tools, validation errors, blocked calls, and thrown
+ * errors come back as `isError: true`.
+ */
+export async function runToolCall(toolCall, options) {
+    const { assistantMessage, context, signal } = options;
+    const tool = options.tools.find((candidate) => candidate.name === toolCall.name);
+    const preparation = await prepareToolCall(context, assistantMessage, toolCall, tool, options, signal);
+    if (preparation.kind === "immediate") {
+        return { toolCall, result: preparation.result, isError: preparation.isError };
+    }
+    const executed = await executePreparedToolCall(preparation, signal, options.onUpdate ?? (() => { }));
+    return finalizeExecutedToolCall(context, assistantMessage, preparation, executed, options, signal);
+}
+async function executePreparedToolCall(prepared, signal, onUpdate) {
     const updateEvents = [];
     let acceptingUpdates = true;
     try {
         const execution = prepared.tool.execute(prepared.toolCall.id, prepared.args, signal, (partialResult) => {
             if (!acceptingUpdates)
                 return;
-            updateEvents.push(Promise.resolve(emit({
-                type: "tool_execution_update",
-                toolCallId: prepared.toolCall.id,
-                toolName: prepared.toolCall.name,
-                args: prepared.toolCall.arguments,
-                partialResult,
-            })));
+            updateEvents.push(Promise.resolve(onUpdate(partialResult)));
         });
         const abortRelease = abortReleasePromise(signal);
         const settled = abortRelease ? await Promise.race([execution, abortRelease]) : await execution;
@@ -937,6 +1067,8 @@ async function finalizeExecutedToolCall(currentContext, assistantMessage, prepar
                 context: currentContext,
             }, signal);
             if (afterResult) {
+                // Structured content not replaced along with the content may no longer match it.
+                const structuredContent = afterResult.structuredContent ?? (afterResult.content ? undefined : result.structuredContent);
                 result = {
                     ...result,
                     content: afterResult.content ?? result.content,
@@ -944,6 +1076,10 @@ async function finalizeExecutedToolCall(currentContext, assistantMessage, prepar
                     usage: afterResult.usage ?? result.usage,
                     terminate: afterResult.terminate ?? result.terminate,
                 };
+                if (structuredContent === undefined)
+                    delete result.structuredContent;
+                else
+                    result.structuredContent = structuredContent;
                 isError = afterResult.isError ?? isError;
             }
         }

package/dist/agent.d.ts

@@ -1,18 +1,25 @@
-import { type Context, type ImageContent, type Message, type SimpleStreamOptions, type ThinkingBudgets, type Transport } from "@earendil-works/pi-ai";
-import type { AfterToolCallContext, AfterToolCallResult, AgentContext, AgentEvent, AgentLoopConfig, AgentLoopTurnUpdate, AgentMessage, AgentState, BeforeToolCallContext, BeforeToolCallResult, PrepareNextTurnContext, QueueMode, ShouldStopAfterTurnContext, StreamFn, ToolExecutionMode } from "./types.ts";
+import { type ImageContent, type Message, type SimpleStreamOptions, type ThinkingBudgets, type TranscriptContext, type Transport } from "@earendil-works/pi-ai";
+import type { AfterToolCallContext, AfterToolCallResult, AgentContext, AgentEvent, AgentLoopConfig, AgentLoopTurnUpdate, AgentMessage, AgentState, BeforeToolCallContext, BeforeToolCallResult, FinishTurn, PrepareNextTurnContext, PrepareRequest, QueueMode, StreamFn, ToolExecutionMode } from "./types.ts";
 export type { QueueMode } from "./types.ts";
+/**
+ * Initial state for {@link Agent}. Fork: `systemPrompt` and `tools` stay the agent's own state and are folded
+ * into the leading system message per request by `buildProviderContext`; they are not copied into `messages`.
+ */
+export type AgentInitialState = Partial<Omit<AgentState, "pendingToolCalls" | "isStreaming" | "streamingMessage" | "errorMessage" | "providerDiagnostic">>;
 /** Options for constructing an {@link Agent}. */
 export interface AgentOptions {
-    initialState?: Partial<Omit<AgentState, "pendingToolCalls" | "isStreaming" | "streamingMessage" | "errorMessage" | "providerDiagnostic">>;
+    initialState?: AgentInitialState;
     convertToLlm?: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
     transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
     streamFn: StreamFn;
     getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
     onPayload?: SimpleStreamOptions["onPayload"];
     onResponse?: SimpleStreamOptions["onResponse"];
+    onProviderStreamEvent?: SimpleStreamOptions["onProviderStreamEvent"];
     beforeToolCall?: (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined>;
     afterToolCall?: (context: AfterToolCallContext, signal?: AbortSignal) => Promise<AfterToolCallResult | undefined>;
-    shouldStopAfterTurn?: (context: ShouldStopAfterTurnContext, signal?: AbortSignal) => boolean | Promise<boolean>;
+    finishTurn?: FinishTurn;
+    prepareRequest?: PrepareRequest;
     prepareNextTurn?: (signal?: AbortSignal) => Promise<AgentLoopTurnUpdate | undefined> | AgentLoopTurnUpdate | undefined;
     prepareNextTurnWithContext?: (context: PrepareNextTurnContext, signal?: AbortSignal) => Promise<AgentLoopTurnUpdate | undefined> | AgentLoopTurnUpdate | undefined;
     steeringMode?: QueueMode;
@@ -55,9 +62,11 @@ export declare class Agent {
     getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
     onPayload?: SimpleStreamOptions["onPayload"];
     onResponse?: SimpleStreamOptions["onResponse"];
+    onProviderStreamEvent?: SimpleStreamOptions["onProviderStreamEvent"];
     beforeToolCall?: (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined>;
     afterToolCall?: (context: AfterToolCallContext, signal?: AbortSignal) => Promise<AfterToolCallResult | undefined>;
-    shouldStopAfterTurn?: (context: ShouldStopAfterTurnContext, signal?: AbortSignal) => boolean | Promise<boolean>;
+    finishTurn?: FinishTurn;
+    prepareRequest?: PrepareRequest;
     prepareNextTurn?: (signal?: AbortSignal) => Promise<AgentLoopTurnUpdate | undefined> | AgentLoopTurnUpdate | undefined;
     prepareNextTurnWithContext?: (context: PrepareNextTurnContext, signal?: AbortSignal) => Promise<AgentLoopTurnUpdate | undefined> | AgentLoopTurnUpdate | undefined;
     private activeRun?;
@@ -82,7 +91,7 @@ export declare class Agent {
     abortServerSideFallback?: boolean;
     /** Cursor exec-channel tool handlers; see {@link AgentLoopConfig.cursorExecHandlers}. */
     cursorExecHandlers?: AgentLoopConfig["cursorExecHandlers"];
-    buildProviderContext(context: AgentContext, signal?: AbortSignal): Promise<Context>;
+    buildProviderContext(context: AgentContext, signal?: AbortSignal): Promise<TranscriptContext>;
     constructor(options: AgentOptions);
     /**
      * Subscribe to agent lifecycle events.
@@ -119,6 +128,8 @@ export declare class Agent {
     clearAllQueues(): void;
     /** Returns true when either queue still contains pending messages. */
     hasQueuedMessages(): boolean;
+    /** Preview the messages selected for the next turn without consuming them. */
+    peekQueuedMessages(): AgentMessage[];
     /** Active abort signal for the current run, if any. */
     get signal(): AbortSignal | undefined;
     /** Abort the current run, if one is active. */
@@ -136,7 +147,10 @@ export declare class Agent {
      * This resolves after `agent_end` listeners settle.
      */
     waitForIdle(): Promise<void>;
-    /** Clear transcript state, runtime state, and queued messages. */
+    /**
+     * Clear transcript state, runtime state, and queued messages. Fork: the prompt/tool baseline is agent state
+     * (`systemPrompt`, `tools`), so transcript system messages are conversation content and are cleared too.
+     */
     reset(): void;
     /** Start a new prompt from text, a single message, or a batch of messages. */
     prompt(message: AgentMessage | AgentMessage[]): Promise<void>;