@sema-agent/core 5.10.0 → 5.11.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 5.11.0 — 2026-08-04
+
+### BREAKING
+
+- **The restart-loop suspend cap counts CONSECUTIVE NO-PROGRESS suspends, not total approvals.** The cap's stated purpose is catching a restart-prone model re-issuing the same gated call forever — yet it counted distinct approved-and-executed gates identically, so under a doctrine that asks per call (`shellGate:"classify"` + out-of-root reads) a fully cooperating approver was killed on the 6th legitimate Yes (`suspend.loop`, default `maxSuspends: 5`). The chain base now resets the moment the resume leg starts EXECUTING the approved pending call (an execution that then errors still consumed the approval — it reset the chain); a park whose approved call never ran keeps accumulating. **Consumer flips**: checkpoint `suspendCount` restarts at 1 after each executed approval — probes pinning a monotonically increasing `suspendCount` across approve-execute cycles red; `maxSuspends` now bounds no-progress chains, never the total number of approvals a run may receive.
+- **`SubagentErrorKind` closed set gains a sixth member: `"governance"`.** A FAILED child whose `errorCode` carries the `usage.*` prefix (deployment usage window refused/exhausted) now classifies as `governance` with `retryable: false` — it is DEFERRED-retryable: re-issuing NOW gets the same refusal, but the refusal lifts at the card's `retryAfterMs`. Previously these folded into `logic` ("re-delegating unchanged won't help"), which told a scheduler to abandon a subtask that merely needed to wait. The transient retry set (`rate_limit`/`overloaded`/`timeout`/`network` → `retryable: true`) is untouched. **Consumer flips**: switches over the closed five-member kind set add a `governance` arm; the completed agent card now pairs `error_kind: "governance"` with `retryAfterMs` on window-exhausted children.
+
+- **Deferred-tool activation no longer rewrites the provider tools block — `toolMaterializeStrategy` defaults to `"static"`.** Tools serialize FIRST in the provider prompt-cache hierarchy, so the old activation swap (placeholder → full schema via setTools) invalidated the entire conversation cache — 29% of benchmarked trials paid an average ~31k tokens per break. Under the new default the placeholder bytes persist for the whole run; the full schema reaches the model through the ToolSearch result text (existing carrier) and engine-side validation against the REAL schema is unchanged. Ruled GO by a live A/B on the weakest BYOM model (15/15 argument instances correct, three scenario classes incl. nested/optional params). `"swap"` is the explicit opt-back (spec or `SEMA_TOOL_MATERIALIZE_STRATEGY`, invalid env value refused loudly as `config.tool_materialize_invalid`). **Consumer flips**: probes pinning the post-activation full schema in the tools block red — the activation announcement frames and genuine roster changes (MCP refresh) are unchanged.
+
+### Added
+
+- **A shell-gated ask persists the live shellGate doctrine on its risk descriptor.** Field forensics could not answer "was `classify` or `always` live when this gate fired" from any persisted artifact. The mint now stamps `RiskDescriptor.shellGateDoctrine` (`"classify" | "always"`, present only on shell-gated asks — `"off"` never mints) so the checkpoint row self-reports its provenance. Additive optional field.
+- **`TaskSpec.additionalReadDirectories` — a read-only fence widening.** Extra directories the READ faces admit and nothing else: the `shellGate:"classify"` read boundary (a provably read-only command like `head <dir>/settings.json` auto-allows instead of consulting the approver on every call — the interactive kill shape this exists for), plus read_file/grep/glob/repo_map and `bash_readonly` containment. The write faces (edit_file/write_file/notebook_edit) refuse these directories exactly as before — a read grant never silently becomes a write grant (`additionalDirectories` remains the read+write widening). Same canonicalization/fail-closed-skip rules as `additionalDirectories` (the skip trace gains an optional `field` discriminator); announced in `# Environment` as `Additional read-only directories:`; inherited down the delegation tree on the same seat as `additionalDirectories`. Additive — absent ⇒ byte-identical behavior.
+
+### Fixed
+
+- **WebFetch stops laundering emptiness into authority (grounding contract).** A shell page (tiny extracted text, or near-zero text ratio) now gets a TRUSTED grounding verdict outside the untrusted fence, the full extracted text appended for verification, and additive `details.grounding{level,textChars,bytes,textRatio}`; an incomplete body is called a retrieved prefix. The summarizer input budget derives from the summary model's window (flat 100k retired; trimmed input disclosed structurally and in the rendered head; NaN model metadata refused loudly). Recovery prose names Bash/curl only when reachable in THIS run. The summary prompt gains a grounding clause (report absence rather than infer; a filename is only evidence about naming) ahead of the byte-fixed CC guidelines tail.
+- **A truncated-tool-arguments disclosure names the request output cap when one was armed** (`request output cap in effect: N tokens`) on both brain lanes — a cut mid-arguments at the cap read as a generic provider error with no budget clue.
+- **agentStream's birth window is steerable**: an immediate `steer()` after `agentStream()` waits (bounded) for the loop's first prompt and lands on turn 1; a finished run keeps the honest refusal.
+- **A long-window zero-byte Bash timeout names its two honest readings** (stalled before producing output / holding it in a block buffer); short windows and abort arms stay bare.
+- **The background faces carry the governance wait hint.** A `usage.window_exhausted` background child's settle dropped `retryAfterMs` — every bg face (poll text, poll details, notification-adjacent durable row) said `retryable:false` with no way to know when the refusal lifts, while the sync report card carried the hint. The classification family gains its fourth seat end-to-end: settle mint → registry row → durable archival row → poll `details.retryAfterMs` → the poll text clause (`(error_kind: governance, retryable: false, retry_after_ms: N)`); a revive clears it with its three siblings. Additive on every face.
+- **The `suspend.loop` terminal diagnoses the every-approval-was-Yes kill.** When every recorded gate decision on the run was ALLOW, the message now names the shape (a gate that keeps asking × an approver that keeps approving consumed the suspend allowance on legitimate work) and the remedies (a live `onAsk` parks nothing; keep benign commands inside the read boundary; raise `maxSuspends` for approval-heavy tasks) instead of reporting a bare restart-loop mystery.
+
 ## 5.10.0 — 2026-08-04
 
 ### Added

