@sema-agent/core 7.55.0 → 7.56.0

package/dist/engine/compaction/compaction.js

@@ -7,6 +7,7 @@ import { budgetInvokedSkillsRetention, computeFileLists, createFileOps, extractF
 import { ENGINE_AUTHORITY_ENVELOPE_TAGS, sanitizeUntrustedText } from "../../core/untrusted-text.js";
 import { sliceHeadSafe } from "../../core/surrogate-safe-slice.js";
 import { thrownText } from "../../core/thrown-value.js";
+import { capabilityHeld } from "../../brain/model-capability.js";
 function safeJsonStringify(value) {
     try {
         return JSON.stringify(value) ?? "undefined";
@@ -576,7 +577,7 @@ First, inside an <analysis>...</analysis> block, note what is new since the prev
 Keep each section concise. Preserve exact file paths, function names, and error messages.`;
 function createSummarizationOptions(model, maxTokens, apiKey, headers, signal, thinkingLevel) {
     const options = { maxTokens, signal, apiKey, headers };
-    if (model.reasoning && thinkingLevel) {
+    if (capabilityHeld(model, "reasoning") && thinkingLevel) {
         options.reasoning = thinkingLevel;
     }
     return options;
@@ -868,7 +869,7 @@ async function summarizeWithLengthRecovery(label, model, context, baseMaxTokens,
         ? Math.max(baseMaxTokens, model.contextWindow - estimateSummarizationInputTokens(context, cpt) - SUMMARY_WINDOW_MARGIN)
         : Number.POSITIVE_INFINITY;
     const cap = Math.min(modelCap, windowCap);
-    let maxTokens = Math.min(cap, model.reasoning ? Math.max(baseMaxTokens, SUMMARY_REASONING_FLOOR) : baseMaxTokens);
+    let maxTokens = Math.min(cap, capabilityHeld(model, "reasoning") ? Math.max(baseMaxTokens, SUMMARY_REASONING_FLOOR) : baseMaxTokens);
     for (let attempt = 0;; attempt++) {
         const canEscalate = attempt < SUMMARY_MAX_ESCALATIONS && maxTokens < cap;
         const response = await completeSummarization(model, context, createSummarizationOptions(model, maxTokens, apiKey, headers, signal, thinkingLevel), streamFn, runtime);

package/dist/engine/execution-env/node-execution-env.d.ts

@@ -88,9 +88,13 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
     /** `ExecutionEnv.cdPath` = the `CDPATH` the shell child receives, read LIVE off the same merge each exec gets (never the
      *  engine process's own environment): its entries, `[]` when the child gets none. Residual: a per-exec `env.CDPATH`. */
     get cdPath(): readonly string[];
-    /** The environment the next shell child would receive, for a READ (the scrub seat is a no-op: a read reports nothing).
-     *  `undefined` when no child would be spawned at all — the policy is refused against the own credentials declared
-     *  since construction, and every spawn throws that reason — so a reader sees "the child gets none", never a throw. */
+    /** `ExecutionEnv.withheldEnv` = what the same merge withholds from the shell child (an entry `shellEnv` re-supplies is
+     *  no loss), read LIVE; `[]` when no child would be spawned at all. Residual: a per-exec `env` re-supplying one. */
+    get withheldEnv(): readonly SecretEnvFinding[];
+    /** The environment the next shell child would receive, for a READ (the scrub seat is the reader's collector or a
+     *  no-op: a read announces nothing). `undefined` when no child would be spawned at all — the policy is refused against
+     *  the own credentials declared since construction, and every spawn throws that reason — so a reader sees "the child
+     *  gets none", never a throw. */
     private childEnvForRead;
     private shellPath?;
     private shellEnv?;

package/dist/engine/execution-env/node-execution-env.js

@@ -116,6 +116,10 @@ function toFileError(error, path) {
                 return new FileError("not_directory", message, path, cause);
             case "EISDIR":
                 return new FileError("is_directory", message, path, cause);
+            case "ENAMETOOLONG":
+                if (path !== undefined && path.split(/[\\/]/).some((part) => Buffer.byteLength(part, "utf8") > 255))
+                    return new FileError("name_too_long", message, path, cause);
+                break;
             case "EINVAL":
                 return new FileError("invalid", message, path, cause);
             default:
@@ -321,10 +325,15 @@ export class NodeExecutionEnv {
         const value = this.childEnvForRead()?.CDPATH;
         return value === undefined || value === "" ? [] : value.split(":");
     }
-    childEnvForRead() {
+    get withheldEnv() {
+        let withheld = [];
+        this.childEnvForRead((f) => (withheld = f));
+        return withheld;
+    }
+    childEnvForRead(collect = () => { }) {
         if (inheritEnvPolicyProblem(this.inheritEnv) !== undefined)
             return undefined;
-        return getShellEnv(this.inheritEnv, this.shellEnv, undefined, () => { });
+        return getShellEnv(this.inheritEnv, this.shellEnv, undefined, collect);
     }
     shellPath;
     shellEnv;

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

@@ -1,6 +1,6 @@
 import type { ActorAssertion, AssistantMessage, ImageContent, Model, TextContent, UserMessage, UserMessageAttachment } from "../llm/index.js";
 import { type ToolTurnRepair } from "../llm/index.js";
-import { type ExecutedToolCallOutcome } from "../loop/agent-loop.js";
+import { runToolCall, type ExecutedToolCallOutcome } from "../loop/agent-loop.js";
 import type { HaltRemainingDirective } from "../loop/types.js";
 import type { AgentMessage, AgentTool, AgentToolCall, LoopMalformedToolUseRecovery, LoopThinkingOnlyRecovery, LoopTruncatedOutputRecovery, QueueMode, ThinkingLevel } from "../loop/types.js";
 import { type EngineSegment } from "../../core/untrusted-text.js";
@@ -174,6 +174,8 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     private readonly seatCutSources;
     private trailingBatchEndedOn?;
     private turnCutConsumed?;
+    private readonly committedEntryIds;
+    private readonly answerSources;
     /** backlog #389 — one-way latch set by {@link abort}. Read by `drainQueuedMessages`: no boundary may
      *  hand a queued frame to the model once the run is unwinding, and — crucially — none may SPLICE one
      *  out of the queue either (that would delete the terminal undrained account the abort path owes it). */
@@ -308,6 +310,8 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     private maxOutputTokensPerCall?;
     private stallTimeoutsPerCall?;
     private abortResultDetails?;
+    private executeTool?;
+    private activeRun?;
     private loopTrace?;
     private onToolInputValidationFault?;
     private onToolMediaRefused?;
@@ -509,6 +513,15 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
      *  the loop takes the run-terminal path and never reports that settlement, so the consumption is recorded here, the
      *  only point that can see the causation (synchronous, single-threaded). A LATER abort is the run's own ending. */
     private cutSeat;
+    /** The entry ids of the committed messages an answer `prompt()` returned was read from, in conversation order: the
+     *  final assistant message, or every member of the continuation chain merged into it (members never appended — an
+     *  empty failure — have no id). Bound to the returned object, so a prompt that rejects, or one overlapping another,
+     *  hands its caller nothing to misread. Empty for `undefined` (no answer, read from nothing); `undefined` when the
+     *  sources are not this harness's to state — an object it did not return, or an answer read from a message the
+     *  transcript held before the run began whose append this harness never saw. */
+    answerEntryIdsOf(answer: AssistantMessage | undefined): readonly string[] | undefined;
+    /** Record what an answer was read from (the append receipts of its source messages) and hand the answer back. */
+    private answeredFrom;
     /** The harness's statement of what this run's halt (and its stop siblings) did — {@link HaltConsumption}. Readable
      *  during the run and after `prompt()` settled (cleared by the NEXT prompt). */
     haltConsumption(): HaltConsumption;
@@ -550,6 +563,17 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     finalizeToolCall(toolCall: AgentToolCall, args: unknown, executed: ExecutedToolCallOutcome): Promise<ExecutedToolCallOutcome & {
         toolCall: AgentToolCall;
     }>;
+    /**
+     * A call the host makes while a run is running (an extension's `$.tool.call`): the loop's own per-call pipeline
+     * ({@link runToolCall}) under the run's config and current roster — announced, judged at the gate, executed through the
+     * execution seat, finalized and closed on the run's event stream — with no model message carrying it and nothing added
+     * to the transcript. `admit` reads the tool the name resolves to before anything is announced; its throw is the caller's.
+     * Throws when no run is running or the run mounts no tool of that name.
+     */
+    callTool(toolCall: AgentToolCall, signal: AbortSignal | undefined, admit: (tool: AgentTool) => void): Promise<Awaited<ReturnType<typeof runToolCall>>["finalized"]>;
+    /** Whether the loop would run this call beside others (`isBatchSafeToolCall`, the partitioner's own predicate) on the running
+     *  prompt's roster — false for a name it does not mount, and when no prompt is running. */
+    isBatchSafe(toolName: string, args: unknown): boolean;
     getModel(): Model;
     /** The ref that chose the CURRENT model — {@link getModel}'s companion (a word re-resolves, an object pins). */
     getModelRef(): import("../../core/model-seat.js").ModelRef;

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

@@ -1,5 +1,5 @@
-import { createAssistantMessageEventStream, ensureToolTurnInvariants, snapshotActorAssertion, stripEngineMetadata, userAttachmentOf } from "../llm/index.js";
-import { finalizeToolOutcome, runAgentLoop } from "../loop/agent-loop.js";
+import { createAssistantMessageEventStream, ensureToolTurnInvariants, findToolByName, snapshotActorAssertion, stripEngineMetadata, userAttachmentOf } from "../llm/index.js";
+import { finalizeToolOutcome, isBatchSafeToolCall, runAgentLoop, runToolCall } from "../loop/agent-loop.js";
 import { resolveAgentCoreStreamFn } from "../loop/runtime-deps.js";
 import { normalizeEngineSegments } from "../../core/untrusted-text.js";
 import { isCredentialHeaderName } from "../../core/secret-env.js";
@@ -208,6 +208,8 @@ export class AgentHarness {
     seatCutSources = new WeakMap();
     trailingBatchEndedOn;
     turnCutConsumed;
+    committedEntryIds = new WeakMap();
+    answerSources = new WeakMap();
     aborting = false;
     drainedPendingInjection = [];
     runAbortController;
@@ -295,6 +297,8 @@ export class AgentHarness {
     maxOutputTokensPerCall;
     stallTimeoutsPerCall;
     abortResultDetails;
+    executeTool;
+    activeRun;
     loopTrace;
     onToolInputValidationFault;
     onToolMediaRefused;
@@ -331,6 +335,7 @@ export class AgentHarness {
         this.maxOutputTokensPerCall = options.maxOutputTokensPerCall;
         this.stallTimeoutsPerCall = options.stallTimeoutsPerCall;
         this.abortResultDetails = options.abortResultDetails;
+        this.executeTool = options.executeTool;
         this.loopTrace = options.loopTrace;
         this.onToolInputValidationFault = options.onToolInputValidationFault;
         this.onToolMediaRefused = options.onToolMediaRefused;
@@ -650,6 +655,7 @@ export class AgentHarness {
             ...(this.maxOutputTokensPerCall !== undefined ? { maxTokensPerCall: this.maxOutputTokensPerCall } : {}),
             ...(this.stallTimeoutsPerCall !== undefined ? { stallTimeoutsPerCall: this.stallTimeoutsPerCall } : {}),
             ...(this.abortResultDetails !== undefined ? { abortResultDetails: this.abortResultDetails } : {}),
+            ...(this.executeTool !== undefined ? { executeTool: this.executeTool } : {}),
             ...(this.onToolInputValidationFault !== undefined ? { onToolInputValidationFault: this.onToolInputValidationFault } : {}),
             ...(this.onToolMediaRefused !== undefined ? { onToolMediaRefused: this.onToolMediaRefused } : {}),
             ...(this.resilience !== undefined ? { resilience: this.resilience } : {}),
@@ -834,6 +840,7 @@ export class AgentHarness {
             let entryId;
             if (!isEmptyFailureAssistant(event.message)) {
                 entryId = await this.session.appendMessage(event.message);
+                this.committedEntryIds.set(event.message, entryId);
                 this.settleInjectedFrame(event.message, entryId);
                 if (entryId !== undefined && event.message.role === "toolResult" && typeof event.message.toolCallId === "string") {
                     try {
@@ -943,9 +950,12 @@ export class AgentHarness {
         const setTurnState = (nextTurnState) => {
             activeTurnState = nextTurnState;
         };
+        const loopConfig = this.createLoopConfig(getTurnState, setTurnState, beforeResult?.systemPrompt);
+        const emitRunEvent = (event) => this.handleAgentEvent(event, abortController.signal);
+        this.activeRun = { config: loopConfig, context: () => this.createContext(getTurnState(), beforeResult?.systemPrompt), emit: emitRunEvent, signal: abortController.signal };
         const runResultPromise = (async () => {
             try {
-                return await runAgentLoop(takePrompts, this.createContext(turnState, beforeResult?.systemPrompt), this.createLoopConfig(getTurnState, setTurnState, beforeResult?.systemPrompt), (event) => this.handleAgentEvent(event, abortController.signal), abortController.signal, this.createStreamFn(getTurnState), undefined, this.loopTrace, {
+                return await runAgentLoop(takePrompts, this.createContext(turnState, beforeResult?.systemPrompt), loopConfig, emitRunEvent, abortController.signal, this.createStreamFn(getTurnState), undefined, this.loopTrace, {
                     ...(options?.settleUnansweredToolCalls !== undefined
                         ? {
                             settle: {
@@ -975,13 +985,14 @@ export class AgentHarness {
             for (let i = newMessages.length - 1; i >= 0; i--) {
                 const message = newMessages[i];
                 if (message.role === "assistant") {
-                    return mergeTruncatedOutputChain(newMessages, i);
+                    const answer = mergeTruncatedOutputChain(newMessages, i);
+                    return this.answeredFrom(answer.message, answer.members);
                 }
             }
             if (this.stopRequested || abortController.signal.aborted)
                 return undefined;
             if (this.trailingBatchEndedOn !== undefined)
-                return this.trailingBatchEndedOn;
+                return this.answeredFrom(this.trailingBatchEndedOn, [this.trailingBatchEndedOn]);
             throw new AgentHarnessError("invalid_state", "AgentHarness prompt completed without an assistant message");
         }
         finally {
@@ -990,6 +1001,7 @@ export class AgentHarness {
             }
             finally {
                 this.runAbortController = undefined;
+                this.activeRun = undefined;
             }
         }
     }
@@ -1145,6 +1157,21 @@ export class AgentHarness {
         if (runQuietBefore && this.runAbortController?.signal.aborted === true)
             this.turnCutConsumed = { source };
     }
+    answerEntryIdsOf(answer) {
+        return answer === undefined ? [] : this.answerSources.get(answer);
+    }
+    answeredFrom(answer, members) {
+        const ids = [];
+        for (const m of members) {
+            const id = this.committedEntryIds.get(m);
+            if (id !== undefined)
+                ids.push(id);
+            else if (this.runHistory?.has(m) === true)
+                return answer;
+        }
+        this.answerSources.set(answer, ids);
+        return answer;
+    }
     haltConsumption() {
         const turnCut = this.turnCutConsumed?.source;
         return {
@@ -1244,6 +1271,23 @@ export class AgentHarness {
     finalizeToolCall(toolCall, args, executed) {
         return finalizeToolOutcome(toolCall, executed, (result, isError) => this.afterToolCallHook(toolCall, args, result, isError), this.onToolMediaRefused);
     }
+    async callTool(toolCall, signal, admit) {
+        const run = this.activeRun;
+        if (run === undefined)
+            throw new AgentHarnessError("invalid_state", "a host's tool call runs inside a running prompt, and none is running");
+        const context = run.context();
+        const tool = findToolByName(context.tools, toolCall.name);
+        if (tool === undefined)
+            throw new AgentHarnessError("invalid_state", `no tool named "${toolCall.name}" in this run (it has ${(context.tools ?? []).map((t) => t.name).join(", ") || "none"})`);
+        admit(tool);
+        const both = signal !== undefined ? AbortSignal.any([signal, run.signal]) : run.signal;
+        return (await runToolCall(context, undefined, toolCall, run.config, both, run.emit)).finalized;
+    }
+    isBatchSafe(toolName, args) {
+        const tools = this.activeRun?.context().tools;
+        const tool = findToolByName(tools, toolName);
+        return tool !== undefined && isBatchSafeToolCall(tool, { type: "toolCall", id: "", name: toolName, arguments: (typeof args === "object" && args !== null ? args : {}) });
+    }
     getModel() {
         return this.model;
     }
@@ -1463,6 +1507,7 @@ function mergeTruncatedOutputChain(messages, lastAssistantIndex) {
     const last = messages[lastAssistantIndex];
     const lastText = last.content.map((c) => (c.type === "text" ? c.text : "")).join("");
     const parts = [];
+    const members = [last];
     let i = lastAssistantIndex;
     while (i - 2 >= 0) {
         const mid = messages[i - 1];
@@ -1477,18 +1522,20 @@ function mergeTruncatedOutputChain(messages, lastAssistantIndex) {
         if (!step)
             break;
         parts.unshift(head.content.map((c) => (c.type === "text" ? c.text : "")).join(""));
+        members.unshift(head);
         i = i - 2;
     }
     if (parts.length === 0) {
-        return last;
+        return { message: last, members };
     }
-    return {
+    const message = {
         ...last,
         content: [
             { type: "text", text: parts.join("") + lastText },
             ...last.content.filter((c) => c.type !== "text"),
         ],
     };
+    return { message, members };
 }
 function toLintErrorObject(value, fallbackMessage) {
     if (value instanceof Error) {

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

@@ -2,6 +2,7 @@ import type { PromptEpochDescriptor } from "../../prompt-assembly/epoch.js";
 import type { DocumentContent, ImageContent, Model, SimpleStreamOptions, TextContent, Transport } from "../llm/index.js";
 import type { AfterToolCallResult, AgentEvent, AgentMessage, AgentTool, BeforeToolCallResult, QueueMode, ThinkingLevel } from "../loop/types.js";
 import type { AgentCoreRuntimeDeps } from "../loop/runtime-deps.js";
+import type { SecretEnvFinding } from "../../core/secret-env.js";
 /** Result of a fallible operation. Expected failures are returned as `ok: false` instead of thrown. */
 export type Result<TValue, TError> = {
     ok: true;
@@ -103,7 +104,11 @@ export interface WriteReceipt {
     created: boolean;
 }
 /** Stable, backend-independent file error codes returned by {@link FileSystem} file operations. */
-export type FileErrorCode = "aborted" | "not_found" | "permission_denied" | "not_directory" | "is_directory" | "invalid" | "not_supported"
+export type FileErrorCode = "aborted" | "not_found" | "permission_denied" | "not_directory" | "is_directory"
+/** A name this filesystem cannot hold (POSIX `ENAMETOOLONG` for a path component past `NAME_MAX`) — nothing can be there, and
+ *  a program that opens it fails the same way: an absence as conclusive as `not_found`. A path past `PATH_MAX` whose
+ *  components are short is not this word (such a file may exist, reached from a directory below it). */
+ | "name_too_long" | "invalid" | "not_supported"
 /** Exclusive create refused because the path already exists ({@link FileSystem.writeFileExclusive},
  *  POSIX `O_EXCL` shape). Discriminable so a caller can distinguish "lost the create race" from a
  *  write failure and give honest guidance instead of overwriting. */
@@ -550,6 +555,11 @@ export interface ExecutionEnv extends FileSystem, Shell {
     readonly homeDir?: string;
     /** #1554 — the `CDPATH` entries the shell child receives (`[]` = none), or `"unknown"` when the adapter cannot say. */
     readonly cdPath: readonly string[] | "unknown";
+    /** #1963 — the entries of the environment the shell child inherits that it does NOT receive: the findings of the one
+     *  composition its spawns read (`inheritedHostEnv(policy, findings)`), less the keys the adapter's explicit grants
+     *  re-supply — names and rules, never a value. `[]` = none withheld, or none inherited (a shell environment built
+     *  rather than inherited from this process); `"unknown"` = the adapter cannot say. A read: it announces nothing. */
+    readonly withheldEnv: readonly SecretEnvFinding[] | "unknown";
 }
 /** Base fields shared by append-only session tree entries. */
 export interface SessionTreeEntryBase {
@@ -916,6 +926,16 @@ export interface SessionMetadata {
     /** WHO owns this row, recorded by the write that creates it and changed by no later write; `null` = anonymous; absent reads as `null`. */
     owner?: string | null;
 }
+/**
+ * One row of {@link SessionRepo.list}: the row's metadata, plus the newest activity the repo records for the row. `lastActiveAt` is
+ * epoch ms — on the File repo its log's modification time (every write to a row is an append to its log, and {@link SessionRepo.touch}
+ * moves the same time), on the in-memory repo its last {@link SessionRepo.touch} (it never sees its sessions' writes). Absent = the repo
+ * records none; a reader then takes the row's `createdAt`. It is what the repo records, never what one process saw — so a dropped
+ * cache, a restart or another replica reads the same time, and only a later activity moves it.
+ */
+export type SessionRow<TMetadata extends SessionMetadata = SessionMetadata> = TMetadata & {
+    readonly lastActiveAt?: number;
+};
 /** One row's owner, occupant (`undefined` = unknown) and active leaf (`null` = none), read in ONE read so the three answer for one row generation. */
 export interface SessionHead {
     readonly owner: string | null;
@@ -1078,7 +1098,12 @@ export interface SessionForkOptions {
 export interface SessionRepo<TMetadata extends SessionMetadata = SessionMetadata, TCreateOptions extends SessionCreateOptions = SessionCreateOptions, TListOptions = void> {
     create(options: TCreateOptions): Promise<Session<TMetadata>>;
     open(metadata: TMetadata): Promise<Session<TMetadata>>;
-    list(options?: TListOptions): Promise<TMetadata[]>;
+    /** Every ordinary row (placed rows are not listed), each with the newest write the repo holds for it ({@link SessionRow}), in no
+     *  promised order. The source `TtlSessionStore.list` reads; the store, not the repo, orders, filters and pages. */
+    list(options?: TListOptions): Promise<SessionRow<TMetadata>[]>;
+    /** Record activity on the row now: the time {@link list} answers as the row's `lastActiveAt` moves to now. A missing row is a no-op; a
+     *  fault rejects. Optional: a repo without it records only what its writes record. */
+    touch?(sessionId: string): Promise<void>;
     delete(metadata: TMetadata): Promise<void>;
     /** A fork is a NEW row: `options.id` equal to the source's id is refused (`invalid_fork_target`) — onto its source it would mint a new occupant over the source's own transcript. */
     fork(source: TMetadata, options: SessionForkOptions & TCreateOptions): Promise<Session<TMetadata>>;
@@ -1464,6 +1489,8 @@ export interface AgentHarnessOptions<TSkill extends Skill = Skill, TPromptTempla
      * texts themselves never change.
      */
     abortResultDetails?: () => Record<string, unknown> | undefined;
+    /** The host's station around one tool execution, forwarded verbatim to the loop config (`AgentLoopConfig.executeTool`). */
+    executeTool?: import("../loop/types.js").AgentLoopConfig["executeTool"];
     /**
      * C2: the loop's recovery/terminal trace sink, forwarded to `runAgentLoop`'s trace
      * parameter (previously test-only — never passed in production, so the loop's six self-heal

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";
@@ -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;
     /**
@@ -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;
@@ -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: 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/loop/agent-loop.d.ts

@@ -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

@@ -802,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);
@@ -846,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",
@@ -887,7 +876,7 @@ function isCallConcurrencySafe(tool, args) {
         return false;
     }
 }
-function isBatchSafeToolCall(tool, toolCall) {
+export function isBatchSafeToolCall(tool, toolCall) {
     if (!tool)
         return false;
     let args;
@@ -1108,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))
@@ -1395,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) {
@@ -1404,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;
                 }
@@ -1427,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) {
@@ -1507,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;
@@ -564,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