@sema-agent/core 5.9.0 → 5.11.0

package/dist/core/runner/runtask.js

@@ -24,7 +24,7 @@ import { cacheFamilyOf, usageCostMicroUsd } from "./usage-accounting.js";
 import { assembleResult, errorCodeOf } from "./assemble-result.js";
 import { ATTACHMENT_BYTE_CAP, CHANGED_FILES_MAX, AGENT_LISTING_REMOVED_HEADER, SKILLS_LISTING_DELTA_HEADER, SKILLS_LISTING_REMOVED_HEADER, advanceCadenceClock, agentListingDeltaHeader, agentListingInitialHeader, replayAnnouncedListing, replayAnnouncedModels, clipToBytes, collectDateChange, collectDueAttachments, collectInstructionsChange, commitAgentListing, commitInstructionsChange, commitSkillsListing, createAttachmentState, rebaseCadenceWindows, reduceToolEnd, renderAgentListingDelta, renderMcpDroppedTools, renderMcpInstructionsDelta, renderOrphanedBackgroundTasks, selectMcpDroppedBatch, renderSkillsListingDelta, renderToolsDelta, stampWriteAnchor } from "./turn-attachments.js";
 import { buildWorkingFileAttachments, centerAdoptionOption, emitInputTruncated } from "./compaction-call-options.js";
-import { prepareTask } from "./prepare-task.js";
+import { prepareTask, resolveCheckpointStore } from "./prepare-task.js";
 import { settleTeardownLeg } from "./teardown-bounded.js";
 import { TOOL_SEARCH_NAME } from "./tool-disclosure.js";
 import { hasVerifiableStructureSignal } from "./grounding-signal.js";
@@ -123,6 +123,9 @@ function toolEndBodyFrom(result, isError) {
         ...(typeof code === "string" ? { errorCode: code } : {}),
     };
 }
+export function reconciledToolEndBody(orphan) {
+    return toolEndBodyFrom({ content: orphan.text, details: { code: orphan.errorKind } }, true);
+}
 function deepJsonEqual(a, b) {
     if (a === b)
         return true;
@@ -240,6 +243,42 @@ function resumeContinuation(resume) {
         `conversation above. Do NOT restart the task or re-run any tool you already ran; continue from this ` +
         `exact point, building on the existing results, and finish the remaining work.`);
 }