package/dist/agents/subagent.d.ts

@@ -34,7 +34,7 @@ export interface SubagentWorktreeIsolation {
 }
 export declare function createSubagentWorktreeHelper(baseEnv: ExecutionEnv, repoRoot: string): SubagentWorktreeIsolation;
 export declare const REPORT_FIELD_MAX = 300;
-export type SubagentErrorKind = "rate_limit" | "overloaded" | "timeout" | "network" | "logic";
+export type SubagentErrorKind = "rate_limit" | "overloaded" | "timeout" | "network" | "logic" | "governance";
 export declare function classifySubagentError(child: {
     status: string;
     errorCode?: string;

package/dist/agents/subagent.js

@@ -229,8 +229,10 @@ export function classifySubagentError(child) {
                 ? "timeout"
                 : code === "network" || code === "server"
                     ? "network"
-                    : "logic";
-    return { errorKind, retryable: errorKind !== "logic" };
+                    : code !== undefined && code.startsWith("usage.")
+                        ? "governance"
+                        : "logic";
+    return { errorKind, retryable: errorKind !== "logic" && errorKind !== "governance" };
 }
 export function completedAgentCard(child, extras) {
     return {
@@ -1502,6 +1504,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 ...(ctx.alwaysLoadTools !== undefined ? { alwaysLoadTools: [...ctx.alwaysLoadTools] } : {}),
                 ...(ctx.promptProfile !== undefined ? { promptProfile: ctx.promptProfile } : {}),
                 ...(ctx.additionalDirectories !== undefined ? { additionalDirectories: [...ctx.additionalDirectories] } : {}),
+                ...(ctx.additionalReadDirectories !== undefined ? { additionalReadDirectories: [...ctx.additionalReadDirectories] } : {}),
                 ...(ctx.envFacts !== undefined ? { envFacts: { ...ctx.envFacts } } : {}),
                 ...(ctx.getApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: ctx.getApiKeyAndHeaders } : {}),
                 enableBlockedReport: true,
@@ -2567,6 +2570,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         ...(!ok ? { error: reaped ? (collateral ? BG_AGENT_COLLATERAL_REAP_REASON : BG_AGENT_REAP_STOP_ERROR) : unparkedPauseReason ?? child.errorMessage ?? String(child.status) } : {}),
                         ...(errCodeBg !== undefined ? { errorCode: errCodeBg } : {}),
                         ...(errClassBg !== undefined ? { retryable: errClassBg.retryable, errorKind: errClassBg.errorKind } : {}),
+                        ...(failedBg && child.retryAfterMs !== undefined ? { retryAfterMs: child.retryAfterMs } : {}),
                     }) ??
                         (abort.signal.aborted ? "killed" : ok ? "completed" : "failed");
                     if (!bgRetain && reviveRow === undefined && !(await bgRowConfirmed())) {

package/dist/brain/anthropic.js

@@ -558,7 +558,7 @@ export function createAnthropicBrain(config = {}) {
                         const noUsableContent = toolCalls.length === 0 && !anyText;
                         const toolErrorParts = [];
                         if (malformed.length > 0) {
-                            toolErrorParts.push(`tool call argument(s) not valid JSON (likely truncated, stop_reason="${stopReason ?? "?"}"): ${malformed.join("; ")}`);
+                            toolErrorParts.push(`tool call argument(s) not valid JSON (likely truncated, stop_reason="${stopReason ?? "?"}"${sentMaxTokens !== undefined ? `; request output cap in effect: ${sentMaxTokens} tokens — a cut mid-arguments commonly means the cap was hit` : ""}): ${malformed.join("; ")}`);
                         }
                         if (unnamed.length > 0) {
                             toolErrorParts.push(`tool call(s) arrived with no tool name and cannot be executed (stop_reason="${stopReason ?? "?"}"): ${unnamed.join("; ")}`);

package/dist/brain/openai.js

@@ -526,7 +526,7 @@ export function createOpenAIBrain(config = {}) {
                         }
                         const toolErrorParts = [];
                         if (malformed.length > 0) {
-                            toolErrorParts.push(`tool call argument(s) not valid JSON (likely truncated, finish_reason="${finishReason ?? "?"}"): ${malformed.join("; ")}`);
+                            toolErrorParts.push(`tool call argument(s) not valid JSON (likely truncated, finish_reason="${finishReason ?? "?"}"${sentMaxTokens !== undefined ? `; request output cap in effect: ${sentMaxTokens} tokens — a cut mid-arguments commonly means the cap was hit` : ""}): ${malformed.join("; ")}`);
                         }
                         if (unnamed.length > 0) {
                             toolErrorParts.push(`tool call(s) arrived with no tool name and cannot be executed (finish_reason="${finishReason ?? "?"}"): ${unnamed.join("; ")}`);

package/dist/core/background-agent-store.d.ts

@@ -40,13 +40,14 @@ export interface BackgroundAgentRecord {
     errorCode?: string;
     errorRetryable?: boolean;
     errorKind?: string;
+    errorRetryAfterMs?: number;
     resultIsPartial?: boolean;
     recentSteps?: SubagentStep[];
     editedFiles?: SubagentEditedFile[];
     usage?: BackgroundAgentUsage;
     rev: number;
 }
-export declare const REVIVED_ROW_CLEARED_FIELDS: readonly ["settledAt", "stoppedBy", "completionId", "finalOutput", "finalOutputFull", "error", "errorCode", "errorRetryable", "errorKind", "resultIsPartial", "summary", "recentSteps", "editedFiles", "usage"];
+export declare const REVIVED_ROW_CLEARED_FIELDS: readonly ["settledAt", "stoppedBy", "completionId", "finalOutput", "finalOutputFull", "error", "errorCode", "errorRetryable", "errorKind", "errorRetryAfterMs", "resultIsPartial", "summary", "recentSteps", "editedFiles", "usage"];
 export declare function clearRevivedRowTerminalPayload(record: BackgroundAgentRecord): void;
 export interface BackgroundAgentRowSummary {
     handle: string;

package/dist/core/background-agent-store.js

@@ -9,6 +9,7 @@ export const REVIVED_ROW_CLEARED_FIELDS = [
     "errorCode",
     "errorRetryable",
     "errorKind",
+    "errorRetryAfterMs",
     "resultIsPartial",
     "summary",
     "recentSteps",

package/dist/core/checkpoint-store.d.ts

@@ -24,6 +24,7 @@ export interface RiskDescriptor {
         shell?: boolean;
     };
     toolName: string;
+    shellGateDoctrine?: "classify" | "always";
     summary?: string;
     touchedPaths?: string[];
 }
@@ -39,6 +40,7 @@ export declare function buildRiskDescriptor(input: {
     args: unknown;
     safety?: SafetyAxis;
     shellGated?: boolean;
+    shellGateDoctrine?: "classify" | "always";
 }): RiskDescriptor;
 export type CheckpointGate = {
     kind: "human";

package/dist/core/checkpoint-store.js

@@ -115,6 +115,7 @@ export function buildRiskDescriptor(input) {
             severity: riskSeverity(axes),
             axes,
             toolName,
+            ...(input.shellGated && input.shellGateDoctrine !== undefined ? { shellGateDoctrine: input.shellGateDoctrine } : {}),
             ...(summary !== undefined ? { summary } : {}),
             ...(touchedPaths !== undefined ? { touchedPaths } : {}),
         };

package/dist/core/runner/assemble-result.js

@@ -86,6 +86,15 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
         status = "failed";
         errorCode = "suspend.loop";
         errorMessage = "task suspended too many times (resume/restart loop) — exceeded the suspend limit";
+        const gates = stats.humanReview?.gates ?? [];
+        if (gates.length > 0 && gates.every((g) => g.decision === "allow")) {
+            errorMessage +=
+                `. Diagnosis: all ${gates.length} recorded gate decision(s) on this run were ALLOW — a gate that keeps ` +
+                    `asking combined with an approver that keeps approving consumes the suspend allowance on legitimate ` +
+                    `work. Remedies: answer asks at a LIVE onAsk (a synchronous allow parks nothing and consumes no ` +
+                    `suspend), keep provably-benign commands inside the read boundary so the classifier auto-allows them, ` +
+                    `or raise maxSuspends for genuinely approval-heavy tasks.`;
+        }
     }
     else if (flags.threw) {
         status = "failed";

package/dist/core/runner/prepare-task.d.ts

@@ -121,6 +121,7 @@ export interface Prepared {
     } | undefined;
     activeTools: Set<string>;
     deferredToolNames?: ReadonlySet<string>;
+    toolMaterializeStatic: boolean;
     memoryEngineSession?: {
         engine: MemoryEngine;
         handle: MemorySessionHandle;
@@ -134,6 +135,9 @@ export interface Prepared {
         scope?: string;
         restoreMode?: "snapshot" | "park_only";
     };
+    suspendProgressRef: {
+        executedApproved: boolean;
+    };
     reviewRef: {
         token?: CheckpointToken;
         gate?: CheckpointGate;

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

@@ -319,6 +319,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 +989,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 +1164,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 +1349,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 +1433,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 +1475,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 +1799,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 +2046,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 +2123,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 +2173,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);
@@ -3083,7 +3120,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 +3168,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 +3229,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 +3252,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 +3313,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 } : {}),
@@ -3636,7 +3674,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, 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

@@ -541,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
                         ? {
@@ -556,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)
@@ -1338,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) => {
@@ -1501,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) => {
@@ -1753,7 +1776,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 &&
@@ -2705,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 }));
@@ -3512,6 +3538,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);

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

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) {

package/dist/core/task-registry-agent.d.ts

@@ -69,6 +69,7 @@ export declare function settleBackgroundAgentLane(core: DurableAgentCore, id: st
     errorCode?: string;
     retryable?: boolean;
     errorKind?: string;
+    retryAfterMs?: number;
     stoppedBy?: StopSource;
     seq?: number;
     cycle?: number;
@@ -105,6 +106,7 @@ export declare function settleRevivedAgentLane(core: DurableAgentCore, id: strin
     errorCode?: string;
     retryable?: boolean;
     errorKind?: string;
+    retryAfterMs?: number;
 }): "completed" | "failed" | "killed" | undefined;
 export declare function noteBackgroundAgentActivityLane(core: DurableAgentCore, id: string, now?: number): void;
 export declare function reapStaleSessionBackgroundAgentsLane(core: DurableAgentCore, staleMs: number, now?: number, onTerminal?: (note: () => void) => void): number;
@@ -137,6 +139,7 @@ export interface AgentPollDetailsInput {
     error?: string;
     errorCode?: string;
     errorRetryable?: boolean;
+    errorRetryAfterMs?: number;
     resultIsPartial?: boolean;
     completionId?: string;
 }

package/dist/core/task-registry-agent.js

@@ -713,6 +713,8 @@ export function settleBackgroundAgentLane(core, id, outcome) {
             handle.errorRetryable = outcome.retryable;
         if (outcome.errorKind !== undefined)
             handle.errorKind = outcome.errorKind;
+        if (outcome.retryAfterMs !== undefined)
+            handle.errorRetryAfterMs = outcome.retryAfterMs;
     }
     handle.updatedAt = Date.now();
     if (outcome.seq !== undefined)
@@ -731,6 +733,7 @@ export function settleBackgroundAgentLane(core, id, outcome) {
         ...(handle.errorCode !== undefined ? { errorCode: handle.errorCode } : {}),
         ...(handle.errorRetryable !== undefined ? { errorRetryable: handle.errorRetryable } : {}),
         ...(handle.errorKind !== undefined ? { errorKind: handle.errorKind } : {}),
+        ...(handle.errorRetryAfterMs !== undefined ? { errorRetryAfterMs: handle.errorRetryAfterMs } : {}),
     }, ["parkedCheckpointToken", "parkClaimId", "parkedAt"]);
     return outcome.status;
 }
