@sema-agent/core 7.54.1 → 7.56.0

package/dist/engine/llm/types.d.ts

@@ -5,6 +5,7 @@ import type { ProviderCondition, ProviderConditionSource } from "../../brain/pro
 import type { RequestRoute, RouteCarrierBag, RouteCredentialSource } from "../../brain/request-route.js";
 export type { RouteCredentialSource } from "../../brain/request-route.js";
 import type { ModelOutputInvalidCause } from "./tool-turns.js";
+import type { PromptTraitName, TraitCondition } from "../../prompt-assembly/catalog/schema.js";
 export type KnownApi = "openai-completions" | "mistral-conversations" | "openai-responses" | "azure-openai-responses" | "openai-chatgpt-responses" | "anthropic-messages" | "bedrock-converse-stream" | "google-generative-ai" | "google-vertex";
 export type Api = KnownApi | (string & {});
 export type KnownImagesApi = "openrouter-images";
@@ -611,10 +612,10 @@ export interface AssistantMessage {
     /**
      * design/124 tier A: this final message was PARTIALLY FINALIZED after a mid-stream connection
      * loss/stall — the substantive streamed prefix (text and/or completed tool calls) was promoted to
-     * final content instead of failing the turn (CC 198 queryModelStreaming parity: avoid re-billing +
+     * final content instead of failing the turn (avoid re-billing +
      * keep the displayed content consistent with the result). `stopReason` is synthesized from the
      * content ("toolUse" when a completed tool call streamed, else "stop"); `errorMessage` carries the
-     * warning in CC 2.1.220's words ("Response stalled mid-stream." / "Connection closed mid-response."; gone from 2.1.245 on), visible
+     * warning in the reference's former words ("Response stalled mid-stream." / "Connection closed mid-response."), visible
      * to the model in the transcript. Downstream semantics (agent-loop): `partialFinalized &&
      * stopReason==="stop"` gets a BOUNDED continue nudge (an unattended run must not book the cut as an
      * incomplete success); `partialFinalized && stopReason==="toolUse"` executes normally (a truncated
@@ -697,11 +698,24 @@ export interface Tool<TParameters extends TSchema = TSchema> {
     /** VENDORED EDIT (design/115 P0): canonical tool renames keep old model/SDK wire names as aliases. */
     aliases?: string[];
     description: string;
-    /** R2 双形轴 — classic-profile description variant (see ToolSpec.descriptionClassic). Swapped in
-     *  for `description` at mount time when the run's promptProfile is "classic"; absent = one form. */
-    descriptionClassic?: string;
+    /** The description's conditional variants (see ToolSpec.descriptionVariants): at mount, the first whose traits
+     *  condition holds over the run's traits replaces `description`; none holds ⇒ `description`. */
+    descriptionVariants?: readonly ToolDescriptionVariant[];
     parameters: TParameters;
 }
