@sema-agent/core 5.10.0 → 5.12.0

package/dist/core/runner/prepare-task.js

@@ -4,6 +4,7 @@ import { resolve as resolveFsPath } from "node:path";
 import { AgentHarness, DEFAULT_CHARS_PER_TOKEN, DEFAULT_CLAMP_TOLERANCE, DEFAULT_COMPACTION_SETTINGS, estimateContextTokens, readCompactionActiveTools, summaryOutputBudgetTokens } from "../../internal/harness.js";
 const PROMPT_HASH_SALT = randomBytes(16);
 import { sanitizeCompactionSettings } from "../auto-compaction.js";
+import { projectStaleToolResults, resolveStaleToolResultOffload } from "./compaction-call-options.js";
 import { createAutoModeDecider } from "../auto-mode.js";
 import { buildAutoModePrompt, renderAutoModeAction, renderAutoModeWindow } from "../auto-mode-prompt.js";
 import { resolveModel, resolveTaskModel, roleModelIfSet } from "../roles.js";
@@ -319,6 +320,18 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             throw e;
         }
     }
+    if (spec.toolMaterializeStrategy !== undefined && spec.toolMaterializeStrategy !== "swap" && spec.toolMaterializeStrategy !== "static") {
+        const e = new Error(`toolMaterializeStrategy must be "swap" or "static" (got ${JSON.stringify(spec.toolMaterializeStrategy)}).`);
+        e.code = "config.tool_materialize_invalid";
+        throw e;
+    }
+    if (spec.toolMaterializeStrategy === "static" && spec.deferSelfResolve === false) {
+        const e = new Error(`toolMaterializeStrategy "static" cannot be combined with deferSelfResolve: false — with the direct-call ` +
+            `lane disabled a placeholder is never swapped and never self-resolves, so no deferred tool could ever be ` +
+            `called. Use "swap", or leave deferSelfResolve on.`);
+        e.code = "config.tool_materialize_unreachable";
+        throw e;
+    }
     if (resume === undefined && spec.objective.trim().length === 0) {
         const e = new Error("TaskSpec.objective is empty — a task needs an instruction (an empty user message is rejected by strict model endpoints and would fail every later request of the session).");
         e.code = "config.empty_objective";
@@ -977,6 +990,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             alwaysLoadTools: toolFaceSnapshot.alwaysLoad,
             promptProfile,
             ...(spec.additionalDirectories !== undefined ? { additionalDirectories: Object.freeze([...spec.additionalDirectories]) } : {}),
+            ...(spec.additionalReadDirectories !== undefined ? { additionalReadDirectories: Object.freeze([...spec.additionalReadDirectories]) } : {}),
             ...(spec.envFacts !== undefined ? { envFacts: { ...spec.envFacts } } : {}),
             getApiKeyAndHeaders: spec.getApiKeyAndHeaders,
             parentCwd: taskRootPath,
@@ -1151,6 +1165,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             gates: resume?.priorHumanReview?.gates ? [...resume.priorHumanReview.gates] : [],
         };
         const priorSuspendCount = resume?.priorSuspendCount ?? 0;
+        const suspendProgressRef = { executedApproved: false };
+        const suspendChainBase = () => (suspendProgressRef.executedApproved ? 0 : priorSuspendCount);
         const maxSuspends = spec.maxSuspends ?? deps.maxSuspends ?? DEFAULT_MAX_SUSPENDS;
         const maxSlices = spec.resourceSuspend?.maxSlices;
         const priorLedger = resume?.priorLedger;
@@ -1334,34 +1350,40 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         const callIssuedAtRef = {};
         const memoryWriteGateRef = {};
         const additionalRootsCanonical = [];