@@ -857,6 +860,7 @@ export function reviveBackgroundAgentLane(core, id, access, abort) {
     handle.errorCode = undefined;
     handle.errorRetryable = undefined;
     handle.errorKind = undefined;
+    handle.errorRetryAfterMs = undefined;
     handle.resultIsPartial = undefined;
     handle.stopSource = undefined;
     handle.completionId = undefined;
@@ -1052,6 +1056,7 @@ export function buildAgentPollDetails(input) {
         ...(failed && input.error !== undefined ? { error: delimitUntrusted("agent error", boundedRedactedSummary(input.error, 300)) } : {}),
         ...(failed && input.errorCode !== undefined ? { errorCode: input.errorCode } : {}),
         ...(failed && input.errorRetryable !== undefined ? { retryable: input.errorRetryable } : {}),
+        ...(failed && input.errorRetryAfterMs !== undefined ? { retryAfterMs: input.errorRetryAfterMs } : {}),
         ...(input.resultIsPartial === true ? { partial_result: true } : {}),
         ...(input.completionId !== undefined ? { completionId: input.completionId } : {}),
     };
@@ -1070,7 +1075,7 @@ The agent is durably suspended, waiting for an approval decision. It resumes whe
         };
     }
     const kindClause = row.status === "failed" && row.errorKind !== undefined && row.errorRetryable !== undefined
