@sema-agent/core 7.55.0 → 7.57.0

package/dist/core/user-attachment.js

@@ -10,6 +10,8 @@ import { commitReminderDisclosureEffects, planReminderDisclosure } from "./remin
 import { DEFAULT_CHARS_PER_TOKEN, estimateTokens, uuidv7 } from "../internal/harness.js";
 import { thrownText } from "./thrown-value.js";
 import { guardBudget } from "./context-guard.js";
+import { agentIdOf, failedHandlerClause } from "./mods/stations.js";
+import { extensionWords } from "./untrusted-egress.js";
 export const USER_ATTACHMENTS_MAX = 20;
 export const USER_ATTACHMENT_LABEL_MAX = 4096;
 export const USER_ATTACHMENT_KINDS = Object.freeze(["text", "notebook", "image", "pdf", "directory", "client_text", "client_image"]);
@@ -142,9 +144,12 @@ export function refuseUserAttachmentPathsWithoutWorkspace(screened) {
         throw userAttachmentRefusal(memberRef(entryRef(i), "path"), "this run has no workspace (its hand tools are off), so the engine has no file to read — send the file's bytes as a `text` or `image` entry instead.");
 }
 export function userAttachmentDeclarations(screened) {
-    return screened.map((a, i) => a.supply === "path"
-        ? { ordinal: i + 1, supply: a.supply, path: a.path }
-        : { ordinal: i + 1, supply: a.supply, name: a.name, bytes: a.supply === "content_text" ? Buffer.byteLength(a.text, "utf8") : Buffer.from(a.data, "base64").byteLength });
+    return screened.map((a, i) => declarationOf(a, i + 1));
+}
+function declarationOf(a, ordinal) {
+    return a.supply === "path"
+        ? { ordinal, supply: a.supply, path: a.path }
+        : { ordinal, supply: a.supply, name: a.name, bytes: a.supply === "content_text" ? Buffer.byteLength(a.text, "utf8") : Buffer.from(a.data, "base64").byteLength };
 }
 export async function admitUserAttachmentImages(screened) {
     const out = new Map();
@@ -218,6 +223,8 @@ function noteSentence(note, origin) {
             return "The listing was cut short, so it is incomplete.";
         case "too_large_to_restore":
             return "The file was read before the conversation was summarized, but its contents are too large to include here. Use the Read tool if you need them.";
+        case "extension_declined":
+            return "An extension of this deployment did not let this attachment through, so its contents were not attached; what it said is stated above.";
     }
 }
 function disclosureSentence(v) {
@@ -290,13 +297,65 @@ export async function readUserAttachments(input) {
     const count = input.screened.length;
     const seat = disclosureSeatOf(input.reader, input.mark, input.counts);
     const frames = [];
+    const mentions = input.mentions !== undefined && input.mentions.bus.hasHandlers("prompt.mention") ? input.mentions : undefined;
     for (const [i, a] of input.screened.entries()) {
         const ordinal = i + 1;
-        const r = await readOne(a, ordinal, input);
+        const r = mentions !== undefined ? await readMentioned(a, ordinal, input, mentions) : await readOne(a, ordinal, input);
         frames.push(mintFrame(r, { inputId: input.inputId, ordinal, count, mark: input.mark, origin: "user" }, seat));
     }
     return frames;
 }
+const declineOf = (x) => isPlainObject(x) && Object.keys(x).length === 1 && ((typeof x["deny"] === "string" && x["deny"] !== "") || (Object.hasOwn(x, "type") && x["type"] === null))
+    ? typeof x["deny"] === "string" ? { reason: x["deny"] } : {}
+    : undefined;
+async function readMentioned(a, ordinal, input, mentions) {
+    const label = a.supply === "path" ? a.path : a.name;
+    const declined = (text) => ({ supply: a.supply, label, outcome: "not_attached", shape: "file", data: [{ type: "text", text }], notes: [{ kind: "extension_declined" }], unscanned: [label, text], truncated: false });
+    const window = a.supply === "path" && a.lines !== undefined ? { offset: a.lines.start, ...(a.lines.end !== undefined ? { limit: a.lines.end - a.lines.start + 1 } : {}) } : {};
+    const e = { mention: declarationOf(a, ordinal), ...(mentions.agentId !== undefined ? { agentId: mentions.agentId } : {}), ...(a.supply === "path" ? { path: a.path, ...window } : {}) };
+    const reads = new Map();
+    const bottom = async (handed) => {
+        const spelled = respelled(a, handed);
+        const read = typeof spelled === "string" ? declined(`Not attached: ${spelled}.`) : await readOne(spelled, ordinal, input);
+        const answer = Object.freeze({ type: read.outcome === "not_attached" ? null : (read.kind ?? null), outcome: read.outcome });
+        reads.set(answer, read);
+        return answer;
+    };
+    let outcome;
+    try {
+        outcome = await mentions.bus.dispatch("prompt.mention", e, {
+            bottom,
+            signal: input.signal,
+            checkAnswer: (x) => (typeof x === "object" && x !== null && reads.has(x)) || declineOf(x) !== undefined ? undefined : "prompt.mention takes next(e), { deny: <reason> } or { type: null } — an extension does not supply an attachment's contents",
+            ranks: { of: (x) => (typeof x === "object" && x !== null && reads.has(x) ? 0 : 1), top: 1 },
+        });
+    }
+    catch (err) {
+        outcome = { kind: "failed", registration: "engine", cause: "threw", reason: `could not raise the station: ${thrownText(err)}`, skipped: [] };
+    }
+    if (outcome.kind === "aborted")
+        return declined("Not attached: the run was cancelled while an extension was judging it.");
+    if (outcome.kind === "failed")
+        return declined(`Not attached: a prompt.mention extension ${failedHandlerClause(outcome)}.`);
+    const read = typeof outcome.answer === "object" && outcome.answer !== null ? reads.get(outcome.answer) : undefined;
+    if (read !== undefined)
+        return read;
+    const reason = declineOf(outcome.answer)?.reason;
+    return declined(`Not attached: extension "${extensionWords(outcome.answeredBy ?? "engine", 80)}" declined it${reason !== undefined ? `: ${extensionWords(reason, 300)}` : ""}.`);
+}
+function respelled(a, handed) {
+    if (a.supply !== "path") {
+        return ["path", "offset", "limit"].some((k) => Object.hasOwn(handed, k)) ? "an extension handed down a path or line window for an attachment the host supplied (its bytes are its own; nothing is read)" : a;
+    }
+    const { path, offset, limit } = handed;
+    const line = (v) => v === undefined || (typeof v === "number" && Number.isInteger(v) && v >= 1);
+    if (typeof path !== "string" || path === "" || path.length > USER_ATTACHMENT_LABEL_MAX)
+        return "an extension handed down a path that is not one";
+    if (!line(offset) || !line(limit))
+        return "an extension handed down a line window that is not one (offset and limit are whole numbers from 1)";
+    const start = typeof offset === "number" ? offset : typeof limit === "number" ? 1 : undefined;
+    return start === undefined ? { supply: "path", path } : { supply: "path", path, lines: { start, ...(typeof limit === "number" ? { end: start + limit - 1 } : {}) } };
+}
 const refusalData = (r) => {
     const c = r.refusal?.content;
     return typeof c === "string" && c.length > 0 ? [{ type: "text", text: c }] : [];
@@ -439,6 +498,7 @@ export async function readObjectiveAttachments(prepared, inputId, blocked, windo
         mark: prepared.reminderMark,
         counts: prepared.reminderDisclosureCounts,
         signal: prepared.abortController.signal,
+        mentions: { bus: prepared.modBus, ...(agentIdOf(prepared.hookIdentity) !== undefined ? { agentId: agentIdOf(prepared.hookIdentity) } : {}) },
     });
     refuseFramesOverWindow(frames, prepared.harness.getModel(), window);
     return { frames, chars: frames.reduce((n, f) => n + f.seed.content.reduce((m, b) => m + (b.type === "text" ? b.text.length : 0), 0), 0) };

package/dist/core/wiring-manifest.d.ts

@@ -496,6 +496,13 @@ export interface WiringManifest {
     sessionRules?: {
         childrenReadLive: boolean;
     };
+    /**
+     * EFFECTIVE half only; present ⇔ the deployment declared a host floor (`RunnerDeps.hostFloor`): its POSTURE — whether an `only` list
+     * bounds what is reachable (`onlyMode`; `onlyCount: 0` with it = no structured egress at all) and how many entries each list holds.
+     * Deliberately not the entries' text (deployment-supplied hosts, the {@link WiringManifest.readDeny} class). IN the fingerprint: the
+     * declaration is the deployment's, so legs of one assembly agree.
+     */
+    hostFloor?: import("./host-floor.js").HostFloorPosture;
     /**
      * EFFECTIVE half only — the advisor tool on this leg, as the leg STARTED (a snapshot: a switch-off that lands later in the
      * leg is not in it; a host reads the conversation's current state off the transcript, `advisorHoldOf`). Present ⇔ the leg's
@@ -612,6 +619,8 @@ export interface WiringFacts {
     sessionRulesChildrenReadLive?: boolean;
     /** Effective half only — the advisor phase's answer ({@link WiringManifest.advisor}), relayed, never re-derived. */
     advisor?: WiringAdvisorFact;
+    /** Effective half only — the compiled host floor's posture ({@link WiringManifest.hostFloor}); absent ⇒ none declared. */
+    hostFloor?: import("./host-floor.js").HostFloorPosture;
 }
 /** {@link WiringManifest.advisor}. */
 export interface WiringAdvisorFact {

package/dist/core/wiring-manifest.js

@@ -228,6 +228,7 @@ export function deriveWiringManifest(facts) {
         ...(facts.half === "effective" && facts.projectMemory !== undefined ? { projectMemory: readWordFact(facts.projectMemory, ["on", "disabled", "absent"], "project-memory") } : {}),
         ...(facts.half === "effective" && facts.sessionRulesChildrenReadLive !== undefined ? { sessionRules: readSessionRulesFact(facts.sessionRulesChildrenReadLive) } : {}),
         ...(facts.half === "effective" && facts.advisor !== undefined ? { advisor: { ...facts.advisor, ...(facts.advisor.hold !== undefined ? { hold: { ...facts.advisor.hold } } : {}) } } : {}),
+        ...(facts.half === "effective" && facts.hostFloor !== undefined ? { hostFloor: { onlyMode: facts.hostFloor.onlyMode, denyCount: facts.hostFloor.denyCount, onlyCount: facts.hostFloor.onlyCount } } : {}),
         ...(facts.half === "effective" && facts.teamRole !== undefined ? { teamRole: facts.teamRole } : {}),
         ...(facts.half === "effective" && facts.peerPresence !== undefined && (facts.peerPresence.agent !== undefined || facts.peerPresence.intent !== undefined)
             ? { peerPresence: { ...(facts.peerPresence.agent !== undefined ? { agent: facts.peerPresence.agent } : {}), ...(facts.peerPresence.intent !== undefined ? { intent: facts.peerPresence.intent } : {}) } }

package/dist/core/workflow-journal-store.js

@@ -102,7 +102,7 @@ export function journalOversizeTombstone(result, bytes) {
         taskId: result.taskId,
         sessionId: result.sessionId,
         terminal: { kind: "failed", code: JOURNAL_OVERSIZE_ERROR_CODE, message },
-        result: message,
+        result: message, resultEntryIds: [],
         stats: result.stats,
     };
 }

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";
@@ -34,10 +34,11 @@ export interface HaltConsumption {
 export interface TrailingToolBatchOptions {
     readonly halt?: HaltRemainingDirective;
 }
-/** `prompt()` option: called when the prompt and next-turn queue's messages enter the loop transcript, before
- *  their frames are emitted and committed. Not called when a trailing-batch settlement ends the run first — the
- *  caller then still owns whatever the prompt was carrying. */
-export type PromptDeliveredCallback = () => void;
+/** `prompt()` option: the prompt's own receipt — called with the entry id once the prompt's user message is in the
+ *  session (its append returned), before its `message_end` is published. Not called when the append fails or when a
+ *  trailing-batch settlement ends the run before the prompt is delivered — the caller then still owns whatever the
+ *  prompt was carrying. */
+export type PromptCommittedCallback = (entryId: string) => void;
 /** An engine-minted message that TRAILS the prompt's human message in the same request (a user-attachment frame):
  *  minted from its content blocks, always an engine note, carrying its delivery record. */
 export interface TrailingMessageSeed {
@@ -173,7 +174,10 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     private lastPublishedSeat?;
     private readonly seatCutSources;
     private trailingBatchEndedOn?;
+    private promptReceipt?;
     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 +312,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?;
@@ -406,7 +412,7 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     prompt(text: string, options?: {
         images?: ImageContent[];
         settleUnansweredToolCalls?: TrailingToolBatchOptions;
-        onDelivered?: PromptDeliveredCallback;
+        onCommitted?: PromptCommittedCallback;
     } & UserMessageProvenance & PromptTrailing): Promise<AssistantMessage | undefined>;
     /** R2-③: an empty/whitespace-only injection with no images carries ZERO information — it
      *  must not mint a user frame (strict endpoints reject empty user content, and an empty follow-up would
@@ -509,6 +515,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 +565,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,11 +1,12 @@
-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";
 import { isProviderEchoShape } from "../../brain/errors.js";
 import { convertToLlm } from "./messages.js";
 import { readMember, thrownText } from "../../core/thrown-value.js";
+import { remoteWords } from "../../core/protocol-http-auth.js";
 import { AgentHarnessError, CompactionError, SessionError, SYNTHETIC_MESSAGE_MODEL, toError, } from "./types.js";
 const API_FAILURE_RECORD_MAX_CHARS = 2000;
 function createUserMessage(text, images, provenance) {
@@ -66,7 +67,7 @@ function createFailureMessage(model, error, aborted) {
         provider: model.provider,
         model: model.id,
         stopReason: aborted ? "aborted" : "error",
-        errorMessage: thrownText(error),
+        errorMessage: remoteWords(thrownText(error), []),
         timestamp: Date.now(),
         usage: {
             input: 0,
@@ -207,7 +208,10 @@ export class AgentHarness {
     lastPublishedSeat;
     seatCutSources = new WeakMap();
     trailingBatchEndedOn;
+    promptReceipt;
     turnCutConsumed;
+    committedEntryIds = new WeakMap();
+    answerSources = new WeakMap();
     aborting = false;
     drainedPendingInjection = [];
     runAbortController;
@@ -295,6 +299,8 @@ export class AgentHarness {
     maxOutputTokensPerCall;
     stallTimeoutsPerCall;
     abortResultDetails;
+    executeTool;
+    activeRun;
     loopTrace;
     onToolInputValidationFault;
     onToolMediaRefused;
@@ -331,6 +337,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 +657,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,7 +842,13 @@ 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 (this.promptReceipt?.message === event.message) {
+                    const { commit } = this.promptReceipt;
+                    this.promptReceipt = undefined;
+                    commit(entryId);
+                }
                 if (entryId !== undefined && event.message.role === "toolResult" && typeof event.message.toolCallId === "string") {
                     try {
                         this.onFrameCommitted?.({ kind: "tool_result", toolCallId: event.message.toolCallId, content: event.message.content }, entryId);
@@ -901,6 +915,7 @@ export class AgentHarness {
     async executeTurn(turnState, text, options, abortController) {
         let activeTurnState = turnState;
         const userMessage = createUserMessage(text, options?.images, options);
+        this.promptReceipt = options?.onCommitted !== undefined ? { message: userMessage, commit: options.onCommitted } : undefined;
         const trailingMessages = (options?.trailing ?? []).map(createTrailingMessage);
         this.runHistory = new WeakSet(turnState.messages.filter((m) => m.role === "assistant"));
         const beforeResult = await this.emitHook({
@@ -943,9 +958,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: {
@@ -957,7 +975,6 @@ export class AgentHarness {
                             },
                         }
                         : {}),
-                    ...(options?.onDelivered !== undefined ? { onPromptsDelivered: options.onDelivered } : {}),
                 });
             }
             catch (error) {
@@ -975,13 +992,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 +1008,9 @@ export class AgentHarness {
             }
             finally {
                 this.runAbortController = undefined;
+                this.activeRun = undefined;
+                if (this.promptReceipt?.message === userMessage)
+                    this.promptReceipt = undefined;
             }
         }
     }
@@ -1145,6 +1166,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 +1280,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 +1516,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 +1531,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