+        const additionalReadRootsCanonical = [];
         let attachmentRootCanonical;
         if (handsEnabled) {
             const rootRaw = taskRootPath;
             const canon = await executionEnv.canonicalPath(rootRaw);
             const rootCanonical = canon.ok ? canon.value : rootRaw;
             attachmentRootCanonical = rootCanonical;
-            for (const dir of spec.additionalDirectories ?? []) {
-                if (!dir || !dir.trim())
-                    continue;
-                const c = await executionEnv.canonicalPath(dir);
-                if (c.ok) {
-                    additionalRootsCanonical.push(c.value);
-                }
-                else {
-                    deps.onError?.(new Error(`additionalDirectories entry skipped (cannot canonicalize): ${dir}`), {
-                        phase: "config",
-                        sessionId,
-                    });
-                    emitTrace(deps.tracer, () => ({
-                        kind: "config.additional_directory_skipped",
-                        version: 1,
-                        taskId: hostTaskId,
-                        entry: dir,
-                        reason: `${c.error.code}: ${c.error.message}`,
-                        ts: Date.now(),
-                    }));
+            const canonicalizeExtraDirs = async (dirs, field, sink) => {
+                for (const dir of dirs ?? []) {
+                    if (!dir || !dir.trim())
+                        continue;
+                    const c = await executionEnv.canonicalPath(dir);
+                    if (c.ok) {
+                        sink.push(c.value);
+                    }
+                    else {
+                        deps.onError?.(new Error(`${field} entry skipped (cannot canonicalize): ${dir}`), {
+                            phase: "config",
+                            sessionId,
+                        });
+                        emitTrace(deps.tracer, () => ({
+                            kind: "config.additional_directory_skipped",
+                            version: 1,
+                            taskId: hostTaskId,
+                            entry: dir,
+                            ...(field !== "additionalDirectories" ? { field } : {}),
+                            reason: `${c.error.code}: ${c.error.message}`,
+                            ts: Date.now(),
+                        }));
+                    }
                 }
-            }
+            };
+            await canonicalizeExtraDirs(spec.additionalDirectories, "additionalDirectories", additionalRootsCanonical);
+            await canonicalizeExtraDirs(spec.additionalReadDirectories, "additionalReadDirectories", additionalReadRootsCanonical);
             if (spec.envFacts?.scratchpadDir) {
                 let c = await executionEnv.canonicalPath(spec.envFacts.scratchpadDir);
                 if (!c.ok && c.error.code === "not_found") {
@@ -1412,6 +1434,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             }
             const band = createHandsToolkit(executionEnv, readFileState, rootCanonical, {
                 ...(additionalRootsCanonical.length > 0 ? { additionalRoots: additionalRootsCanonical } : {}),
+                ...(additionalReadRootsCanonical.length > 0 ? { additionalReadRoots: additionalReadRootsCanonical } : {}),
                 includeShell: handsIncludeShell,
                 readOnly: handsReadOnly,
                 ...(handsCwdRef ? { cwdRef: handsCwdRef } : {}),
@@ -1453,7 +1476,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 irreversibilityTier.set("Bash", shellGate === "always" ? "always" : "maybe");
                 irreversibleTools.add("Bash");
                 const shellReadBoundary = () => ({
-                    roots: [rootCanonical, ...additionalRootsCanonical],
+                    roots: [rootCanonical, ...additionalRootsCanonical, ...additionalReadRootsCanonical],
                     ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}),
                 });
                 if (shellGate === "classify")
@@ -1777,6 +1800,9 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             if (additionalRootsCanonical.length > 0) {
                 envFacts.additionalDirectories = [...additionalRootsCanonical];
             }
+            if (additionalReadRootsCanonical.length > 0) {
+                envFacts.additionalReadDirectories = [...additionalReadRootsCanonical];
+            }
             try {
                 const probe = await executionEnv.exec('uname -s; uname -r; (git rev-parse --is-inside-work-tree 2>/dev/null || echo false); (git symbolic-ref --short -q HEAD 2>/dev/null || echo "HEAD (detached)"); (git rev-parse --show-toplevel 2>/dev/null || echo); (test -n "$(git status --porcelain 2>/dev/null | head -1)" && echo dirty || echo clean); (s=$(ps -p $$ -o comm= 2>/dev/null); s=${s##*/}; echo "${s#-}"); (test "$(git rev-parse --git-dir 2>/dev/null)" != "$(git rev-parse --git-common-dir 2>/dev/null)" && echo linked || echo main); (pwd -P 2>/dev/null || pwd)', { cwd: envFacts.cwd, timeout: 10 });
                 if (probe.ok && probe.value.exitCode === 0) {
@@ -2021,6 +2047,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             .filter((s) => s.status === "failed")
             .map((s) => ({ name: inlineUntrusted(s.name, 160), ...(s.error !== undefined ? { error: inlineUntrusted(s.error, 240) } : {}) }));
         let toolsDeltaRef;
+        let toolMaterializeStatic = false;
         if (deferred.size > 0 || failedMcpServers.length > 0) {
             toolsDeltaRef = { pending: [], pendingRemoved: [], pendingReadded: [], pendingFailed: failedMcpServers };
         }
@@ -2097,8 +2124,16 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             };
             offloadReachableToolsRef.current = callableToolNames;
             let toolSearch;
+            const envStrategy = process.env.SEMA_TOOL_MATERIALIZE_STRATEGY;
+            if (envStrategy !== undefined && envStrategy !== "swap" && envStrategy !== "static") {
+                const e = new Error(`SEMA_TOOL_MATERIALIZE_STRATEGY must be "swap" or "static" (got ${JSON.stringify(envStrategy)}).`);
+                e.code = "config.tool_materialize_invalid";
+                throw e;
+            }
+            const materializeStatic = (spec.toolMaterializeStrategy ?? envStrategy ?? "static") === "static" && spec.deferSelfResolve !== false;
+            toolMaterializeStatic = materializeStatic;
             const buildToolList = (active) => {
-                const list = tools.map((t) => (deferred.has(t.name) && !active.has(t.name) ? placeholders.get(t.name) : t));
+                const list = tools.map((t) => (deferred.has(t.name) && (materializeStatic || !active.has(t.name)) ? placeholders.get(t.name) : t));
                 list.push(toolSearch);
                 return list;
             };
@@ -2139,6 +2174,9 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 listingRide: (newly) => listingRideRef.current?.(newly),
                 mountedNames: callableToolNames,
                 directCallEnabled: spec.deferSelfResolve !== false,
+                ...(materializeStatic
+                    ? { staticSchemaFor: (name) => tools.find((t) => t.name === name)?.parameters }
+                    : {}),
                 serializeActivation,
             });
             harnessTools = buildToolList(activeTools);
@@ -2238,6 +2276,34 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         const dateChange = renderWithDate
             ? { legDate: envFacts.date, today: () => formatLocalDate(new Date(), tzValid ? userTz : undefined) }
             : undefined;
+        const lastBrainContextRef = {};
+        const requestLossyRef = { current: false };
+        const staleOffloadWrittenRefs = new Set();
+        const lastBrainContext = () => lastBrainContextRef.current;
+        const recordBrainContext = (servedModelId, c) => {
+            if (requestLossyRef.current) {
+                lastBrainContextRef.current = undefined;
+                return;
+            }
+            lastBrainContextRef.current = {
+                ...(c.systemPrompt !== undefined ? { systemPrompt: c.systemPrompt } : {}),
+                ...(c.systemBlocks !== undefined ? { systemBlocks: [...c.systemBlocks] } : {}),
+                messages: [...c.messages],
+                ...(c.tools !== undefined ? { tools: [...c.tools] } : {}),
+                modelId: servedModelId,
+            };
+        };
+        const staleOffloadCfg = resolveStaleToolResultOffload(spec.compaction?.staleToolResultOffload);
+        if (staleOffloadCfg !== undefined && offloadStore === undefined) {
+            deps.onError?.(new Error("compaction.staleToolResultOffload is set but the tool-result offload store is disabled (toolResultThresholdChars ≤ 0/∞) — the knob is inert this run; re-enable offloading or drop the knob"), { phase: "config", sessionId });
+        }
+        const staleOffload = staleOffloadCfg !== undefined && offloadStore !== undefined ? { cfg: staleOffloadCfg, store: offloadStore } : undefined;
+        const guardedBrain = brainCallGuardrailMs === undefined
+            ? deps.brain
+            : {
+                ...deps.brain,
+                stream: withBrainCallGuardrail((m, c, o) => deps.brain.stream(m, c, o), brainCallGuardrailMs, brainCallGuardrailRef),
+            };
         const harness = new AgentHarness({
             abortResultDetails: () => suspendRef.token !== undefined || reviewRef.token !== undefined ? { code: "gate.parked" } : undefined,
             ...(spec.limits?.maxOutputTokens !== undefined && spec.limits.maxOutputTokens > 0
@@ -2271,12 +2337,20 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             systemPrompt,
             ...(assembled.systemBlocks ? { systemBlocks: assembled.systemBlocks } : {}),
             getApiKeyAndHeaders: spec.getApiKeyAndHeaders,
-            runtime: brainToRuntime(brainCallGuardrailMs === undefined
-                ? deps.brain
-                : {
-                    ...deps.brain,
-                    stream: withBrainCallGuardrail((m, c, o) => deps.brain.stream(m, c, o), brainCallGuardrailMs, brainCallGuardrailRef),
-                }),
+            runtime: brainToRuntime({
+                ...guardedBrain,
+                stream: (m, c, o) => {
+                    if (staleOffload === undefined) {
+                        recordBrainContext(m.id, c);
+                        return guardedBrain.stream(m, c, o);
+                    }
+                    return (async () => {
+                        const projected = await projectStaleToolResults(c, staleOffload.cfg, staleOffload.store, sessionId, staleOffloadWrittenRefs);
+                        recordBrainContext(m.id, projected);
+                        return await guardedBrain.stream(m, projected, o);
+                    })();
+                },
+            }),
         });
         harnessRef.current = harness;
         let releaseSignal = () => undefined;
@@ -3083,7 +3157,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         }
                         return false;
                     }
-                    if (suspendLoopCapHit(priorSuspendCount, maxSuspends, " for a plan_review (likely a resume/restart loop)."))
+                    if (suspendLoopCapHit(suspendChainBase(), maxSuspends, " for a plan_review (likely a resume/restart loop)."))
                         return false;
                     const leafId = await session.getLeafId();
                     if (!leafId) {
@@ -3131,7 +3205,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         createdAt: mintedAt,
                         suspendedAt: now(),
                         deadline: mintedAt + (sanitizedTtlMs(spec.durableApproval?.ttlMs) ?? DEFAULT_RESOURCE_TTL_MS),
-                        suspendCount: priorSuspendCount + 1,
+                        suspendCount: suspendChainBase() + 1,
                         humanReview: humanReviewRef.count > 0
                             ? { count: humanReviewRef.count, totalWaitMs: humanReviewRef.totalWaitMs, gates: [...humanReviewRef.gates] }
                             : undefined,
@@ -3192,7 +3266,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         if (abortController.signal.aborted) {
                             return undefined;
                         }
-                        if (suspendLoopCapHit(priorSuspendCount, maxSuspends, ` for tool "${req.toolName}" — likely a resume/restart loop.`))
+                        if (suspendLoopCapHit(suspendChainBase(), maxSuspends, ` for tool "${req.toolName}" — likely a resume/restart loop.`))
                             return undefined;
                         if (remoteEnv !== undefined) {
                             if (hasBackgroundShell(remoteEnv))
@@ -3215,6 +3289,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             args: postHookArgs,
                             safety,
                             shellGated: (req.toolName === "Bash" && shellGatedBash) || (req.toolName === "Monitor" && shellGatedMonitor),
+                            ...(effectiveShellGate !== "off" ? { shellGateDoctrine: effectiveShellGate } : {}),
                         });
                         gate =
                             safety !== undefined
@@ -3275,7 +3350,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             humanReview: humanReviewRef.count > 0
                                 ? { count: humanReviewRef.count, totalWaitMs: humanReviewRef.totalWaitMs, gates: [...humanReviewRef.gates] }
                                 : undefined,
-                            suspendCount: priorSuspendCount + 1,
+                            suspendCount: suspendChainBase() + 1,
                             resourceLedger: approvalLedger,
                             sourceTaskId: sessionId,
                             ...(spec.principal ? { principal: spec.principal } : {}),
@@ -3448,7 +3523,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     : {}),
             });
             let trimmed = trimToBudget(edited, guardAt, estimateContextTokens(edited, charsPerToken).tokens, charsPerToken);