-        ? ` (error_kind: ${row.errorKind}, retryable: ${row.errorRetryable})`
+        ? ` (error_kind: ${row.errorKind}, retryable: ${row.errorRetryable}${row.errorRetryAfterMs !== undefined ? `, retry_after_ms: ${row.errorRetryAfterMs}` : ""})`
         : "";
     const body = `status: ${row.status}
 ${row.error ? `error: ${row.error}${kindClause}
@@ -1087,6 +1092,7 @@ ${clipTaskOutput(row.finalOutputFull ?? row.finalOutput)}` : "(no result text)"}
             ...(row.error !== undefined ? { error: row.error } : {}),
             ...(row.errorCode !== undefined ? { errorCode: row.errorCode } : {}),
             ...(row.errorRetryable !== undefined ? { errorRetryable: row.errorRetryable } : {}),
+            ...(row.errorRetryAfterMs !== undefined ? { errorRetryAfterMs: row.errorRetryAfterMs } : {}),
             ...(row.resultIsPartial === true ? { resultIsPartial: true } : {}),
             ...(row.completionId !== undefined ? { completionId: row.completionId } : {}),
         }),
@@ -1126,7 +1132,7 @@ The agent is durably suspended, waiting for an approval decision. It resumes whe
     const fullResult = handle.result ? (handle.resultFull ?? handle.result) : undefined;
     const resultText = fullResult !== undefined ? await spillClippedAgentResult(handle, fullResult, clipTaskOutput(fullResult, handle.outputFile), store, sessionId) : undefined;
     const kindClause = handle.status === "failed" && handle.errorKind !== undefined && handle.errorRetryable !== undefined
-        ? ` (error_kind: ${handle.errorKind}, retryable: ${handle.errorRetryable})`
+        ? ` (error_kind: ${handle.errorKind}, retryable: ${handle.errorRetryable}${handle.errorRetryAfterMs !== undefined ? `, retry_after_ms: ${handle.errorRetryAfterMs}` : ""})`
         : "";
     const body = running
         ? oneShot === true
@@ -1149,6 +1155,7 @@ ${resultText}` : "(no result text)"}`;
             ...(handle.error !== undefined ? { error: handle.error } : {}),
             ...(handle.errorCode !== undefined ? { errorCode: handle.errorCode } : {}),
             ...(handle.errorRetryable !== undefined ? { errorRetryable: handle.errorRetryable } : {}),
+            ...(handle.errorRetryAfterMs !== undefined ? { errorRetryAfterMs: handle.errorRetryAfterMs } : {}),
             ...(handle.resultIsPartial === true ? { resultIsPartial: true } : {}),
             ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
         }),

package/dist/core/task-registry-shared.d.ts

@@ -139,6 +139,7 @@ export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
     errorCode?: string;
     errorRetryable?: boolean;
     errorKind?: string;
+    errorRetryAfterMs?: number;
     resultIsPartial?: boolean;
     stopSource?: StopSource;
     stoppedBy?: StopSource;

package/dist/core/task-registry.d.ts

@@ -141,6 +141,7 @@ export declare class TaskRegistry {
         errorCode?: string;
         retryable?: boolean;
         errorKind?: string;
+        retryAfterMs?: number;
         stoppedBy?: StopSource;
         seq?: number;
         cycle?: number;
@@ -180,6 +181,7 @@ export declare class TaskRegistry {
         errorCode?: string;
         retryable?: boolean;
         errorKind?: string;
+        retryAfterMs?: number;
     }): "completed" | "failed" | "killed" | undefined;
     unmarkRetainedContinuation(id: string): void;
     attachAgentNotify(id: string, notify: NonNullable<BackgroundAgentTaskHandle["notify"]>, cycle?: number): void;

package/dist/core/trace.d.ts

@@ -94,6 +94,7 @@ export type TraceEvent = {
     kind: "config.additional_directory_skipped";
     version: 1;
     taskId: string;
+    field?: "additionalReadDirectories";
     entry: string;
     reason: string;
     ts: number;

package/dist/core/types.d.ts

@@ -109,6 +109,7 @@ export interface ToolExecuteContext {
     alwaysLoadTools?: readonly string[];
     promptProfile?: "simple" | "classic";
     additionalDirectories?: readonly string[];
+    additionalReadDirectories?: readonly string[];
     envFacts?: TaskSpec["envFacts"];
     getApiKeyAndHeaders?: TaskSpec["getApiKeyAndHeaders"];
     activeSkillScope?: () => readonly unknown[];
@@ -297,6 +298,7 @@ export interface TaskSpec {
     tools?: ToolSpec[];
     excludeTools?: string[];
     deferTools?: string[];
+    toolMaterializeStrategy?: "swap" | "static";
     alwaysLoadTools?: string[];
     deferSelfResolve?: boolean;
     promptProfile?: "simple" | "classic";
@@ -325,6 +327,7 @@ export interface TaskSpec {
     checkpointStore?: import("./checkpoint-store.js").CheckpointStore | null;
     handsReadOnly?: boolean;
     additionalDirectories?: string[];
+    additionalReadDirectories?: string[];
     enablePlanMode?: boolean;
     interactiveTools?: boolean;
     enableFork?: boolean;

package/dist/prompts/default.d.ts

@@ -27,6 +27,7 @@ export interface EnvironmentFacts {
     gitWorktreeRoot?: string;
     isLinkedWorktree?: boolean;
     additionalDirectories?: readonly string[];
+    additionalReadDirectories?: readonly string[];
     platform?: string;
     osVersion?: string;
     shell?: string;

package/dist/prompts/default.js

@@ -237,6 +237,9 @@ export function buildEnvironmentContext(facts) {
     if (facts.additionalDirectories && facts.additionalDirectories.length > 0) {
         lines.push(`Additional working directories: ${facts.additionalDirectories.map((d) => inlineUntrusted(d)).join(", ")}`);
     }
+    if (facts.additionalReadDirectories && facts.additionalReadDirectories.length > 0) {
+        lines.push(`Additional read-only directories: ${facts.additionalReadDirectories.map((d) => inlineUntrusted(d)).join(", ")}`);
+    }
     if (facts.isGitRepo !== undefined)
         lines.push(`Is a git repository: ${facts.isGitRepo ? "yes" : "no"}`);
     if (facts.gitBranch)

package/dist/tools/fs/fs-bash.js

@@ -296,9 +296,12 @@ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, c
             const captured = (pStdout ? `--- partial stdout ---\n${pStdout}` : "") +
                 (pStderr ? `${pStdout ? "\n" : ""}--- partial stderr ---\n${pStderr}` : "");
             const zeroOutput = captured.length === 0;
+            const zeroOutputHint = res.error.code === "timeout" && timeout >= 60
+                ? ` — the process ran the full ${timeout}s without writing to its stdio; it may have been stalled before producing output, or holding it in a block buffer`
+                : "";
             const body = !zeroOutput
                 ? `\n${delimitUntrusted("partial command output", captured)}`
-                : `\n(no output was produced before the cutoff)`;
+                : `\n(no output was produced before the cutoff${zeroOutputHint})`;
             const overflowNote = cutOverflowFile !== undefined ? shellRecoveryHint(cutOverflowFile, readOnly) : "";
             return {
                 content: `Error (${toolName}): ${headline}${body}${overflowNote}`,

package/dist/tools/fs/index.d.ts

@@ -13,6 +13,7 @@ export * from "./fs-bash.js";
 import { type CwdRef, type ReadImageDownsamplerOption } from "./fs-shared.js";
 export interface HandsToolkitOptions {
     additionalRoots?: readonly string[];
+    additionalReadRoots?: readonly string[];
     includeShell?: boolean;
     readOnly?: boolean;
     bashReadonlyAllow?: readonly string[];

package/dist/tools/fs/index.js

@@ -16,7 +16,10 @@ import { createEditFileTool, createWriteFileTool, createNotebookEditTool } from
 import { createGrepTool, createGlobTool } from "./fs-search-tools.js";
 import { createBashTool, createBashReadonlyTool, createEnvTaskOutputTool, createEnvTaskStopTool } from "./fs-bash.js";
 export function createHandsToolkit(env, readFileState, rootCanonical, opts = {}) {
-    const { includeShell = false, readOnly = false, bashReadonlyAllow, commitCoAuthor = false, mountBackgroundTaskTools = true, additionalRoots, } = opts;
+    const { includeShell = false, readOnly = false, bashReadonlyAllow, commitCoAuthor = false, mountBackgroundTaskTools = true, additionalRoots, additionalReadRoots, } = opts;
+    const readFaceRoots = additionalReadRoots === undefined || additionalReadRoots.length === 0
+        ? additionalRoots
+        : [...(additionalRoots ?? []), ...additionalReadRoots];
     const cwdRef = opts.cwdRef ?? { current: rootCanonical };
     const bgReadRegistry = opts.taskRegistry;
     const bgOutputReadExemption = bgReadRegistry === undefined
@@ -27,18 +30,18 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
             ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
         }, env);
     const tools = [
-        createReadFileTool(env, readFileState, rootCanonical, readOnly ? undefined : cwdRef, additionalRoots, opts.readImageDownsampler, opts.pdfModelCapabilities, bgOutputReadExemption),
+        createReadFileTool(env, readFileState, rootCanonical, readOnly ? undefined : cwdRef, readFaceRoots, opts.readImageDownsampler, opts.pdfModelCapabilities, bgOutputReadExemption),
     ];
     if (!readOnly) {
         tools.push(createEditFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite), createWriteFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite), createNotebookEditTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite));
     }
-    tools.push(createGrepTool(env, rootCanonical, additionalRoots), createGlobTool(env, rootCanonical, additionalRoots), createRepoMapTool(env, rootCanonical, additionalRoots));
+    tools.push(createGrepTool(env, rootCanonical, readFaceRoots), createGlobTool(env, rootCanonical, readFaceRoots), createRepoMapTool(env, rootCanonical, readFaceRoots));
     if (includeShell) {
         tools.push(readOnly
             ? createBashReadonlyTool(env, rootCanonical, new Set(bashReadonlyAllow ?? BASH_READONLY_DEFAULT_ALLOW), {
                 ...(opts.bashDefaultTimeoutMs !== undefined ? { bashDefaultTimeoutMs: opts.bashDefaultTimeoutMs } : {}),
                 ...(opts.bashMaxTimeoutMs !== undefined ? { bashMaxTimeoutMs: opts.bashMaxTimeoutMs } : {}),
-                ...(additionalRoots !== undefined ? { additionalRoots } : {}),
+                ...(readFaceRoots !== undefined ? { additionalRoots: readFaceRoots } : {}),
             })
             : createBashTool(env, rootCanonical, commitCoAuthor, cwdRef, {
                 taskRegistry: opts.taskRegistry,

package/dist/tools/web.d.ts

@@ -9,17 +9,37 @@ export interface WebFetchConfig {
     summarize?: (content: string, prompt: string, signal?: AbortSignal) => Promise<string | {
         text: string;
         truncated?: boolean;
+        inputTruncated?: boolean;
+        inputChars?: number;
+        usedChars?: number;
     }>;
     userAgent?: string;
 }
+export declare const WEBFETCH_GROUNDING_MIN_TEXT_CHARS = 200;
+export interface WebFetchGrounding {
+    level: "ok" | "low";
+    textChars: number;
+    bytes: number;
+    textRatio: number;
+}
 export declare function htmlToText(html: string): string;
 export declare function webFetchToolSpec(config?: WebFetchConfig): ToolSpec;
 export declare function createWebFetchTool(config?: WebFetchConfig): AgentTool;
 export declare const WEBFETCH_SUMMARY_MAX_CONTENT = 100000;
 export declare const WEBFETCH_SUMMARY_GUIDELINES: string;
-export declare function createWebFetchSummarizer(brain: Brain, model: Model): (content: string, prompt: string, signal?: AbortSignal) => Promise<string | {
+export declare const WEBFETCH_SUMMARY_GROUNDING_CLAUSE: string;
+export declare const WEBFETCH_SUMMARY_INPUT_HEADROOM = 0.8;
+export declare const WEBFETCH_SUMMARY_MIN_CONTENT = 4000;
+export declare function resolveSummaryInputChars(model: Model, override?: number): number;
+export interface WebFetchSummarizerOptions {
+    maxContentChars?: number;
+}
+export declare function createWebFetchSummarizer(brain: Brain, model: Model, options?: WebFetchSummarizerOptions): (content: string, prompt: string, signal?: AbortSignal) => Promise<string | {
     text: string;
     truncated?: boolean;
+    inputTruncated?: boolean;
+    inputChars?: number;
+    usedChars?: number;
 }>;
 export interface WebSearchConfig {
     search: (query: string, signal?: AbortSignal, opts?: {

package/dist/tools/web.js

@@ -25,6 +25,25 @@ function resolveWebMaxBytes(value) {
     }
     return value;
 }
+export const WEBFETCH_GROUNDING_MIN_TEXT_CHARS = 200;
+const GROUNDING_MIN_TEXT_RATIO = 0.01;
+const GROUNDING_RATIO_MAX_TEXT_CHARS = 2_000;
+const GROUNDING_ECHO_MAX_CHARS = GROUNDING_RATIO_MAX_TEXT_CHARS + 100;
+const GROUNDING_SHELL_MIN_BYTES = 500;
+function assessGrounding(text, bytes) {
+    const textChars = text.replace(/\s+/g, " ").trim().length;
+    const textRatio = bytes > 0 ? (textChars / bytes) : 0;
+    const low = textChars < WEBFETCH_GROUNDING_MIN_TEXT_CHARS ||
+        (textChars < GROUNDING_RATIO_MAX_TEXT_CHARS && bytes > 0 && textRatio < GROUNDING_MIN_TEXT_RATIO);
+    return { level: low ? "low" : "ok", textChars, bytes, textRatio: Math.round(textRatio * 1000) / 1000 };
+}
+function recoveryToolRuledOut(ctx, toolName) {
+    if (ctx.excludeTools?.includes(toolName) ?? false)
+        return true;
+    const deferred = ctx.deferTools?.includes(toolName) ?? false;
+    const pinnedInline = ctx.alwaysLoadTools?.includes(toolName) ?? false;
+    return deferred && !pinnedInline;
+}
 const DEFAULT_FETCH_TIMEOUT_MS = 30_000;
 const ERROR_BODY_EXCERPT_CHARS = 2048;
 const ERROR_BODY_CONVERT_MAX_CHARS = 64 * 1024;
@@ -471,10 +490,14 @@ export function webFetchToolSpec(config = {}) {
                         : bodyCut
                             ? `\n\n[WebFetch: ${cutPhrase} — the ${bodyBytes.length} bytes are a partial prefix received before the cutoff, NOT the object's full size]`
                             : "";
+                    const shellRecoveryRuledOut = recoveryToolRuledOut(ctx, "Bash") || ctx.handsReadOnly === true;
+                    const recoveryLine = shellRecoveryRuledOut
+                        ? "Retrieve it outside this tool — this run has no shell capability that can download it to a file."
+                        : `Download and inspect it with Bash instead, e.g.: curl -L -o /tmp/download "${parsed.toString()}"`;
                     return {
                         content: `Error (WebFetch): binary content detected (${kind}${mt && signature ? `, content-type: ${mt}` : ""}, ` +
                             `${bodyBytes.length} bytes) — the body was NOT added to the context (it does not decode as text). ` +
-                            `Download and inspect it with Bash instead, e.g.: curl -L -o /tmp/download "${parsed.toString()}"` +
+                            recoveryLine +
                             binaryStateNote,
                         details: {
                             type: "web-fetch",
@@ -503,8 +526,11 @@ export function webFetchToolSpec(config = {}) {
                 raw = raw.slice(0, maxBytes);
             }
             const text = /html/i.test(contentType) || /^\s*</.test(raw) ? htmlToText(raw) : raw;
+            const grounding = assessGrounding(text, bodyBytes ? bodyBytes.length : raw.length);
             let out = text;
             let summaryTruncated = false;
+            let summaryApplied = false;
+            let summaryInputNote;
             let note;
             if (prompt && bodyCut) {
                 note =
@@ -516,13 +542,24 @@ export function webFetchToolSpec(config = {}) {
                     const summarized = await config.summarize(text, prompt, ctx.signal);
                     if (typeof summarized === "string") {
                         out = summarized;
+                        summaryApplied = true;
                     }
                     else {
                         out = summarized.text;
+                        summaryApplied = true;
                         if (summarized.truncated) {
                             summaryTruncated = true;
                             note = `[note: the summary below is INCOMPLETE — the summarizer hit its output limit before finishing]`;
                         }
+                        if (summarized.inputTruncated) {
+                            const sizes = summarized.usedChars !== undefined && summarized.inputChars !== undefined
+                                ? ` (only the first ${summarized.usedChars} of ${summarized.inputChars} characters were read)`
+                                : "";
+                            summaryInputNote =
+                                `[note: the summary below covers only the BEGINNING of the page${sizes} — the page exceeded what the ` +
+                                    `summarizer could feed its model, so the rest was never read. Absence of something from the summary ` +
+                                    `does NOT mean it is absent from the page.]`;
+                        }
                     }
                 }
                 catch (e) {
@@ -537,12 +574,44 @@ export function webFetchToolSpec(config = {}) {
                     `[note: summarization unavailable in this deployment — raw page content follows; ` +
                         `the requested analysis ("${inlineUntrusted(prompt, 120)}") was NOT applied]`;
             }
+            const bodyIncomplete = truncationNote !== "" || bodyCut !== undefined;
+            let groundingNote;
+            let sourceEcho = "";
+            if (grounding.level === "low") {
+                const shellShape = /html/i.test(contentType) && grounding.bytes >= GROUNDING_SHELL_MIN_BYTES
+                    ? bodyIncomplete
+                        ? " The retrieved bytes are almost entirely markup/script — which is either a client-rendered shell or " +
+                            "simply the head of a document whose content sits past the retrieved prefix; a larger byte limit (or a " +
+                            "completed transfer) would distinguish the two."
+                        : " The retrieved bytes are almost entirely markup/script, which is the shape of a page whose content is " +
+                            "loaded by JavaScript after the document — this tool does not run JavaScript, so that content was never present."
+                    : "";
+                const nothingExtractable = grounding.textChars === 0;
+                const sourceLabel = bodyIncomplete ? "extracted text of the retrieved prefix" : "complete extracted page text";
+                const head = `[WebFetch grounding: LOW — the ${bodyIncomplete ? "retrieved prefix" : "page"} yielded ` +
+                    (nothingExtractable ? "NO extractable text at all" : `only ${grounding.textChars} characters of extractable text`) +
+                    ` out of ${grounding.bytes} retrieved bytes`;
+                groundingNote = summaryApplied
+                    ? `${head}. ` +
+                        (nothingExtractable
+                            ? `There is no source text at all, so every specific claim in the summary below is unsourced — do not use it as a factual source.`
+                            : `That may be all this URL serves, or it may be a page whose content is not present in the fetched bytes — this tool ` +
+                                `cannot tell the two apart, so the summary below is NOT usable as a source on its own: check every specific claim ` +
+                                `in it against the ${sourceLabel} reproduced after it.`) +
+                        shellShape +
+                        `]`
+                    : `${head}; the content below is ${bodyIncomplete ? "all the retrieved prefix yielded" : "all of it"}.${shellShape}]`;
+                if (summaryApplied && !nothingExtractable) {
+                    sourceEcho = `\n\n${delimitUntrusted(`WebFetch ${parsed.hostname} — ${sourceLabel}`, text.replace(/\s+/g, " ").trim(), GROUNDING_ECHO_MAX_CHARS)}`;
+                }
+            }
             const fenced = delimitUntrusted(`WebFetch ${parsed.hostname}`, out);
-            const withNote = note ? `${note}\n\n${fenced}` : fenced;
+            const headNotes = [groundingNote, note, summaryInputNote].filter((n) => n !== undefined);
+            const withNote = headNotes.length > 0 ? `${headNotes.join("\n\n")}\n\n${fenced}` : fenced;
             const partialNote = bodyCut
                 ? `\n\n[WebFetch: ${cutPhrase} — the content above is PARTIAL: ${bodyBytes?.length ?? 0} bytes were received before the cutoff and the tail is missing. Treat absent information as unfetched, not absent from the source.]`
                 : "";
-            const modelText = withNote + truncationNote + partialNote;
+            const modelText = withNote + truncationNote + partialNote + sourceEcho;
             const RESULT_PREVIEW_CHARS = 8_000;
             return {
                 content: modelText,
@@ -554,7 +623,9 @@ export function webFetchToolSpec(config = {}) {
                     bytes: bodyBytes ? bodyBytes.length : raw.length,
                     result: out.length > RESULT_PREVIEW_CHARS ? `${out.slice(0, RESULT_PREVIEW_CHARS)}\n…[${out.length - RESULT_PREVIEW_CHARS} chars truncated — full text in the tool output]` : out,
                     durationMs: Date.now() - startedAt,
-                    ...(truncationNote || summaryTruncated ? { truncated: true } : {}),
+                    ...(truncationNote || summaryTruncated || summaryInputNote ? { truncated: true } : {}),
+                    grounding,
+                    ...(summaryInputNote ? { summaryInputTruncated: true } : {}),
                     ...transferStateDetails,
                 },
             };
@@ -570,12 +641,50 @@ export const WEBFETCH_SUMMARY_GUIDELINES = `Provide a concise response based onl
     ` - Use quotation marks for exact language from articles; any language outside of the quotation should never be word-for-word the same.\n` +
     ` - You are not a lawyer and never comment on the legality of your own prompts and responses.\n` +
     ` - Never produce or reproduce exact song lyrics.\n`;
-export function createWebFetchSummarizer(brain, model) {
+export const WEBFETCH_SUMMARY_GROUNDING_CLAUSE = `Ground every statement in the content above:\n` +
+    ` - If the content does not contain what was asked for, say exactly that and describe what the content IS instead. Never fill the gap with general knowledge or plausible inference.\n` +
+    ` - If the content is a listing (file names, links, titles) rather than the data itself, a name is evidence only about naming — do not conclude from names alone that the underlying resource does or does not contain something; report what the listing shows and what would have to be opened to answer.\n`;
+export const WEBFETCH_SUMMARY_INPUT_HEADROOM = 0.8;
+export const WEBFETCH_SUMMARY_MIN_CONTENT = 4_000;
+const SUMMARY_PROMPT_OVERHEAD_TOKENS = 1_000;
+const SUMMARY_PROMPT_ALLOWANCE_CHARS = 2_000;
+const SUMMARY_MIN_CONTENT_PER_CALL = 1_024;
+function invalidSummaryBudget(message) {
+    const e = new Error(message);
+    e.code = "config.web_summary_max_content_invalid";
+    return e;
+}
+export function resolveSummaryInputChars(model, override) {
+    if (override !== undefined) {
+        if (!Number.isFinite(override) || override < 1) {
+            throw invalidSummaryBudget(`WebFetch summarizer maxContentChars must be a finite number of characters >= 1 (got ${String(override)})`);
+        }
+        return Math.floor(override);
+    }
+    const window = model.contextTokens ?? model.contextWindow;
+    const charsPerToken = model.charsPerToken ?? 4;
+    for (const [name, value] of [
+        ["contextTokens/contextWindow", window],
+        ["maxTokens", model.maxTokens],
+        ["charsPerToken", charsPerToken],
+    ]) {
+        if (!Number.isFinite(value) || value <= 0) {
+            throw invalidSummaryBudget(`WebFetch summarizer cannot size its input: model "${model.id}" declares a non-finite or non-positive ${name} (got ${String(value)})`);
+        }
+    }
+    const reservedOutputTokens = Math.min(model.maxTokens, Math.floor(window / 4));
+    const inputTokens = window - reservedOutputTokens - SUMMARY_PROMPT_OVERHEAD_TOKENS;
+    const derived = Math.floor(inputTokens * charsPerToken * WEBFETCH_SUMMARY_INPUT_HEADROOM);
+    return Math.min(WEBFETCH_SUMMARY_MAX_CONTENT, Math.max(WEBFETCH_SUMMARY_MIN_CONTENT, derived));
+}
+export function createWebFetchSummarizer(brain, model, options = {}) {
+    const maxContentChars = resolveSummaryInputChars(model, options.maxContentChars);
     return async (content, prompt, signal) => {
-        const truncated = content.length > WEBFETCH_SUMMARY_MAX_CONTENT
-            ? content.slice(0, WEBFETCH_SUMMARY_MAX_CONTENT) + "\n\n[Content truncated due to length...]"
-            : content;
-        const userPrompt = `\nWeb page content:\n---\n${truncated}\n---\n\n${prompt}\n\n` + WEBFETCH_SUMMARY_GUIDELINES;
+        const promptOverflow = Math.max(0, prompt.length - SUMMARY_PROMPT_ALLOWANCE_CHARS);
+        const budget = promptOverflow === 0 ? maxContentChars : Math.max(SUMMARY_MIN_CONTENT_PER_CALL, maxContentChars - promptOverflow);
+        const inputTruncated = content.length > budget;
+        const truncated = inputTruncated ? content.slice(0, budget) + "\n\n[Content truncated due to length...]" : content;
+        const userPrompt = `\nWeb page content:\n---\n${truncated}\n---\n\n${prompt}\n\n` + WEBFETCH_SUMMARY_GROUNDING_CLAUSE + "\n" + WEBFETCH_SUMMARY_GUIDELINES;
         const context = { messages: [{ role: "user", content: userPrompt, timestamp: Date.now() }] };
         const msg = brain.complete
             ? await brain.complete(model, context, { signal })
@@ -590,7 +699,14 @@ export function createWebFetchSummarizer(brain, model) {
             .trim();
         if (!text)
             throw new Error("summarizer returned no text");
-        return msg.stopReason === "length" || msg.partialFinalized === true ? { text, truncated: true } : text;
+        const outputTruncated = msg.stopReason === "length" || msg.partialFinalized === true;
+        if (!outputTruncated && !inputTruncated)
+            return text;
+        return {
+            text,
+            ...(outputTruncated ? { truncated: true } : {}),
+            ...(inputTruncated ? { inputTruncated: true, inputChars: content.length, usedChars: budget } : {}),
+        };
     };
 }
 const DEFAULT_SEARCH_TIMEOUT_MS = 30_000;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.10.0",
+  "version": "5.11.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",