+const ENV_DUE_GOVERNANCE_READ_BUDGET_MS = 5_000;
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const DEADLINE_TICK = Symbol("deadline-tick");
+export const GOVERNANCE_READ_STALLED = Symbol("governance-read-stalled");
+const CHARGE_SETTLE_DISCLOSE_MS = 10_000;
+export async function awaitChargeWithSlowDisclosure(charge, onSlow, discloseAfterMs = CHARGE_SETTLE_DISCLOSE_MS) {
+    let timer = setTimeout(() => {
+        timer = undefined;
+        try {
+            onSlow();
+        }
+        catch {
+        }
+    }, discloseAfterMs);
+    try {
+        return await charge;
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+export async function raceUntilDeadline(p, deadline) {
+    for (let firstPass = true;; firstPass = false) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0 && !firstPass)
+            return GOVERNANCE_READ_STALLED;
+        let timer;
+        const tick = new Promise((res) => {
+            timer = setTimeout(() => res(DEADLINE_TICK), Math.max(0, Math.min(remaining, MAX_TIMER_DELAY_MS)));
+        });
+        const out = await Promise.race([p, tick]).finally(() => clearTimeout(timer));
+        if (out !== DEADLINE_TICK)
+            return out;
+    }
+}
 function platformLimitTerminal(reason, retryAfterMs, moment = "turn_boundary") {
     const message = moment === "entry"
         ? `a deployment usage window is exhausted (RunnerDeps.usageWindows), so the task was refused before its first model call — nothing ran and nothing was spent. There is no checkpoint to suspend into at this point, so the caller re-submits after the window frees, in ${String(retryAfterMs ?? 0)}ms.`
@@ -267,17 +306,39 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
         let platformRetryAfterMs;
         const preemptWillSuspend = preemptHit && prepared.suspendForResource !== undefined;
         if (!preemptWillSuspend && prepared.suspendRef.token === undefined && !prepared.abortController.signal.aborted) {
-            if (prepared.envLifetimeSuspendAt !== undefined && Date.now() >= prepared.envLifetimeSuspendAt) {
-                platformCause = "env_lifetime";
-            }
-            else if (prepared.usageGovernance !== undefined) {
+            const ledgerReadDeadline = prepared.envLifetimeSuspendAt !== undefined ? prepared.envLifetimeSuspendAt + ENV_DUE_GOVERNANCE_READ_BUDGET_MS : undefined;
+            if (prepared.usageGovernance !== undefined) {
                 const governance = prepared.usageGovernance;
                 try {
                     const at = Date.now();
-                    await governance.commit(stats.tokens, at);
-                    platformRetryAfterMs = await governance.check(at);
-                    if (platformRetryAfterMs !== undefined)
-                        platformCause = "usage_window";
+                    await awaitChargeWithSlowDisclosure(governance.commit(stats.tokens, at), () => runnerHooks.onError?.(new Error("the usage ledger CHARGE has not settled after 10s — still waiting (a charge is never abandoned: walking away would double-charge on the end-of-task flush). A wedged ledger store wedges this boundary, now visibly."), { phase: "config", sessionId: prepared.sessionId }));
+                    const windowRead = governance.check(at);
+                    let answer;
+                    if (ledgerReadDeadline !== undefined) {
+                        answer = await raceUntilDeadline(windowRead, ledgerReadDeadline);
+                        if (answer === GOVERNANCE_READ_STALLED) {
+                            void windowRead.catch((lateErr) => {
+                                try {
+                                    runnerHooks.onError?.(lateErr instanceof Error ? lateErr : new Error(String(lateErr)), { phase: "config", sessionId: prepared.sessionId });
+                                }
+                                catch {
+                                }
+                            });
+                            try {
+                                runnerHooks.onError?.(new Error("the usage ledger did not answer before the execution environment's suspend deadline — stopping for the environment, the cause this run can still prove. The window state for this boundary is UNKNOWN and was not enforced."), { phase: "config", sessionId: prepared.sessionId });
+                            }
+                            catch {
+                            }
+                        }
+                    }
+                    else {
+                        answer = await windowRead;
+                    }
+                    if (answer !== GOVERNANCE_READ_STALLED) {
+                        platformRetryAfterMs = answer;
+                        if (platformRetryAfterMs !== undefined)
+                            platformCause = "usage_window";
+                    }
                 }
                 catch (govErr) {
                     rs.limits.platformTerminal = govErr instanceof Error ? govErr : new Error(String(govErr));
@@ -286,6 +347,9 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                     return undefined;
                 }
             }
+            if (platformCause === undefined && prepared.envLifetimeSuspendAt !== undefined && Date.now() >= prepared.envLifetimeSuspendAt) {
+                platformCause = "env_lifetime";
+            }
         }
         if (platformCause !== undefined) {
             const platformSpend = { costMicroUsd: stats.costMicroUsd, tokens: stats.tokens, turns: stats.turns, walltimeMs: Math.round(performance.now() - rs.telemetry.taskStartMonotonic) };
@@ -477,6 +541,7 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                         : {}),
                     ...(bgTasks !== undefined ? { backgroundTasks: bgTasks } : {}),
                     ...(pendingTools !== undefined ? { newTools: pendingTools } : {}),
+                    ...(prepared.toolMaterializeStatic ? { newToolsStaticFace: true } : {}),
                     ...(mcpToolsDelta !== undefined ? { mcpToolsDelta } : {}),
                     ...(rs.attach.agentListingOn && prepared.agentListing !== undefined
                         ? {
@@ -492,7 +557,11 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                     ...(mcpDropped !== undefined ? { mcpDroppedTools: mcpDropped } : {}),
                 }));
                 if (pendingTools !== undefined || mcpToolsDelta !== undefined) {
-                    const exact = renderToolsDelta({ ...(pendingTools !== undefined ? { added: pendingTools } : {}), ...(mcpToolsDelta ?? {}) });
+                    const exact = renderToolsDelta({
+                        ...(pendingTools !== undefined ? { added: pendingTools } : {}),
+                        ...(prepared.toolMaterializeStatic ? { staticFace: true } : {}),
+                        ...(mcpToolsDelta ?? {}),
+                    });
                     if (exact !== undefined && due.some((a) => a.source === "tools_delta" && a.body === exact)) {
                         const ref = prepared.toolsDeltaRef;
                         if (pendingTools !== undefined)
@@ -923,7 +992,8 @@ function makeHarnessHandlers(prepared, stats, rs, deps) {
                     : {}),
                 ts: callEndAt,
             }));