-            if (trimmed.length < edited.length) {
+            const trimDroppedMessages = trimmed.length < edited.length;
+            if (trimDroppedMessages) {
                 trimPressureRef.droppedMessages = true;
                 const droppedCount = edited.length - trimmed.length;
                 trimmed = insertTrimNotice(trimmed);
@@ -3471,6 +3547,12 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 catch {
                 }
             }
+            requestLossyRef.current =
+                capped !== healed ||
+                    mediaCapped !== capped ||
+                    edited !== mediaCapped ||
+                    trimDroppedMessages ||
+                    swept.dropped.length > 0;
             return { messages: swept.messages };
         });
         const cacheBreakDetector = deps.cacheBreakDetection === false ? undefined : new CacheBreakDetector();
@@ -3584,7 +3666,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             : undefined;
         const listBackgroundTasks = () => defaultTaskRegistry
             .list({ owner: hostTaskId, scope: taskScope, sessionId })
-            .filter((t) => t.status === "pending" || t.status === "running")
+            .filter((t) => t.status === "pending" || t.status === "running" || t.status === "parked")
             .map((t) => ({ id: t.task_id, ...(t.description !== undefined ? { description: t.description } : {}), status: t.status }));
         const overheadState = { promptChars: 0 };
         const centerCompactionCandidate = deps.promptSource !== undefined && centerAdoption !== undefined