+/**
+ * One conditional variant of a tool's description — the tool card's variant table is these, first match wins, with
+ * `description` as the unconditional last entry. Chosen by the run's prompt traits through the same trait reading the
+ * prompt catalog's variants use; the variant chosen is reported in the tool's `cardId` (`<card>#<id>`).
+ */
+export interface ToolDescriptionVariant {
+    /** The variant's name in the tool's card id: non-empty, at most 64 characters of `[A-Za-z0-9._-]`, unique per tool. */
+    readonly id: string;
+    /** The trait condition (`allOf` / `noneOf`, trait names) under which this text replaces `description`. */
+    readonly traits: TraitCondition;
+    /** The description text (non-blank). */
+    readonly text: string;
+}
 export interface Context {
     systemPrompt?: string;
     /**
@@ -877,7 +891,7 @@ export interface OpenAIResponsesCompat {
  */
 export interface AnthropicMessagesCompat {
     /**
-     * How this endpoint takes extended thinking (CC 2.1.198 parity, design/119).
+     * How this endpoint takes extended thinking (design/119).
      * - `"budget"` (default, pre-Fable models): `thinking: { type: "enabled", budget_tokens }`.
      * - `"adaptive"` (Fable 5 / Opus 4.8/4.7 class): `thinking: { type: "adaptive" }` — NO
      *   `budget_tokens` (these models 400 on a budget), no max_tokens bump; the intensity is carried
@@ -886,7 +900,7 @@ export interface AnthropicMessagesCompat {
      */
     thinkingMode?: "budget" | "adaptive";
     /**
-     * Effort tiers this endpoint accepts via `output_config.effort` (CC 2.1.198 `effort` /
+     * Effort tiers this endpoint accepts via `output_config.effort` (the reference's `effort` /
      * `xhigh_effort` / `max_effort` capability bits collapsed into one declared set, matching the
      * `reasoningEffortLevels` pattern on {@link OpenAICompletionsCompat}). Present ⇒ the brain sends
      * `output_config: { effort }` plus the `effort-2025-11-24` beta header, clamping the requested
@@ -896,14 +910,14 @@ export interface AnthropicMessagesCompat {
      */
     effortLevels?: ThinkingLevel[];
     /**
-     * Whether the endpoint accepts `temperature` at all. CC 2.1.198 sends temperature only to a
+     * Whether the endpoint accepts `temperature` at all. The reference sends temperature only to a
      * legacy allowlist — Fable-5-class models NEVER receive it (400 risk), independent of thinking
      * state. Default true (existing models unchanged); `false` drops a caller temperature
      * unconditionally, not just under extended thinking.
      */
     supportsTemperature?: boolean;
     /**
-     * design/119 S4 (CC 2.1.198 `context_management` capability): when thinking is enabled, send
+     * design/119 S4 (`context_management` capability): when thinking is enabled, send
      * `context_management: { edits: [{ type: "clear_thinking_20251015", keep: "all" }] }` plus the
      * `context-management-2025-06-27` beta — an explicit opt-OUT of the server's default
      * thinking-clearing, preserving cross-turn reasoning continuity (what CC sends on first-party
@@ -912,7 +926,7 @@ export interface AnthropicMessagesCompat {
      */
     contextManagement?: boolean;
     /**
-     * design/119 S4 (CC 2.1.198): attach the `interleaved-thinking-2025-05-14` beta on tool-enabled
+     * design/119 S4: attach the `interleaved-thinking-2025-05-14` beta on tool-enabled
      * requests with thinking on (thinking blocks may interleave with tool_use). Declare per endpoint;
      * absent = no beta (pre-119 behavior; a deployment could already do this via static `headers`).
      */
@@ -924,7 +938,9 @@ export interface Model<TApi extends Api = Api> {
     api: TApi;
     provider: Provider;
     baseUrl: string;
-    reasoning: boolean;
+    /** Declares reasoning (thinking keys): `true` / `false`, absent = not declared. Read only through `capabilityOf`
+     *  (`brain/model-capability.ts`), which also says what an undeclared capability means. */
+    reasoning?: boolean;
     /**
      * design/111 — this model's DEFAULT thinking level (per-model preset). The thinking-resolution chain is
      * `spec.thinking ?? role.thinking ?? model.defaultThinking` (prepare-task) — a caller/role still overrides, but
@@ -940,7 +956,8 @@ export interface Model<TApi extends Api = Api> {
      * Missing keys use provider defaults. null marks a level as unsupported.
      */
     thinkingLevelMap?: ThinkingLevelMap;
-    input: ("text" | "image")[];
+    /** Declares image input: a list with `"image"` = on, without = off, absent = not declared (same reader as `reasoning`). */
+    input?: ("text" | "image")[];
     cost?: {
         input: number;
         output: number;
@@ -957,7 +974,7 @@ export interface Model<TApi extends Api = Api> {
     /**
      * Optional AUTOCOMPACT window — the window the compaction trigger and the clearStale frontier
      * are derived from when it differs from the physical request window (dual-window semantics).
-     * CC 2.1.207 posture: its 1M sonnet keeps the PHYSICAL window at 1M while a per-model dynamic
+     * The reference's posture: its 1M sonnet keeps the PHYSICAL window at 1M while a per-model dynamic
      * config lowers only the autocompact window to 967000, so the reactive trigger lands at 934000
      * (= 967000 − 33000); a single window value cannot express both. Consumed by the trigger-side
      * geometry only (`editBudget`/`sanitizeCompactionSettings`/`shouldCompact` window); the request
@@ -996,13 +1013,13 @@ export interface Model<TApi extends Api = Api> {
     /** Extra request HEADERS merged into the provider call. Cannot override auth / content-type / version. */
     headers?: Record<string, string>;
     /**
-     * design/119 S3 (CC 2.1.198 parity): model-declared system-prompt guidance sections, appended to
-     * the assembled system prompt. This is the declarative home for per-model behavioral patches (CC
-     * ships Fable-5 "mitigations" baked behind model-name checks; sema keeps the MECHANISM generic —
-     * any Model can carry guidance — and the CONTENT as preset data, zero model-name matching in core).
-     * Each entry is one section; joined with blank lines.
+     * The prompt traits this model has: the reference's capability names that gate prompt text (`PROMPT_TRAITS`), its
+     * bundle names (`PROMPT_TRAIT_BUNDLES`, expanded to their members), or a deployment's own `x-<namespace>-<name>`.
+     * The prompt catalog and every overlay's `when.traits` select on them; the engine never derives them from `id`. An
+     * EXACT set — nothing is added to what it lists (declare `lean_prompt` for the lean shape). Absent ⇒
+     * `["lean_prompt"]`. A name that is none of these refuses the task (`config.prompt_trait_unknown`).
      */
-    promptGuidance?: string[];
+    promptTraits?: readonly PromptTraitName[];
     /** Compatibility overrides for OpenAI-compatible APIs. If not set, auto-detected from baseUrl. */
     compat?: TApi extends "openai-completions" ? OpenAICompletionsCompat : TApi extends "openai-responses" ? OpenAIResponsesCompat : TApi extends "anthropic-messages" ? AnthropicMessagesCompat : never;
 }

package/dist/engine/llm/validation.d.ts

@@ -1,7 +1,10 @@
 import type { Tool, ToolCall } from "./types.js";
 /** Finds the target tool and validates/coerces a model-emitted tool call. */
 export declare function validateToolCall(tools: Tool[], toolCall: ToolCall): unknown;
-/** VENDORED EDIT (design/115 P0): resolve canonical tool names first, then legacy aliases. */
+/** The dispatcher's name resolution over one tool list, indexed once (for a caller resolving many names over the same list):
+ *  canonical names first, then aliases (design/115 P0 order) — the first tool carrying a name, or an alias, owns it. */
+export declare function toolNameIndex<T extends Tool>(tools: readonly T[] | undefined): (name: string) => T | undefined;
+/** VENDORED EDIT (design/115 P0): resolve canonical tool names first, then legacy aliases ({@link toolNameIndex} for one name). */
 export declare function findToolByName<T extends Tool>(tools: readonly T[] | undefined, name: string): T | undefined;
 /** Validates tool arguments against TypeBox or plain JSON-schema parameters. */
 export declare function validateToolArguments(tool: Tool, toolCall: ToolCall): unknown;

package/dist/engine/llm/validation.js

@@ -378,8 +378,20 @@ export function validateToolCall(tools, toolCall) {
     }
     return validateToolArguments(tool, toolCall);
 }
+export function toolNameIndex(tools) {
+    const byName = new Map();
+    const byAlias = new Map();
+    for (const t of tools ?? []) {
+        if (!byName.has(t.name))
+            byName.set(t.name, t);
+        for (const a of t.aliases ?? [])
+            if (!byAlias.has(a))
+                byAlias.set(a, t);
+    }
+    return (name) => byName.get(name) ?? byAlias.get(name);
+}
 export function findToolByName(tools, name) {
-    return tools?.find((t) => t.name === name) ?? tools?.find((t) => t.aliases?.includes(name));
+    return toolNameIndex(tools)(name);
 }
 export function validateToolArguments(tool, toolCall) {
     const args = structuredClone(toolCall.arguments);

package/dist/engine/loop/agent-loop.d.ts

@@ -61,7 +61,7 @@ export type LoopTerminalReason =
  *  loop ended cleanly at a manufactured boundary, no reconcile owed), and which consult caught
  *  it is timing, not semantics. */
  | "stop_requested"
-/** RB-206 (CC 220 counterpart @400176-400230, `Bxs` @397652-397674 buckets it
+/** RB-206 (the reference buckets it
  *  with budget_exhausted/api_error/model_error/turn_setup_failed, explicitly NOT `"completed"`): every
  *  tool call in the turn was dropped as malformed AND the bounded `malformed_tool_use_retry` nudge
  *  budget is used up — the model believes it acted, nothing ran, and there is no more recovery budget
@@ -154,11 +154,33 @@ type ExecutedToolCallBatch = {
     messages: ToolResultMessage[];
     terminate: boolean;
 };
+/**
+ * ONE call through the loop's per-call pipeline — announced, prepared (the gate included), executed through the execution
+ * seat, finalized, closed. The sequential lane runs each call through it and adds the call's tool-result message; a host's
+ * own call (`AgentHarness.callTool`) runs it with no model message and adds nothing. The partitioned and streaming lanes run
+ * the same steps in two phases.
+ */
+export declare function runToolCall(currentContext: AgentContext, assistantMessage: AssistantMessage | undefined, toolCall: AgentToolCall, config: AgentLoopConfig, signal: AbortSignal | undefined, emit: AgentEventSink): Promise<{
+    finalized: FinalizedToolCallOutcome;
+    halt?: HaltRemainingDirective;
+}>;
+/**
+ * Partition rule: a call is batch-safe ONLY if its arguments
+ * VALIDATE against the tool's schema (CC `safeParse` — a malformed call never rides a parallel batch;
+ * it stays a singleton and surfaces its validation error at execution) AND the tool/hook opts in.
+ * The hook sees the validated+coerced args — same as CC handing `parsed.data` to `isConcurrencySafe`.
+ */
+export declare function isBatchSafeToolCall(tool: AgentTool | undefined, toolCall: AgentToolCall): boolean;
 /** An executed call's raw outcome, before (and, from {@link finalizeToolOutcome}, after) the post-execution half. */
 export type ExecutedToolCallOutcome = {
     result: AgentToolResult<unknown>;
     isError: boolean;
 };
+type FinalizedToolCallOutcome = {
+    toolCall: AgentToolCall;
+    result: AgentToolResult<unknown>;
+    isError: boolean;
+};
 /**
  * THE reading a value gets on its way to becoming a call's arguments: the tool's own preparation (`prepareArguments` —
  * a default filled in, an alias folded), then the schema's coercions ({@link validateToolArguments}). The loop reads the

package/dist/engine/loop/agent-loop.js

@@ -118,11 +118,12 @@ async function settleTrailingBatchTurn(state, signal, emit, settle) {
         terminalEmitted = ended;
     }
     else if (!ended) {
+        state.hasMoreToolCalls = !batch.terminate;
         const boundary = { message: tail, toolResults: batch.messages, context: state.context, newMessages: state.newMessages };
-        adoptNextTurnSnapshot(state, await state.config.prepareNextTurn?.(boundary));
+        adoptNextTurnSnapshot(state, await state.config.prepareNextTurn?.({ ...boundary, continues: state.hasMoreToolCalls }));
         ended = (await state.config.shouldStopAfterTurn?.(boundary)) === true || signal?.aborted === true;
         if (!ended)
-            state.pendingMessages.push(...((await state.config.getSteeringMessages?.()) || []));
+            state.pendingMessages.push(...((await state.config.getSteeringMessages?.(state.hasMoreToolCalls)) || []));
     }
     settle.report({ assistantMessage: tail, settled: batch.messages.length, aborted: ended });
     if (ended && !terminalEmitted)
@@ -242,7 +243,7 @@ async function createLoopState(context, config, newMessages) {
         config,
         newMessages,
         firstTurn: true,
-        pendingMessages: (await config.getSteeringMessages?.()) || [],
+        pendingMessages: (await config.getSteeringMessages?.(true)) || [],
         hasMoreToolCalls: true,
         truncatedOutputContinues: 0,
         staticReasoningCutRecoveries: context.messages.filter((m) => m.role === "assistant" && m.staticReasoningCut === true).length,
@@ -258,7 +259,7 @@ async function runLoop(state, signal, emit, streamFn, runtime, trace) {
             const followUpMessages = (await state.config.getFollowUpMessages?.()) || [];
             if (followUpMessages.length === 0) {
                 if ((state.config.pendingInjectionCount?.() ?? 0) > 0) {
-                    state.pendingMessages = (await state.config.getSteeringMessages?.()) || [];
+                    state.pendingMessages = (await state.config.getSteeringMessages?.(false)) || [];
                     if (state.pendingMessages.length > 0) {
                         trace?.({ kind: "continue", reason: "steer_injected" });
                     }
@@ -448,7 +449,7 @@ async function runTurnPhases(state, signal, turnController, publishSeat, retract
             retractSeat();
             state.degenerateContinues++;
             await emit({ type: "turn_end", message, toolResults: [] });
-            const drained = (await state.config.getSteeringMessages?.()) || [];
+            const drained = (await state.config.getSteeringMessages?.(false)) || [];
             state.pendingMessages = drained.length > 0 ? drained : [createDegenerateRecoveryNudge()];
             return { kind: "ran", recovered: "degenerate_output_recovery" };
         }
@@ -493,7 +494,7 @@ async function runTurnPhases(state, signal, turnController, publishSeat, retract
         context: state.context,
         newMessages: state.newMessages,
     };
-    const nextTurnSnapshot = await state.config.prepareNextTurn?.(nextTurnContext);
+    const nextTurnSnapshot = await state.config.prepareNextTurn?.({ ...nextTurnContext, continues: state.hasMoreToolCalls });
     adoptNextTurnSnapshot(state, nextTurnSnapshot);
     if (await state.config.shouldStopAfterTurn?.({
         message,
@@ -504,7 +505,7 @@ async function runTurnPhases(state, signal, turnController, publishSeat, retract
         await emit({ type: "agent_end", messages: state.newMessages });
         return { kind: "terminal", reason: "stop_requested" };
     }
-    state.pendingMessages = (await state.config.getSteeringMessages?.()) || [];
+    state.pendingMessages = (await state.config.getSteeringMessages?.(state.hasMoreToolCalls)) || [];
     const truncated = state.config.recovery?.truncatedOutput;
     if (message.stopReason === "length") {
         if (truncated && toolCalls.length === 0 && state.pendingMessages.length === 0) {
@@ -653,6 +654,7 @@ async function settleInterruptedTurn(state, message, executor, committedResults,
         toolResults,
         context: state.context,
         newMessages: state.newMessages,
+        continues: state.hasMoreToolCalls,
     });
     adoptNextTurnSnapshot(state, nextTurnSnapshot);
     if (await state.config.shouldStopAfterTurn?.({
@@ -664,7 +666,7 @@ async function settleInterruptedTurn(state, message, executor, committedResults,
         await emit({ type: "agent_end", messages: state.newMessages });
         return { kind: "terminal", reason: "stop_requested" };
     }
-    state.pendingMessages = (await state.config.getSteeringMessages?.()) || [];
+    state.pendingMessages = (await state.config.getSteeringMessages?.(state.hasMoreToolCalls)) || [];
     return { kind: "ran" };
 }
 async function streamAssistantResponse(context, config, signal, emit, streamFn, runtime, executor, staticReasoningCutDowngrade) {
@@ -800,27 +802,7 @@ async function executeToolCallsSequential(currentContext, assistantMessage, tool
     const messages = [];
     for (let i = 0; i < toolCalls.length; i++) {
         const toolCall = toolCalls[i];
-        await emit({
-            type: "tool_execution_start",
-            toolCallId: toolCall.id,
-            toolName: toolCall.name,
-            args: toolCall.arguments,
-        });
-        const preparation = await prepareToolCall(currentContext, assistantMessage, toolCall, config, signal);
-        let finalized;
-        let halt;
-        if (preparation.kind === "immediate") {
-            finalized = {
-                toolCall,
-                result: preparation.result,
-                isError: preparation.isError,
-            };
-            halt = preparation.halt;
-        }
-        else {
-            finalized = await executePreparedWithDisclosure(currentContext, assistantMessage, preparation, config, signal, emit);
-        }
-        await emitToolExecutionEnd(finalized, emit);
+        const { finalized, halt } = await runToolCall(currentContext, assistantMessage, toolCall, config, signal, emit);
         const toolResultMessage = createToolResultMessage(finalized);
         await emitToolResultMessage(toolResultMessage, emit);
         finalizedCalls.push(finalized);
@@ -844,6 +826,15 @@ async function executeToolCallsSequential(currentContext, assistantMessage, tool
         terminate: shouldTerminateToolBatch(finalizedCalls),
     };
 }
+export async function runToolCall(currentContext, assistantMessage, toolCall, config, signal, emit) {
+    await emit({ type: "tool_execution_start", toolCallId: toolCall.id, toolName: toolCall.name, args: toolCall.arguments });
+    const preparation = await prepareToolCall(currentContext, assistantMessage, toolCall, config, signal);
+    const finalized = preparation.kind === "immediate"
+        ? { toolCall, result: preparation.result, isError: preparation.isError }
+        : await executePreparedWithDisclosure(currentContext, assistantMessage, preparation, config, signal, emit);
+    await emitToolExecutionEnd(finalized, emit);
+    return { finalized, ...(preparation.kind === "immediate" && preparation.halt !== undefined ? { halt: preparation.halt } : {}) };
+}
 async function settleHaltedToolCall(toolCall, halt, emit) {
     await emit({
         type: "tool_execution_start",
@@ -885,7 +876,7 @@ function isCallConcurrencySafe(tool, args) {
         return false;
     }
 }
-function isBatchSafeToolCall(tool, toolCall) {
+export function isBatchSafeToolCall(tool, toolCall) {
     if (!tool)
         return false;
     let args;
@@ -1106,7 +1097,7 @@ class StreamToolExecutor {
                 return;
             }
             entry.prepared = preparation;
-            entry.executed = await executePreparedToolCall(preparation, this.signal, this.emit, this.config.abortResultDetails, (error) => this.retainCancellation(error));
+            entry.executed = await executePreparedToolCall(preparation, this.signal, this.emit, this.config.executeTool, this.config.abortResultDetails, (error) => this.retainCancellation(error));
         }
         catch (error) {
             if (isAbortSemanticsError(error))
@@ -1393,7 +1384,7 @@ async function prepareToolCall(currentContext, assistantMessage, toolCall, confi
         };
     }
 }
-async function executePreparedToolCall(prepared, signal, emit, abortResultDetails, onLateCancellation) {
+async function executePreparedToolCall(prepared, signal, emit, executeTool, abortResultDetails, onLateCancellation) {
     const updateEvents = [];
     let acceptingUpdates = true;
     if (signal?.aborted) {
@@ -1402,7 +1393,7 @@ async function executePreparedToolCall(prepared, signal, emit, abortResultDetail
     const work = (async () => {
         let outcome;
         try {
-            const result = await prepared.tool.execute(prepared.toolCall.id, prepared.args, signal, (partialResult) => {
+            const body = () => prepared.tool.execute(prepared.toolCall.id, prepared.args, signal, (partialResult) => {
                 if (!acceptingUpdates) {
                     return;
                 }
@@ -1425,6 +1416,7 @@ async function executePreparedToolCall(prepared, signal, emit, abortResultDetail
                 });
                 updateEvents.push(delivery);
             });
+            const result = executeTool !== undefined ? await executeTool({ toolCall: prepared.toolCall, tool: prepared.tool, args: prepared.args }, body, signal) : await body();
             outcome = { result, isError: result.isError === true };
         }
         catch (error) {
@@ -1505,7 +1497,7 @@ function raiseFatalCancellation(executor) {
 async function executePreparedWithDisclosure(currentContext, assistantMessage, prepared, config, signal, emit) {
     let executed;
     try {
-        executed = await executePreparedToolCall(prepared, signal, emit, config.abortResultDetails);
+        executed = await executePreparedToolCall(prepared, signal, emit, config.executeTool, config.abortResultDetails);
     }
     catch (error) {
         if (isAbortSemanticsError(error))

package/dist/engine/loop/types.d.ts

@@ -127,9 +127,9 @@ export interface AfterToolCallResult {
 }
 /** Context passed to `beforeToolCall`. */
 export interface BeforeToolCallContext {
-    /** The assistant message that requested the tool call. */
-    assistantMessage: AssistantMessage;
-    /** The raw tool call block from `assistantMessage.content`. */
+    /** The assistant message that requested the tool call — absent for a host's own call (an extension's `$.tool.call`), which no model message carried. */
+    assistantMessage?: AssistantMessage;
+    /** The raw tool call block (from `assistantMessage.content` when a model message carried it). */
     toolCall: AgentToolCall;
     /** Validated tool arguments for the target tool schema. */
     args: unknown;
@@ -142,9 +142,9 @@ export interface BeforeToolCallContext {
 }
 /** Context passed to `afterToolCall`. */
 export interface AfterToolCallContext {
-    /** The assistant message that requested the tool call. */
-    assistantMessage: AssistantMessage;
-    /** The raw tool call block from `assistantMessage.content`. */
+    /** The assistant message that requested the tool call — absent for a host's own call (an extension's `$.tool.call`), which no model message carried. */
+    assistantMessage?: AssistantMessage;
+    /** The raw tool call block (from `assistantMessage.content` when a model message carried it). */
     toolCall: AgentToolCall;
     /** Validated tool arguments for the target tool schema. */
     args: unknown;
@@ -176,6 +176,8 @@ export interface AgentLoopTurnUpdate {
     thinkingLevel?: ThinkingLevel;
 }
 export interface PrepareNextTurnContext extends ShouldStopAfterTurnContext {
+    /** `hasMoreToolCalls`: the turn's tool results go back to the model as the next request (its batch neither ended the run nor was cut by an interjection; a recovery nudge is not one). */
+    continues: boolean;
 }
 /**
  * Prompt-too-long recovery seam (design/118 ④b, the CC reactive-compact chain adapted to sema's
@@ -214,8 +216,8 @@ export interface LoopPromptTooLongRecovery {
     maxRetries?: number;
     /**
      * M1 (docs/PARITY-CONTEXT-TRANSACTIONS-2026-07-10 §4): withhold the failed assistant's
-     * message_start/message_end stream events while a recovery attempt is pending — CC 198 holds
-     * these errors inside its stream decoder (`claude-cli-2.1.198.pretty.js:473371-473374`) and only
+     * message_start/message_end stream events while a recovery attempt is pending — the reference holds
+     * these errors inside its stream decoder and only
      * leaks them once recovery's outcome is known. Recovery succeeded ⇒ the failure stays invisible
      * to event consumers; failed/declined ⇒ the events leak at that point (terminal truth unchanged).
      * Default true (CC-aligned). `false` restores the pre-M1 live leak of the interim error.
@@ -239,7 +241,7 @@ export interface LoopTruncatedOutputRecovery {
     maxContinues?: number;
 }
 /**
- * Malformed-tool-use retry (design/119 S2, CC 2.1.198 :473745-473785). A turn that stops with
+ * Malformed-tool-use retry (design/119 S2). A turn that stops with
  * `toolUse` but carries ZERO parseable tool calls (the brain dropped truncated/invalid ones) used to
  * end the run silently mid-task. When enabled, inject a synthetic retry nudge and run another turn,
  * up to `maxRetries` per run (CC: once). Absent ⇒ OFF (pre-S2 behavior).
@@ -249,7 +251,7 @@ export interface LoopMalformedToolUseRecovery {
     maxRetries?: number;
 }
 /**
- * Thinking-only retry (design/119 S2, CC 2.1.198 :473786-473825 — the adaptive-thinking era
+ * Thinking-only retry (design/119 S2 — the adaptive-thinking era
  * companion). A turn that stops normally with thinking block(s) but NO visible text and NO tool
  * calls used to end the run as a silent empty success. When enabled, inject a "respond with visible
  * output" nudge and run another turn, up to `maxRetries` per run (CC: once). Absent ⇒ OFF.
@@ -345,7 +347,7 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      */
     stallTimeoutsPerCall?: () => import("../llm/types.js").StallTimeouts | undefined;
     /**
-     * design/120 P1: concurrency cap inside a parallel tool batch. Default 10 (CC 198's production
+     * design/120 P1: concurrency cap inside a parallel tool batch. Default 10 (the reference's production
      * default — its knob is the CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY env; sema takes config).
      */
     maxToolConcurrency?: number;
@@ -473,11 +475,11 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * If messages are returned, they are added to the context before the next LLM call.
      * Tool calls from the current assistant message are not skipped.
      *
-     * Use this for "steering" the agent while it's working.
+     * Use this for "steering" the agent while it's working. `continuing`: {@link PrepareNextTurnContext.continues} here.
      *
      * Contract: must not throw or reject. Return [] when no steering messages are available.
      */
-    getSteeringMessages?: () => Promise<AgentMessage[]>;
+    getSteeringMessages?: (continuing: boolean) => Promise<AgentMessage[]>;
     /**
      * Returns follow-up messages to process after the agent would otherwise stop.
      *
@@ -520,7 +522,7 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
     /**
      * design/373 S1 — the FINAL COMMIT POINT's synchronous double-check: how many queued injection
      * frames a boundary drain could deliver right now (steer + follow-up, excluding frames a live
-     * hold or an unwinding run would refuse to drain). Consulted SYNCHRONOUSLY after the follow-up
+     * hold, an unwinding run or the advisory rule would refuse to drain). Consulted SYNCHRONOUSLY after the follow-up
      * drain (and stop gate) answered empty, with zero awaits between the check and the terminal
      * commit — a frame that arrived during the stop gate's await window is therefore served by this
      * run instead of being stranded behind an already-decided terminal. Absent ⇒ the pre-373 commit
@@ -562,6 +564,16 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * signal re-check, which has always minted its abort result with no details.
      */
     abortResultDetails?: () => Record<string, unknown> | undefined;
+    /**
+     * The host's station around every tool execution, between the gate's allow and the body: `run` runs the body as the loop
+     * would (at most once), and what the station returns is the result the loop finalizes — it may answer without running it,
+     * and honors `signal`. Absent ⇒ the loop runs the body itself.
+     */
+    executeTool?: (call: {
+        readonly toolCall: AgentToolCall;
+        readonly tool: AgentTool;
+        readonly args: unknown;
+    }, run: () => Promise<AgentToolResult<unknown>>, signal: AbortSignal | undefined) => Promise<AgentToolResult<unknown>>;
     /**
      * Fault seat for a THROWING {@link AgentTool.validateInput}: the loop reads the throw as "no
      * verdict" (the call proceeds to the gate as if the tool had no validator) and reports the fault
@@ -759,17 +771,17 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = unk
      * - "parallel": this tool can execute concurrently with other tool calls.
      *
      * If omitted, the tool is treated as NOT concurrency-safe unless its input-level
-     * `isConcurrencySafe` hook opts a call in (fail-closed; CC 2.1.206 TOOL_DEFAULTS parity).
+     * `isConcurrencySafe` hook opts a call in (fail-closed).
      */
     executionMode?: ToolExecutionMode;
     /**
-     * MCP server self-declared result-size threshold (CC 198 `_meta["anthropic/maxResultSizeChars"]`,
-     * pretty.js:320015/:320061 — consumer caps at 500K). Set by the MCP materializer when the server
+     * MCP server self-declared result-size threshold (`_meta["anthropic/maxResultSizeChars"]`,
+     * consumer caps at 500K). Set by the MCP materializer when the server
      * declares it; consulted by the offload mount in prepare-task. Absent on non-MCP tools.
      */
     mcpMaxResultSizeChars?: number;
     /**
-     * RB-400-a — MCP server-declared inline pin (CC 220 `_meta["anthropic/alwaysLoad"]`): set by the
+     * RB-400-a — MCP server-declared inline pin (`_meta["anthropic/alwaysLoad"]`): set by the
      * MCP materializer when the server's tools/list entry declares it; prepare-task folds these names
      * into the defer classification's exemption set, ahead of the MCP constant-defer arm — the
      * server's own channel for keeping one tool's full schema inlined. Absent on non-MCP tools.
@@ -803,7 +815,7 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = unk
      * partitioner for every tool WITHOUT an explicit `executionMode:"parallel"` (a statically-parallel
      * tool needs no refinement); `true` = treat THIS CALL as concurrency-safe. A throw = false
      * (fail-closed, CC same). The partitioner validates the call's args against the tool schema FIRST
-     * (schema-invalid ⇒ unsafe, CC 206 safeParse parity) and hands the hook the validated+coerced
+     * (schema-invalid ⇒ unsafe) and hands the hook the validated+coerced
      * args — still treat defensively (a direct caller may pass raw args). Omitted ⇒ the static mode stands.
      */
     isConcurrencySafe?: (args: unknown) => boolean;

package/dist/engine/lsp/node-lsp-manager.d.ts

@@ -127,12 +127,12 @@ export declare class NodeLspManager implements LspServerManager {
 }
 /** Resolve a file path to a languageId via its extension (undefined = no mapping → degrade). */
 export declare function languageFor(filePath: string): string | undefined;
-/** CC 2.1.220's LSP file cap — single-sourced in core (`src/core/lsp.ts`), where the tool-layer check
+/** The LSP file cap — single-sourced in core (`src/core/lsp.ts`), where the tool-layer check
  *  enforces it model-visibly; re-exported here so engine-path importers keep working. */
 export { MAX_LSP_FILE_BYTES } from "../../core/lsp.js";
 /**
  * RB-232: the local default {@link LspReadText}, hardened with a stat-first precondition (CC
- * 2.1.220 validateInput does the same before ever reading — "Path is not a file", (pretty220.js:474700, historical; not relocated in 250 — see cc-250 anchors)).
+ * the reference's validateInput does the same before ever reading — "Path is not a file").
  * The stat check is the LOAD-BEARING part, do not "simplify" it away: a plain `readFile` on a FIFO/socket
  * blocks forever on the FIRST read and PINS a libuv threadpool thread (default pool = 4) for the process
  * lifetime — measured: `readFile(fifo, { signal })` with an abort fired at 2s was still unsettled at 10s,

package/dist/engine/session/memory-repo.d.ts

@@ -1,22 +1,28 @@
-import { type Session, type SessionForkOptions, type SessionMetadata, type SessionRepo, type SessionTreeEntry } from "../harness/types.js";
-export declare class InMemorySessionRepo implements SessionRepo<SessionMetadata, {
-    id?: string;
-}> {
+import { type Session, type SessionCreateOptions, type SessionForkOptions, type SessionHead, type SessionMetadata, type SessionRepo, type SessionRow, type SessionTreeEntry } from "../harness/types.js";
+export declare class InMemorySessionRepo implements SessionRepo<SessionMetadata, SessionCreateOptions> {
     private sessions;
-    create(options?: {
-        id?: string;
-    }): Promise<Session>;
+    /** Each row's last touch (epoch ms). */
+    private touched;
+    create(options?: SessionCreateOptions): Promise<Session>;
     open(metadata: SessionMetadata): Promise<Session>;
-    list(): Promise<SessionMetadata[]>;
+    /** The row's head off the one session object that IS the row: every cell comes from that object, so a delete and re-create of the
+     *  id while this reads cannot mix two generations. */
+    headOf(sessionId: string): Promise<SessionHead | undefined>;
+    /** Every row, with its last {@link touch} as its activity time where it has one. This repo hands its sessions' storages out and never
+     *  sees their writes (an entry's own `timestamp` is the writer's data, not the time of the write), so a row never touched carries none
+     *  and a reader takes its `createdAt`. */
+    list(): Promise<SessionRow[]>;
+    /** Record activity on the row now (a missing row: nothing to record). The time lives and dies with the row: `delete` drops it. */
+    touch(sessionId: string): Promise<void>;
     delete(metadata: SessionMetadata): Promise<void>;
-    fork(sourceMetadata: SessionMetadata, options: SessionForkOptions): Promise<Session>;
+    fork(sourceMetadata: SessionMetadata, options: SessionForkOptions & SessionCreateOptions): Promise<Session>;
     /** 2c session-sync: the FULL log for export. InMemory holds everything (no F3 floor), so
      *  `getEntries()` IS the full oldest-first log with `id`/`parentId` verbatim. */
     exportEntries(sessionId: string): Promise<SessionTreeEntry[]>;
     /** 2c session-sync: import a verbatim log into `sessionId`. The single invariant gate runs first
-     *  ({@link validateEntriesForImport}, fail-closed); `owner` is a durable multi-tenant concept that the local
-     *  in-memory backend has no field for, so it is accepted but unused here. design/171: the operator's
-     *  trusted-import flag is forwarded to the gate that persists — see SessionRepo.importEntries. */
+     *  ({@link validateEntriesForImport}, fail-closed); a new row records `owner`, an existing row keeps its metadata whole.
+     *  design/171: the operator's trusted-import flag is forwarded to the gate that persists — see
+     *  SessionRepo.importEntries. */
     importEntries(sessionId: string, owner: string | undefined, entries: SessionTreeEntry[], options?: {
         preserveActorAssertions?: boolean;
     }): Promise<void>;