-            if (prepared.cacheBreakDetector && prepared.cacheFingerprint) {
+            const cacheRowUnknown = m.usageMissing === true || m.stopReason === "aborted";
+            if (prepared.cacheBreakDetector && prepared.cacheFingerprint && !cacheRowUnknown) {
                 const finding = prepared.cacheBreakDetector.observe({
                     turn: stats.turns + 1,
                     systemPrompt: prepared.cacheFingerprint.systemPrompt,
@@ -1273,6 +1343,7 @@ export class Runner {
             return Promise.race([p, timeout]).finally(() => clearTimeout(t));
         };
         let reapHandle;
+        let steerChain = Promise.resolve();
         const notifyRef = {};
         const manualCompactRef = { requested: false, waiters: [] };
         const drainManualCompactWaiters = (outcome) => {
@@ -1313,6 +1384,10 @@ export class Runner {
             finally {
                 releaseLock?.();
                 publishReady(handle);
+                manualCompactRef.closed = true;
+                if (manualCompactRef.waiters.length > 0)
+                    manualCompactRef.emitMooted?.("task_ending");
+                manualCompactRef.emitMooted = undefined;
                 drainManualCompactWaiters("mooted");
             }
         })();
@@ -1432,24 +1507,41 @@ export class Runner {
                 return suggestionsDone.catch(() => []);
             },
             steer: async (text, options) => {
-                if (resultValue)
-                    throw steeringError("the task has already finished");
-                const h = handle ?? (await orTimeout(ready));
-                if (!h)
-                    throw steeringError("the task is not running");
                 if (options?.trusted && sanitizeUntrustedText(text) !== text) {
                     throw steeringError("trusted steering text must not contain a </system-reminder> tag", "steering.invalid_content");
                 }
                 const payload = options?.trusted ? formatHookFeedback(text) : text;
-                try {
-                    await h.harness.steer(payload, { provenance: "engine-note" });
-                }
-                catch (e) {
-                    if (e instanceof Error && e.code === "invalid_state") {
-                        throw steeringError("the task is no longer running");
+                const deliver = async () => {
+                    if (resultValue)
+                        throw steeringError("the task has already finished");
+                    const h = handle ?? (await orTimeout(ready));
+                    if (!h)
+                        throw steeringError("the task is not running");
+                    try {
+                        await h.harness.steer(payload, { provenance: "engine-note" });
+                        return;
                     }
-                    throw e;
-                }
+                    catch (e) {
+                        if (!(e instanceof Error && e.code === "invalid_state"))
+                            throw e;
+                    }
+                    const birthDeadline = Date.now() + READY_TIMEOUT_MS;
+                    while (resultValue === undefined && !h.loop.ended && Date.now() < birthDeadline) {
+                        try {
+                            await h.harness.steer(payload, { provenance: "engine-note" });
+                            return;
+                        }
+                        catch (e2) {
+                            if (!(e2 instanceof Error && e2.code === "invalid_state"))
+                                throw e2;
+                        }
+                        await new Promise((r) => setTimeout(r, 10));
+                    }
+                    throw steeringError("the task is no longer running");
+                };
+                const p = steerChain.then(deliver);
+                steerChain = p.then(() => undefined, () => undefined);
+                return p;
             },
             notify: async (input, opts) => {
                 const notifyError = (msg, code) => {
@@ -1501,6 +1593,8 @@ export class Runner {
                     throw steeringError("the task is not running");
                 if (opts?.signal?.aborted)
                     return "mooted";
+                if (manualCompactRef.closed)
+                    return "mooted";
                 return new Promise((resolve) => {
                     const signal = opts?.signal;
                     const entry = {
@@ -1516,6 +1610,7 @@ export class Runner {
                                 if (manualCompactRef.waiters.length === 0) {
                                     manualCompactRef.requested = false;
                                 }
+                                manualCompactRef.emitMooted?.("cancelled");
                                 entry.resolve("mooted");
                             }
                         };
@@ -1649,6 +1744,13 @@ export class Runner {
         }, this);
         notificationHarness = prepared.harness;
         notificationSessionId = prepared.sessionId;
+        const runSourceTaskId = spec.taskId ?? prepared.sessionId;
+        const parentToolCallId = internals?.parentToolCallId;
+        const ident = () => parentToolCallId !== undefined ? { eventId: uuidv7(), parentToolCallId, sourceTaskId: runSourceTaskId } : { eventId: uuidv7() };
+        notificationIdent = ident;
+        manualCompactRef.emitMooted = (reason) => {
+            queue.push({ type: "compaction_outcome", outcome: "mooted", trigger: "manual", reason, ...ident() });
+        };
         prepared.harness.onUndrainedEngineNotes = (payloads) => {
             if (notificationSessionId === undefined)
                 return;
@@ -1667,14 +1769,15 @@ export class Runner {
             if (pendingIdle !== undefined) {
                 for (const payload of discloseDroppedPending(pendingIdle)) {
                     deliveredAtTurnOpen.add(taskNotificationDedupKey(payload));
-                    queue.push({ type: "task_notification", notification: payload });
+                    queue.push({ type: "task_notification", notification: payload, ...ident() });
                     void prepared.harness.nextTurn(renderTaskNotificationXml(payload), { provenance: "engine-note", enginePayload: payload }).catch(() => {
                         this.pendingSessionNotifications.pend(prepared.sessionId, payload);
                     });
                 }
             }
         }
-        onReady({ harness: prepared.harness, abortController: prepared.abortController });
+        const loopLatch = { ended: false };
+        onReady({ harness: prepared.harness, abortController: prepared.abortController, loop: loopLatch });
         const stats = { turns: 0, tokens: 0, toolCalls: 0, promptTokens: 0, totalInputTokens: 0, cachedTokens: 0, cacheWriteTokens: 0, cacheWriteTokensLong: 0, outputTokens: 0, costMicroUsd: 0 };
         prepared.liveSpendRef.get = () => ({ costMicroUsd: stats.costMicroUsd, tokens: stats.tokens, turns: stats.turns, walltimeMs: Math.round(performance.now() - rs.telemetry.taskStartMonotonic) });
         if (resume &&
@@ -1716,7 +1819,7 @@ export class Runner {
         rs.limits.outputRetryCap = resolveOutputRetries(spec.outputRetries);
         rs.limits.effectiveMaxTurns = resolveMaxTurns(spec.limits);
         rs.telemetry.tracer = spec.tracer ?? this.deps.tracer;
-        rs.telemetry.taskId = spec.taskId ?? prepared.sessionId;
+        rs.telemetry.taskId = runSourceTaskId;
         if (taskIdRef) {
             taskIdRef.current = rs.telemetry.taskId;
             taskIdRef.sessionId = prepared.sessionId;
@@ -2064,9 +2167,6 @@ export class Runner {
         const walltimeMonotonicDeadline = effectiveTimeoutMs !== undefined ? rs.telemetry.taskStartMonotonic + effectiveTimeoutMs : undefined;
         rs.counters.walltimeSyncBackstopFired = false;
         const timeout = startTimeout(prepared.harness, prepared.abortController, walltimeMonotonicDeadline !== undefined ? walltimeMonotonicDeadline - performance.now() : undefined, prepared.suspendForResource !== undefined);
-        const parentToolCallId = internals?.parentToolCallId;
-        const ident = () => parentToolCallId !== undefined ? { eventId: uuidv7(), parentToolCallId, sourceTaskId: rs.telemetry.taskId } : { eventId: uuidv7() };
-        notificationIdent = ident;
         const pushContent = (e) => {
             queue.push(e);
             if (parentToolCallId !== undefined && internals?.onForwardEvent) {
@@ -2114,6 +2214,10 @@ export class Runner {
         };
         const withBrainSinks = (fn) => runWithStatusSink(statusEmit, () => runWithBrainTelemetry(telemetryEmit, fn));
         const toolLabels = new Map(prepared.tools.flatMap((t) => (t.label !== undefined && t.label !== t.name ? [[t.name, t.label]] : [])));
+        for (const orphan of prepared.wakeRecovered) {
+            queue.push({ type: "tool_end", toolCallId: orphan.toolCallId, toolName: orphan.toolName, ...(toolLabels.has(orphan.toolName) ? { label: toolLabels.get(orphan.toolName) } : {}), isError: true, ...reconciledToolEndBody(orphan), ...ident() });
+            emitCommitted(orphan.entryId, "toolResult", orphan.toolCallId);
+        }
         const postToolBatchHook = (spec.hooks ?? this.deps.hooks)?.postToolBatch;
         const batchArgs = postToolBatchHook ? new Map() : undefined;
         rs.turn.toolBatch = [];
@@ -2625,9 +2729,11 @@ export class Runner {
                     }));
                 }
             }
+            loopLatch.ended = true;
             abortedLive = prepared.abortController.signal.aborted;
         }
         catch (err) {
+            loopLatch.ended = true;
             if (errorCodeOf(err) === "resume.tool_unavailable") {
                 await settleTeardownLeg(() => prepared.mcp.dispose(), "mcp.dispose (tool_unavailable leg)", (e) => this.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
                 await settleTeardownLeg(() => prepared.a2a?.dispose(), "a2a.dispose (tool_unavailable leg)", (e) => this.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
@@ -2660,7 +2766,7 @@ export class Runner {
         }
         if (prepared.usageGovernance !== undefined) {
             try {
-                await prepared.usageGovernance.commit(stats.tokens, Date.now());
+                await awaitChargeWithSlowDisclosure(prepared.usageGovernance.commit(stats.tokens, Date.now()), () => this.deps.onError?.(new Error("the usage ledger's FINAL charge has not settled after 10s — still waiting (a charge is never abandoned: walking away would double-charge on a later flush). A wedged ledger store wedges this teardown, now visibly."), { phase: "config", sessionId: prepared.sessionId }));
             }
             catch (flushErr) {
                 this.deps.onError?.(flushErr, { phase: "config", sessionId: prepared.sessionId });
@@ -2675,7 +2781,7 @@ export class Runner {
             try {
                 const report = await reconcileInterruptedSession(prepared.session, prepared.toolEffects, undefined, startedToolCallIds);
                 for (const orphan of report.recovered) {
-                    queue.push({ type: "tool_end", toolCallId: orphan.toolCallId, toolName: orphan.toolName, ...(toolLabels.has(orphan.toolName) ? { label: toolLabels.get(orphan.toolName) } : {}), isError: true, ...ident() });
+                    queue.push({ type: "tool_end", toolCallId: orphan.toolCallId, toolName: orphan.toolName, ...(toolLabels.has(orphan.toolName) ? { label: toolLabels.get(orphan.toolName) } : {}), isError: true, ...reconciledToolEndBody(orphan), ...ident() });
                     emitCommitted(orphan.entryId, "toolResult", orphan.toolCallId);
                 }
             }
@@ -2873,7 +2979,7 @@ export class Runner {
             const committedToken = prepared.suspendRef.token ?? prepared.reviewRef.token;
             const committedScope = prepared.suspendRef.scope ?? prepared.reviewRef.scope;
             if (committedToken !== undefined) {
-                const store = spec.checkpointStore ?? this.deps.checkpointStore;
+                const store = resolveCheckpointStore(spec, this.deps);
                 if (store && committedScope !== undefined) {
                     onSuspend({
                         env: prepared.ownedEnv,
@@ -2929,6 +3035,11 @@ export class Runner {
                 catch {
                 }
             }
+            if (manualCompactRef.waiters.length > 0) {
+                queue.push({ type: "compaction_outcome", outcome: "mooted", trigger: "manual", reason: "task_ending", ...ident() });
+                drainManualCompact("mooted");
+            }
+            manualCompactRef.emitMooted = undefined;
             queue.push({ type: "done", result });
             queue.close();
             if (spec.rewindFiles && result.status === "completed") {
@@ -3117,7 +3228,7 @@ export class Runner {
         return stream.result();
     }
     async resumeStream(token, outcome, taskConfig, internals) {
-        const store = taskConfig.checkpointStore ?? this.deps.checkpointStore;
+        const store = resolveCheckpointStore(taskConfig, this.deps);
         if (!store) {
             throw new CheckpointError("checkpoint.not_found", "no CheckpointStore wired — cannot resume (set RunnerDeps.checkpointStore or taskConfig.checkpointStore)");
         }
@@ -3352,13 +3463,16 @@ export class Runner {
         const completed = new Set(pendingAction.completedCallIds);
         const deferredIds = pendingAction.batchToolCallIds.filter((id) => id !== pendingAction.toolCallId && !completed.has(id));
         const names = new Map();
+        const deferredArgs = new Map();
         if (deferredIds.length > 0) {
             const { messages } = await prepared.session.buildContext();
             for (const m of messages) {
                 if (m.role === "assistant") {
                     for (const c of m.content) {
-                        if (c.type === "toolCall")
+                        if (c.type === "toolCall") {
                             names.set(c.id, c.name);
+                            deferredArgs.set(c.id, c.arguments);
+                        }
                     }
                 }
             }
@@ -3369,7 +3483,12 @@ export class Runner {
             }
             else if (!completed.has(id)) {
                 const name = names.get(id) ?? "unknown";
-                emit({ type: "tool_end", toolCallId: id, toolName: name, ...((() => { const l = prepared.tools.find((t) => t.name === name)?.label; return l !== undefined && l !== name ? { label: l } : {}; })()), isError: true, ...toolEndBodyFrom({ content: formatHookFeedback(DEFERRED_REISSUE) }, true) });
+                const displayLabel = (() => {
+                    const l = prepared.tools.find((t) => t.name === name)?.label;
+                    return l !== undefined && l !== name ? { label: l } : {};
+                })();
+                emit({ type: "tool_start", toolCallId: id, toolName: name, ...displayLabel, args: deferredArgs.get(id) ?? {} });
+                emit({ type: "tool_end", toolCallId: id, toolName: name, ...displayLabel, isError: true, ...toolEndBodyFrom({ content: formatHookFeedback(DEFERRED_REISSUE) }, true) });
                 const eid = await prepared.session.appendMessage(toolResultMsg(id, name, formatHookFeedback(DEFERRED_REISSUE), true));
                 emitCommitted(eid, "toolResult", id);
             }
@@ -3419,13 +3538,26 @@ export class Runner {
         }
         const args = resolvedArgs;
         onExecuteStart?.(pendingAction.toolCallId);
+        prepared.suspendProgressRef.executedApproved = true;
         let res;
         try {
             res = await tool.execute(pendingAction.toolCallId, args, prepared.abortController.signal);
         }
         catch (err) {
             const execError = `Error: ${err instanceof Error ? err.message : String(err)}`;
-            emitEnd(true, { content: execError });
+            const marks = (() => {
+                if (err === null || typeof err !== "object")
+                    return undefined;
+                const src = err;
+                let d;
+                if (src.details !== null && typeof src.details === "object" && !Array.isArray(src.details)) {
+                    d = { ...src.details };
+                }
+                if (typeof src.errorKind === "string")
+                    d = { ...(d ?? {}), errorKind: src.errorKind };
+                return d;
+            })();
+            emitEnd(true, { content: execError, ...(marks !== undefined ? { details: marks } : {}) });
             const eid = await prepared.session.appendMessage(toolResultMsg(pendingAction.toolCallId, pendingAction.toolName, execError, true));
             emitCommitted(eid, "toolResult", pendingAction.toolCallId);
             return;

package/dist/core/runner/session-file-state-replay.d.ts

@@ -0,0 +1,7 @@
+import type { AgentMessage } from "../../internal/harness.js";
+export interface TranscriptFileRecord {
+    path: string;
+    content: string;
+    at: number;
+}
+export declare function wholeFileRecordsFromTranscript(messages: readonly AgentMessage[]): TranscriptFileRecord[];

package/dist/core/runner/session-file-state-replay.js

@@ -0,0 +1,56 @@
+import { isAbsolutePathForm } from "../../tools/fs/safety.js";
+const READ_TOOL = "Read";
+const WRITE_TOOL = "Write";
+const RETRACTING_RESULTS = [
+    { toolName: "Edit", type: "edit", pathField: "filePath" },
+    { toolName: "NotebookEdit", type: "notebook-edit", pathField: "notebookPath" },
+];
+function cardOf(details) {
+    if (typeof details !== "object" || details === null)
+        return undefined;
+    const rest = details;
+    return typeof rest.type === "string" ? { type: rest.type, rest } : undefined;
+}
+function wholeFileFromReadCard(rest) {
+    const file = rest.file;
+    if (typeof file !== "object" || file === null)
+        return undefined;
+    const f = file;
+    if (typeof f.content !== "string" || f.truncatedByTokenCap === true)
+        return undefined;
+    if (f.startLine !== 1 || typeof f.numLines !== "number" || f.numLines !== f.totalLines)
+        return undefined;
+    return f.content;
+}
+export function wholeFileRecordsFromTranscript(messages) {
+    const byPath = new Map();
+    for (const m of messages) {
+        if (m.role !== "toolResult" || m.isError)
+            continue;
+        const card = cardOf(m.details);
+        if (card === undefined)
+            continue;
+        const { type, rest } = card;
+        const retracts = RETRACTING_RESULTS.find((r) => r.toolName === m.toolName && r.type === type);
+        if (retracts !== undefined) {
+            const changed = rest[retracts.pathField];
+            if (typeof changed === "string")
+                byPath.delete(changed);
+            continue;
+        }
+        const isRead = m.toolName === READ_TOOL && type === "text";
+        const isWrite = m.toolName === WRITE_TOOL && (type === "create" || type === "update");
+        if (!isRead && !isWrite)
+            continue;
+        const nested = rest.file;
+        const holder = isRead ? (typeof nested === "object" && nested !== null ? nested : undefined) : rest;
+        const filePath = holder?.filePath;
+        if (typeof filePath !== "string" || !isAbsolutePathForm(filePath))
+            continue;
+        const content = isRead ? wholeFileFromReadCard(rest) : typeof rest.content === "string" ? rest.content : undefined;
+        if (content === undefined)
+            continue;
+        byPath.set(filePath, { path: filePath, content, at: m.timestamp });
+    }
+    return [...byPath.values()];
+}

package/dist/core/runner/synthetic-tools.js

@@ -78,7 +78,7 @@ export function createReportFindingsTool() {
             const count = findings.length;
             return {
                 content: count === 0 ? "No findings reported." : `${count} finding${count === 1 ? "" : "s"} reported.`,
-                details: { count, ...(level !== undefined ? { level } : {}), findings },
+                details: { type: "report-findings", count, ...(level !== undefined ? { level } : {}), findings },
             };
         },
     });

package/dist/core/runner/tool-disclosure.d.ts

@@ -54,4 +54,5 @@ export declare function createToolSearchTool(opts: {
     mountedNames?: () => ReadonlySet<string>;
     directCallEnabled?: boolean;
     serializeActivation?: <T>(section: () => Promise<T>) => Promise<T>;
+    staticSchemaFor?: (name: string) => TSchema | undefined;
 }): AgentTool;

package/dist/core/runner/tool-disclosure.js

@@ -80,7 +80,7 @@ export function createPlaceholderTool(info, direct) {
     };
     const invalidArgumentsRejection = (target, params, schemaJson, ride) => {
         const text = `Invalid arguments for \`${sn}\`: ${formatZodValidationError(target.parameters, params)} ` +
-            `\`${sn}\` is now active — its full parameter schema is below (and rides the next request). ` +
+            `\`${sn}\` is now active — its full parameter schema is below; use it for this and later calls. ` +
             `Call \`${sn}\` again with arguments matching it.\nParameter schema: ${schemaJson}`;
         return {
             content: ride === undefined || ride === "" ? [{ type: "text", text }] : [{ type: "text", text }, { type: "text", text: ride }],
@@ -236,11 +236,15 @@ export function extractDiscoveredToolNames(messages, registry) {
     return [...names];
 }
 export function createToolSearchTool(opts) {
-    const { registry, active, rematerialize, listingRide, mountedNames } = opts;
+    const { registry, active, rematerialize, listingRide, mountedNames, staticSchemaFor } = opts;
     const directCallEnabled = opts.directCallEnabled !== false;
     const activationPosture = directCallEnabled
-        ? "Most tools start as name-only placeholders to keep requests small; activating one here loads its full " +
-            "parameter schema. Until you have that schema you cannot reliably form a call, so activate a tool rather " +
+        ? (staticSchemaFor !== undefined
+            ? "Most tools start as name-only placeholders to keep requests small; activating one here returns its full " +
+                "parameter schema in the result (the tools list keeps the compact placeholder entry). "
+            : "Most tools start as name-only placeholders to keep requests small; activating one here loads its full " +
+                "parameter schema. ") +
+            "Until you have that schema you cannot reliably form a call, so activate a tool rather " +
             "than guessing its arguments — a call that does match the real schema executes and activates the tool. " +
             "When any instruction, reminder, or another tool's description names a deferred tool, activate it here " +
             'with query "select:<name>". '
@@ -265,7 +269,9 @@ export function createToolSearchTool(opts) {
             "a bare tool name — activates that tool directly. " +
             "Activate every tool you expect to need in one call (select accepts a comma-separated list) " +
             "rather than one at a time. " +
-            "Activated tools become callable with their full parameters on your next turn.",
+            (staticSchemaFor !== undefined
+                ? "Activation returns each tool's full parameter schema in this result — call the tool directly with arguments matching it."
+                : "Activated tools become callable with their full parameters on your next turn."),
         parameters: Type.Object({
             query: Type.Optional(Type.String({
                 description: 'Query to find deferred tools. Use "select:<tool_name>" for direct selection, or keywords to search.',
@@ -329,11 +335,20 @@ export function createToolSearchTool(opts) {
             const lines = matched.map((n) => {
                 const info = registry.get(n);
                 const tag = newly.includes(n) ? "activated" : "already active";
-                return `- ${safeName(n)} (${tag})${info ? ` — ${info.hint}` : ""}`;
+                const base = `- ${safeName(n)} (${tag})${info ? ` — ${info.hint}` : ""}`;
+                if (staticSchemaFor === undefined)
+                    return base;
+                const schema = staticSchemaFor(n);
+                const json = schema === undefined ? undefined : renderSchemaForModel(schema);
+                return json === undefined ? base : `${base}\n  parameters: ${json}`;
             });
-            const head = newly.length > 0
-                ? `Activated ${newly.length} tool(s); they are now available with full parameters — call them directly:`
-                : "These tools are already active — call them directly:";
+            const head = staticSchemaFor !== undefined
+                ? newly.length > 0
+                    ? `Activated ${newly.length} tool(s) — call them directly with arguments matching the parameter schemas below (the tools list keeps compact placeholder entries):`
+                    : "These tools are already active — call them directly; their parameter schemas are repeated below:"
+                : newly.length > 0
+                    ? `Activated ${newly.length} tool(s); they are now available with full parameters — call them directly:`
+                    : "These tools are already active — call them directly:";
             return {
                 content: `${head}\n${lines.join("\n")}${missingNote}${ride !== undefined ? `\n\n${ride}` : ""}`,
                 details: {

package/dist/core/runner/tool-output-projection.js

@@ -57,11 +57,12 @@ export const toolOutputFrom = (result) => {
     return { output: raw, truncated: true, totalChars };
 };
 const CC_DETAIL_TYPES = new Set([
-    "edit", "multiedit", "create", "update", "bash", "notebook-edit", "notebook", "file_unchanged", "worktree", "text", "grep", "glob", "mcp",
-    "agent", "task", "task-list", "task-output", "memory-saved", "workflow-run",
+    "edit", "create", "update", "bash", "notebook-edit", "notebook", "file_unchanged", "worktree", "text", "grep", "glob", "mcp",
+    "agent", "task", "task-list", "task-output", "workflow-run",
     "web-fetch", "web-search", "todo", "cron-create", "cron-delete", "cron-list", "image",
-    "task-stop", "tool-search", "memory-recall", "repo-map", "fork", "enter-plan-mode", "exit-plan-mode",
-    "monitor-start", "path_not_in_root",
+    "task-stop", "tool-search", "repo-map", "fork", "enter-plan-mode", "exit-plan-mode",
+    "monitor-start", "path_not_in_root", "readonly_out_of_root",
+    "report-findings", "schedule-wakeup", "send-message", "agent-transcript", "a2a", "document",
 ]);
 export const structuredFrom = (result) => {
     const details = result !== null && typeof result === "object" ? result.details : undefined;

package/dist/core/runner/turn-attachments.d.ts

@@ -100,6 +100,7 @@ export interface AttachmentInputs {
     }>;
     backgroundTasks?: ReadonlyArray<BackgroundTaskSnapshot>;
     newTools?: readonly string[];
+    newToolsStaticFace?: boolean;
     mcpToolsDelta?: McpToolsDeltaFacts;
     agentListing?: ReadonlyArray<AgentListingEntry>;
     agentToolName?: string;
@@ -148,6 +149,7 @@ export interface McpToolsDeltaFacts {
 }
 export declare function renderToolsDelta(input: {
     added?: readonly string[];
+    staticFace?: boolean;
 } & McpToolsDeltaFacts): string | undefined;
 export declare const AGENT_TOOLS_NOTE_DEFAULT = "All tools";
 export declare const AGENT_CONCURRENCY_NOTE = "When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently.";

package/dist/core/runner/turn-attachments.js

@@ -168,7 +168,11 @@ export function collectDueAttachments(state, inp) {
         }
     }
     if (inp.config.toolsDelta) {
-        const body = renderToolsDelta({ ...(inp.newTools !== undefined ? { added: inp.newTools } : {}), ...(inp.mcpToolsDelta ?? {}) });
+        const body = renderToolsDelta({
+            ...(inp.newTools !== undefined ? { added: inp.newTools } : {}),
+            ...(inp.newToolsStaticFace === true ? { staticFace: true } : {}),
+            ...(inp.mcpToolsDelta ?? {}),
+        });
         if (body !== undefined)
             (out ??= []).push({ source: "tools_delta", body });
     }
@@ -386,15 +390,20 @@ export function renderToolsDelta(input) {
     const blocks = [];
     const added = input.added ?? [];
     if (added.length > 0) {
-        blocks.push("The following deferred tools are now available. Their full schemas are loaded — call them " +
-            "directly like any other tool:\n" +
+        blocks.push((input.staticFace === true
+            ? "The following deferred tools are now active — call them directly. Their parameter schemas were " +
+                "provided in the ToolSearch result (the tools list itself keeps compact placeholder entries):\n"
+            : "The following deferred tools are now available. Their full schemas are loaded — call them " +
+                "directly like any other tool:\n") +
             added.map((n) => `- ${n}`).join("\n"));
     }
     const readded = input.readded ?? [];
     if (readded.length > 0) {
         blocks.push(`${readded.length} deferred tool${readded.length === 1 ? " is" : "s are"} available again (MCP server reconnected — ` +
-            `names announced earlier in this conversation): ${groupByMcpServer(readded)}. Their schemas are loaded again — ` +
-            `call them directly.`);
+            `names announced earlier in this conversation): ${groupByMcpServer(readded)}. ` +
+            (input.staticFace === true
+                ? `The tools list keeps compact placeholder entries — re-run ToolSearch ("select:<name>") if you need their current parameter schemas.`
+                : `Their schemas are loaded again — call them directly.`));
     }
     const removed = input.removed ?? [];
     if (removed.length > 0) {