@@ -3636,7 +3718,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             : undefined;
         overheadState.promptChars = systemPrompt.length;
         const preparedHolder = {};
-        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath, model, thinking, compModel, mcp: mcp, ...(a2a !== undefined && a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), releaseSignal, cacheBreakDetector, cacheFingerprint, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), ownedEnv, suspendRef, reviewRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, wakeRecovered, promptOverheadTokens, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
+        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath, model, thinking, compModel, mcp: mcp, ...(a2a !== undefined && a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), releaseSignal, cacheBreakDetector, cacheFingerprint, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, ownedEnv, suspendRef, suspendProgressRef, reviewRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
         const prepared = buildPrepared();
         preparedHolder.current = prepared;
         return prepared;

package/dist/core/runner/runtask.js

@@ -3,7 +3,7 @@ import { CheckpointError, BINDING_CHECKPOINT_VERSION, checkpointVersionOf, MAX_S
 import { engineVersion } from "../version.js";
 import { CONFIG_CATALOG_VERSION, declarationReasons, resolveEffectiveConfig } from "../../config/catalog.js";
 import { eventDefaultOn } from "../../prompt-assembly/event-registry.js";
-import { DEFAULT_COMPACTION_INSTRUCTIONS, createRapidRefillState, isCompactionManualCancel, maybeCompact, nextTrimForceBackoff, recordCompactionAndCheckRapidRefill } from "../auto-compaction.js";
+import { DEFAULT_COMPACTION_INSTRUCTIONS, createRapidRefillState, isCompactionManualCancel, maybeCompact, nextTrimForceBackoff, recordCompactionAndCheckRapidRefill, sanitizeCompactionSettings } from "../auto-compaction.js";
 import { ASK_USER_QUESTION_TOOL_NAME, QUESTION_AWAITS_RESUME } from "../ask-question.js";
 import { computeCostMicroUsd, modelCostToPricing } from "../pricing.js";
 import { emitTrace } from "../trace.js";
@@ -23,7 +23,7 @@ import { OUTPUT_TOOL_NAME, SKILLS_LISTING_PROBE_HEADER, resolveOutputRetries } f
 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 { buildWorkingFileAttachments, centerAdoptionOption, emitInputTruncated, forkContextOption } from "./compaction-call-options.js";
 import { prepareTask, resolveCheckpointStore } from "./prepare-task.js";
 import { settleTeardownLeg } from "./teardown-bounded.js";
 import { TOOL_SEARCH_NAME } from "./tool-disclosure.js";
@@ -426,6 +426,12 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
             if (declaredMaxTurns !== undefined && declaredMaxTurns > 0) {
                 ratios.push({ axis: "turn budget", ratio: (stats.turns + 1) / declaredMaxTurns });
             }
+            if (walltimeMonotonicDeadline !== undefined) {
+                const walltimeWindowMs = walltimeMonotonicDeadline - rs.telemetry.taskStartMonotonic;
+                if (walltimeWindowMs > 0) {
+                    ratios.push({ axis: "walltime budget", ratio: (performance.now() - rs.telemetry.taskStartMonotonic) / walltimeWindowMs });
+                }
+            }
             let tightest;
             for (const r of ratios)
                 if (tightest === undefined || r.ratio > tightest.ratio)
@@ -490,7 +496,7 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                         rs.attach.attachState.surfacedMtime.delete(p);
                     changed = scan.changed;
                 }
-                const backgroundTasksOn = rs.attach.attachmentsCfg?.backgroundTasks === true;
+                const backgroundTasksOn = (rs.attach.attachmentsCfg?.backgroundTasks ?? eventDefaultOn("background_tasks")) === true;
                 const bgTasks = backgroundTasksOn && rs.attach.attachState.postCompactPending ? prepared.listBackgroundTasks() : undefined;
                 const toolsDeltaOn = rs.attach.attachmentsCfg?.toolsDelta === true;
                 const tdRef = toolsDeltaOn ? prepared.toolsDeltaRef : undefined;
@@ -541,6 +547,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
                         ? {
@@ -556,7 +563,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)
@@ -755,6 +766,7 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                 ...centerAdoptionOption(prepared),
                 model: event.model,
                 compactionModel: prepared.compModel,
+                ...forkContextOption(prepared, false),
                 brain: compactionBrain,
                 getApiKeyAndHeaders: spec.getApiKeyAndHeaders,
                 thinking: prepared.thinking,
@@ -1338,6 +1350,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) => {
@@ -1501,24 +1514,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) => {
@@ -1753,7 +1783,8 @@ export class Runner {
                 }
             }
         }
-        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 &&
@@ -1903,7 +1934,8 @@ export class Runner {
         rs.attach.agentListingOn = rs.attach.attachmentsCfg?.agentListing !== false && eventDefaultOn("agent_listing");
         rs.attach.skillsListingOn = rs.attach.attachmentsCfg?.skillsListing !== false && eventDefaultOn("skills_listing");
         const listingsLive = (rs.attach.agentListingOn && prepared.agentListing !== undefined) || (rs.attach.skillsListingOn && prepared.skillsListing !== undefined);
-        rs.attach.attachState = rs.attach.attachmentsCfg !== undefined || listingsLive ? createAttachmentState() : undefined;
+        const backgroundTasksLive = (rs.attach.attachmentsCfg?.backgroundTasks ?? eventDefaultOn("background_tasks")) === true;
+        rs.attach.attachState = rs.attach.attachmentsCfg !== undefined || listingsLive || backgroundTasksLive ? createAttachmentState() : undefined;
         rs.attach.dateState = prepared.dateChange !== undefined ? { announcedDate: prepared.dateChange.legDate } : undefined;
         rs.attach.instrProbe = this.deps.probeInstructionSources;
         rs.attach.instrState =
@@ -1916,7 +1948,7 @@ export class Runner {
                 : undefined;
         rs.counters.cadenceTurns = 0;
         rs.turn.lastTurnHadToolCalls = false;
-        if (rs.attach.attachState !== undefined && rs.attach.attachmentsCfg?.backgroundTasks === true) {
+        if (rs.attach.attachState !== undefined && (rs.attach.attachmentsCfg?.backgroundTasks ?? eventDefaultOn("background_tasks")) === true) {
             try {
                 const branch = await prepared.session.getBranch();
                 for (let i = branch.length - 1; i >= 0; i--) {
@@ -2240,6 +2272,19 @@ export class Runner {
         };
         const withinTaskCompaction = (spec.compaction?.enabled ?? true) && (spec.compaction?.withinTask ?? true);
         const compactionBreaker = { failures: 0 };
+        if (spec.compaction?.enabled ?? true) {
+            const prefixWindow = prepared.model.autoCompactTokens ?? prepared.model.contextTokens ?? prepared.model.contextWindow;
+            if (Number.isFinite(prefixWindow) && prefixWindow > 0) {
+                const prefixSettings = sanitizeCompactionSettings({ ...DEFAULT_COMPACTION_SETTINGS, ...spec.compaction }, prefixWindow);
+                const prefixCompactAt = prefixWindow - prefixSettings.reserveTokens;
+                if (prepared.promptOverheadTokens >= prefixCompactAt) {
+                    this.deps.onError?.(new Error(`compaction cannot help: the fixed request prefix (system prompt + tool schemas, ≈${prepared.promptOverheadTokens} tokens) ` +
+                        `already meets or exceeds the compaction threshold (${prefixCompactAt} of a ${prefixWindow}-token window). ` +
+                        `Compaction only shrinks conversation history, so this run will re-trigger or overflow regardless — ` +
+                        `shrink the system prompt/tool surface or use a larger-window model.`), { phase: "config", sessionId: prepared.sessionId });
+                }
+            }
+        }
         const windowSafetyOptions = (mainModel) => ({
             ...(rs.budget.maxCostMicroUsd !== undefined
                 ? {
@@ -2409,6 +2454,7 @@ export class Runner {
                             ...centerAdoptionOption(prepared),
                             model: prepared.harness.getModel(),
                             compactionModel: prepared.compModel,
+                            ...forkContextOption(prepared, true),
                             brain: compactionBrain,
                             getApiKeyAndHeaders: spec.getApiKeyAndHeaders,
                             thinking: prepared.thinking,
@@ -2705,9 +2751,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 }));
@@ -2775,7 +2823,7 @@ export class Runner {
                 });
             }
         }
-        if (rs.attach.attachState?.postCompactPending === true && rs.attach.attachmentsCfg?.backgroundTasks === true) {
+        if (rs.attach.attachState?.postCompactPending === true && (rs.attach.attachmentsCfg?.backgroundTasks ?? eventDefaultOn("background_tasks")) === true) {
             emitTrace(rs.telemetry.tracer, () => ({ kind: "compaction.announce_dropped", version: 1, taskId: rs.telemetry.taskId, ts: Date.now() }));
         }
         const comp = await this.finish(spec, prepared, {
@@ -3512,6 +3560,7 @@ 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);
@@ -3622,6 +3671,7 @@ export class Runner {
                     ...centerAdoptionOption(prepared),
                     model: prepared.model,
                     compactionModel: prepared.compModel,
+                    ...forkContextOption(prepared, false),
                     brain: opts?.brain ?? this.deps.brain,
                     getApiKeyAndHeaders: spec.getApiKeyAndHeaders,
                     thinking: prepared.thinking,

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/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.";