@sema-agent/core 5.5.0 → 5.7.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 5.7.0 (2026-08-04)
+
+_Three collected cars: a parked question is answered by the decision itself (behavior face — see the consumer note), a descendant's terminal notification anchors on the delegation tree, and the env scrub stops deleting infrastructure key names (behavior face)._
+
+### Fixed
+
+- A descendant background agent's terminal notification now anchors on the delegation tree instead of dying with its spawner. A background agent notifies through the injector of the run that spawned it, and that injector parked on that run's OWN session once its lane was gone — so a grandchild launched from a delegated run (root → child A → background grandchild B; A completes, B settles later) parked its terminal on a throwaway child session that never runs again, and the root conversation was never told (the data was never lost — `TaskOutput` still answered; the gap was purely the push face). A delegated agent's TERMINAL frame now also escalates one hop up the delegation chain: a live ancestor takes it in its current run, a dead one repeats the decision one level higher, and the walk ends at the tree root; without a chain link the recorded root anchor is used directly. Strictly additive: the own-session park is kept (a retained child session later resumed still receives what it always received), the live lane is untouched, and every other notification class (shell completions, SendMessage deliveries, external `notify()` events) stays addressed to its own session. A delegated run that can reach neither an uplink nor a root anchor still parks (fail-open) and discloses once (`degraded` / `descendant-terminal-unrouted`).
+
+- The env scrub no longer deletes infrastructure key names. `SECRET_ENV_RE`'s bare `KEY` word matched `PARTITION_KEY` / `SORT_KEY` / `RANGE_KEY` / `IDEMPOTENCY_KEY` / `CACHE_KEY` / `ROUTING_KEY`, and `scrubSecretEnv` DELETES what it matches — a spawned child silently lost variables that carry no credential (writes to a wrong partition, a routing key nothing binds). The word itself cannot be withdrawn (`API_KEY` / `SECRET_KEY` / `PRIVATE_KEY` / `ACCESS_KEY` are the bulk of real credential names), so the fix is the mirror of the existing positive exact-name list: `NON_SECRET_ENV_EXACT_NAMES`, exact names (never a shape — a pattern exemption would be a bypass) confirmed non-credential, consulted before the shape rule with the credential list read first (a name on both lists resolves to the credential reading). An exempted entry is kept and mints no finding. Decorated variants (`USERS_SORT_KEY`, `SORT_KEY_2`) are still dropped. **Consumers pinning the old shape**: a probe asserting `isSecretEnvKey("SORT_KEY") === true`, or that a scrub drops one of the six exempt names, now reads the opposite answer.
+
+### Added
+
+- A durable question can be answered by the decision itself. `ResumeOutcome`'s `policy_ask` arm takes an optional `answer` (a `QuestionAnswer`) when the checkpoint's pending call is the reserved `AskUserQuestion` tool; the resume binds it as the resumed leg's answering face, so the pending call executes against the operator's actual selections. This is the same wiring the documented live arm builds by hand (`resume(token, outcome, { ...config, onQuestion: async () => answer })`) — but minted from the payload, which is the only route available to a caller redeeming an **offline background child**: the revive drive rebuilds that leg's config from the parked row and has no seat to put a closure in, so approving a parked question used to feed the model a fabricated "no human is available" default. The answer is untrusted wire data throughout: it goes through the existing answer fence unchanged (`selected ⊆ options` for the trusted line, off-list values and free-text `note` in a data fence), so multi-select and "Other" free text behave identically on both arms. The binding is one-shot — it answers the decided call only; a new question on the resumed leg is not fed the old answer. The answer is also recorded on the persisted winner, so an `env_failed` reopen must replay the identical answer (a replay may not keep the verdict and swap the text).
+
+### Changed
+
+- **Behavior face** — approving a durable question without an answer is now refused instead of consumed. A `policy_ask` `allow` whose pending call is the reserved question tool is rejected **pre-CAS** (`checkpoint.invalid_outcome`, `detail.field: "answer"`, the checkpoint stays `pending` and redeemable) when it carries neither an `answer` nor a live answering face — where "live" excludes the reserved `QUESTION_AWAITS_RESUME` placeholder, whose contract is that it must never run. Previously that shape consumed the human's approval and let the run finish on a fabricated default (or, with the placeholder, on its config error) with nothing left to redeem. A resume that supplies its own real `onQuestion` is unaffected; so is every non-question approval. Symmetrically, an `answer` attached to a decision that cannot carry one (a `deny`, or a pending call that is not the question tool) is rejected the same way rather than silently dropped. **Consumers pinning the old shape**: a probe that approved a parked question with a bare allow now gets a typed rejection — supply the answer on the outcome, or deny.
+
+## 5.6.0 (2026-08-03)
+
+_A hardening tail: numeric knobs refuse what they cannot honor, the binary gate reads bytes instead of trusting statistics, and the MCP SDK takes its last zero-cost step before the v2 jump._
+
+### Fixed
+
+- Stall-timeout knobs (`connectTimeoutMs` / `firstTokenTimeoutMs` / `idleTimeoutMs`) refuse invalid numbers loudly (`config.stall_timeout_invalid`) instead of silently disarming — a NaN (units fumble: `"120s"` → `Number` → NaN) used to read as "unset", switching every watchdog OFF exactly when a deployment meant to tighten them. `0` stays legal as an explicit off; absent stays absent.
+
+- Read's binary-extension list gains magic-byte criteria of its own (~40 formats, one data-driven signature table): a file whose bytes carry a real binary header (ZIP/gzip/7z/ELF/tar/RIFF…) is now refused by CONTENT even when printable padding used to slip it past the statistical sniffer as mojibake "text". Names still never decide: a `.zip` holding plain text still reads. The Edit/Write/NotebookEdit read-refusal texts all name the same escape route (one constant; NotebookEdit used to render the bare sentence with no hint at all).
+
+### Changed
+
+- `@modelcontextprotocol/sdk` 1.29.0 → 1.30.0 (exact pin). Public surface is purely additive upstream (stdio `maxBufferSize`, SSE `keepAliveMs`); `types` is byte-identical; the only behavior delta is a richer zod parse-error message the engine never pins on. Groundwork for the v2 three-package migration (spiked, GO, waiting out the first patch release).
+
 ## 5.5.0 (2026-08-03)
 
 _Three follow-through items: the deferred-placeholder wrong-guess round trip halves, durable cron jobs survive their creating session, and the redaction findings channel closes its last three audit gaps._

package/dist/brain/stream-engine.js

@@ -2,7 +2,7 @@ import { createAssistantMessageEventStream, } from "../internal/llm.js";
 import { BrainError, classifyHttp, describeNetworkError } from "./errors.js";
 import { retryBackoffMs } from "./retry.js";
 import { emitBrainStatus, emitBrainTelemetry } from "./status-sink.js";
-import { createConnectController } from "./timeout.js";
+import { createConnectController, resolveStallTimeoutMs } from "./timeout.js";
 import { WALLTIME_CUTOFF_MESSAGE } from "./walltime.js";
 const DEFAULT_MAX_RETRIES = 10;
 const MAX_RETRIES_ENV_CEILING = 15;
@@ -113,9 +113,9 @@ export function runStreamingBrain(args) {
         const req = buildRequest();
         const maxRetries = resolveMaxRetries(config.maxRetries);
         const baseDelay = config.retryDelayMs ?? 500;
-        const firstTokenTimeoutMs = config.firstTokenTimeoutMs ?? stallTimeouts?.firstTokenMs;
-        const idleTimeoutMs = config.idleTimeoutMs ?? stallTimeouts?.idleMs;
-        const connectTimeoutMs = config.connectTimeoutMs ?? stallTimeouts?.connectMs;
+        const firstTokenTimeoutMs = resolveStallTimeoutMs(config.firstTokenTimeoutMs ?? stallTimeouts?.firstTokenMs, "firstTokenTimeoutMs");
+        const idleTimeoutMs = resolveStallTimeoutMs(config.idleTimeoutMs ?? stallTimeouts?.idleMs, "idleTimeoutMs");
+        const connectTimeoutMs = resolveStallTimeoutMs(config.connectTimeoutMs ?? stallTimeouts?.connectMs, "connectTimeoutMs");
         let attempt = 0;
         let thinkingRetries = 0;
         let startEmitted = false;

package/dist/brain/timeout.d.ts

@@ -1,4 +1,5 @@
 import type { StreamFn } from "../internal/llm.js";
+export declare function resolveStallTimeoutMs(value: number | undefined, knob: string): number | undefined;
 export interface BrainTimeoutConfig {
     connectTimeoutMs?: number;
     firstTokenTimeoutMs?: number;

package/dist/brain/timeout.js

@@ -1,3 +1,13 @@
+export function resolveStallTimeoutMs(value, knob) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isFinite(value) || value < 0) {
+        const e = new Error(`${knob} must be a non-negative finite number of milliseconds (got ${String(value)})`);
+        e.code = "config.stall_timeout_invalid";
+        throw e;
+    }
+    return value;
+}
 export function createConnectController(connectTimeoutMs, outerSignal, deadlineAtMs) {
     const ac = new AbortController();
     let timedOut = false;

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

@@ -1,3 +1,4 @@
+import { type QuestionAnswer } from "./ask-question.js";
 import type { ReadEntry } from "../tools/fs/safety.js";
 import type { RepairBundle } from "../agents/repair-loop.js";
 import type { WorkspaceHandle } from "./remote-env.js";
@@ -68,6 +69,7 @@ export type ResumeOutcome = {
     decision: "allow" | "deny";
     updatedInput?: unknown;
     reason?: string;
+    answer?: QuestionAnswer;
 } | {
     gate: "resource_limit";
     decision: "continue";
@@ -180,6 +182,7 @@ export interface ResolvedOutcome {
     boundCallId: string;
     decision: "allow" | "deny" | "approve" | "reject" | "edit";
     updatedInput?: unknown;
+    answer?: QuestionAnswer;
 }
 export type ReopenReason = "env_failed" | "tool_unavailable";
 export interface ResolveExpectation {
@@ -241,10 +244,10 @@ export declare function summarizeCheckpoint(cp: Checkpoint): CheckpointSummary;
 export declare class CheckpointError extends Error {
     readonly code: "checkpoint.already_exists" | "checkpoint.already_resolved" | "checkpoint.not_found" | "checkpoint.gate_mismatch" | "checkpoint.resume_aborted" | "checkpoint.invalid_outcome" | "checkpoint.unsupported_version" | "checkpoint.reopen_revote" | "checkpoint.reopened_concurrently" | "checkpoint.reopen_failed" | "steering.invalid_content" | "wake.gate_pending" | "wake.nothing_to_deliver" | "resume.parent_constraint_missing" | "resume.parent_constraint_mismatch";
     readonly detail?: {
-        field?: "boundCallId" | "boundInputHash";
+        field?: "boundCallId" | "boundInputHash" | "answer";
     } | undefined;
     constructor(code: "checkpoint.already_exists" | "checkpoint.already_resolved" | "checkpoint.not_found" | "checkpoint.gate_mismatch" | "checkpoint.resume_aborted" | "checkpoint.invalid_outcome" | "checkpoint.unsupported_version" | "checkpoint.reopen_revote" | "checkpoint.reopened_concurrently" | "checkpoint.reopen_failed" | "steering.invalid_content" | "wake.gate_pending" | "wake.nothing_to_deliver" | "resume.parent_constraint_missing" | "resume.parent_constraint_mismatch", message: string, detail?: {
-        field?: "boundCallId" | "boundInputHash";
+        field?: "boundCallId" | "boundInputHash" | "answer";
     } | undefined);
 }
 export interface CheckpointStore {

package/dist/core/checkpoint-store.js

@@ -223,9 +223,12 @@ export function winnerFromOutcome(outcome) {
     }
     if (outcome.gate !== "policy_ask")
         return undefined;
-    return outcome.updatedInput === undefined
-        ? { boundCallId: outcome.boundCallId, decision: outcome.decision }
-        : { boundCallId: outcome.boundCallId, decision: outcome.decision, updatedInput: outcome.updatedInput };
+    return {
+        boundCallId: outcome.boundCallId,
+        decision: outcome.decision,
+        ...(outcome.updatedInput === undefined ? {} : { updatedInput: outcome.updatedInput }),
+        ...(outcome.answer === undefined ? {} : { answer: outcome.answer }),
+    };
 }
 export function validatePendingSteer(steer) {
     if (sanitizeUntrustedText(steer.text) !== steer.text) {

package/dist/core/runner/runtask.js

@@ -5,7 +5,7 @@ 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, isCompactionWalltimeAbort, maybeCompact, nextTrimForceBackoff, recordCompactionAndCheckRapidRefill } from "../auto-compaction.js";
-import { ASK_USER_QUESTION_TOOL_NAME } from "../ask-question.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";
 import { emitTaskOutcome } from "../task-outcome.js";
@@ -38,7 +38,7 @@ import { RunnerSharedToolResultStore } from "../tool-result-store.js";
 import { formatDiagnosticsBlock } from "../lsp-diagnostics.js";
 import { refuseOutOfContractDecision, toolPolicyNameSets } from "../tool-policy.js";
 import { defaultTaskRegistry } from "../task-registry.js";
-import { discloseDroppedPending, PendingSessionNotifications, renderTaskNotificationXml, SystemInjectionQueue, taskNotificationDedupKey } from "../task-notification.js";
+import { discloseDroppedPending, isDelegatedAgentTerminal, PendingSessionNotifications, renderTaskNotificationXml, SystemInjectionQueue, taskNotificationDedupKey } from "../task-notification.js";
 import { ToolDetachHub } from "../tool-detach.js";
 import { workflowSizeGuidelineChangeNotice } from "../../orchestration/workflow-size-guideline.js";
 import { DEFAULT_MAX_TURNS } from "../../config/defaults.js";
@@ -135,7 +135,24 @@ function deepJsonEqual(a, b) {
     return aKeys.every((k) => Object.prototype.hasOwnProperty.call(bo, k) && deepJsonEqual(ao[k], bo[k]));
 }
 function sameWinner(a, b) {
-    return a.boundCallId === b.boundCallId && a.decision === b.decision && deepJsonEqual(a.updatedInput, b.updatedInput);
+    return (a.boundCallId === b.boundCallId &&
+        a.decision === b.decision &&
+        deepJsonEqual(a.updatedInput, b.updatedInput) &&
+        deepJsonEqual(a.answer, b.answer));
+}
+function pendingContentAskCallId(cp) {
+    return cp.pendingAction.kind === "tool_approval" && cp.pendingAction.toolName === ASK_USER_QUESTION_TOOL_NAME
+        ? cp.pendingAction.toolCallId
+        : undefined;
+}
+function answerFaceForRedeemedCall(answer, redeemedCallId, base) {
+    return async (req, signal) => {
+        if (req.toolCallId === redeemedCallId)
+            return answer;
+        if (base !== undefined)
+            return base(req, signal);
+        throw new Error("this resumed leg's answer was bound to the decided question only — a new question has no answer on this leg");
+    };
 }
 function writeFamilyOfCanonical(name) {
     if (name === "TaskCreate" || name === "TaskUpdate")
@@ -1559,6 +1576,32 @@ export class Runner {
         let notificationIdent = () => ({});
         let notificationLaneLive = true;
         let notificationSessionId;
+        let descendantAnchorDisclosed = false;
+        const parkTaskNotification = (payload, priority) => {
+            if (notificationSessionId !== undefined)
+                this.pendingSessionNotifications.pend(notificationSessionId, payload);
+            if (!isDelegatedAgentTerminal(payload))
+                return;
+            const uplink = internals?.parentNotify;
+            if (uplink !== undefined) {
+                try {
+                    uplink(payload, { priority });
+                }
+                catch (e) {
+                    this.deps.onError?.(e, { phase: "degraded", sessionId: notificationSessionId ?? "", classification: "descendant-terminal-uplink" });
+                }
+                return;
+            }
+            const rootAnchor = internals?.rootSessionId;
+            if (rootAnchor !== undefined && rootAnchor !== notificationSessionId) {
+                this.pendingSessionNotifications.pend(rootAnchor, payload);
+                return;
+            }
+            if (internals?.parentSessionId !== undefined && !descendantAnchorDisclosed) {
+                descendantAnchorDisclosed = true;
+                this.deps.onError?.(new Error(`background-agent terminal ${payload.task_id} parked on this run's own session — the delegation tree's root session is not reachable from this run (no uplink, no root anchor)`), { phase: "degraded", sessionId: notificationSessionId ?? "", classification: "descendant-terminal-unrouted" });
+            }
+        };
         const unsubscribeTaskNotifications = taskNotificationQueue.subscribe((item) => {
             queue.push({ type: "task_notification", notification: item.payload, ...notificationIdent() });
             if (notificationHarness) {
@@ -1567,14 +1610,12 @@ export class Runner {
                     ? notificationHarness.followUp(xml, { provenance: "engine-note", enginePayload: item.payload })
                     : notificationHarness.steer(xml, { provenance: "engine-note", enginePayload: item.payload });
                 void deliver.then(() => item.onDisposition?.("queued"), () => {
-                    if (notificationSessionId !== undefined)
-                        this.pendingSessionNotifications.pend(notificationSessionId, item.payload);
+                    parkTaskNotification(item.payload, item.priority);
                     item.onDisposition?.("parked");
                 });
             }
             else {
-                if (notificationSessionId !== undefined)
-                    this.pendingSessionNotifications.pend(notificationSessionId, item.payload);
+                parkTaskNotification(item.payload, item.priority);
                 item.onDisposition?.("parked");
             }
         });
@@ -1584,8 +1625,7 @@ export class Runner {
             if (deliveredAtTurnOpen.has(taskNotificationDedupKey(notification)))
                 return Promise.resolve("dropped_duplicate");
             if (!notificationLaneLive) {
-                if (notificationSessionId !== undefined)
-                    this.pendingSessionNotifications.pend(notificationSessionId, notification);
+                parkTaskNotification(notification, opts?.priority ?? "later");
                 return Promise.resolve("parked");
             }
             return new Promise((resolve) => {
@@ -3240,6 +3280,20 @@ export class Runner {
                     throw new CheckpointError("checkpoint.reopen_revote", `this checkpoint was reopened after an env-restore failure (env_failed) — a re-resume is a system retry of the already-approved action, not a re-vote; the supplied decision must replay the persisted winner (boundCallId "${cp.resolvedOutcome.boundCallId}", decision "${cp.resolvedOutcome.decision}"), refusing a different decision`);
                 }
             }
+            const contentAskCallId = pendingContentAskCallId(cp);
+            if (outcome.answer !== undefined && (contentAskCallId === undefined || outcome.decision !== "allow")) {
+                throw new CheckpointError("checkpoint.invalid_outcome", contentAskCallId === undefined
+                    ? "resume carried a content-ask `answer` but the checkpoint's pending call is not the reserved question tool — an answer has no consumer on a side-effecting tool's approval; refusing rather than dropping it silently"
+                    : "resume carried a content-ask `answer` on a `deny` — a denial injects a refusal, never an answer; refusing rather than dropping it silently", { field: "answer" });
+            }
+            if (contentAskCallId !== undefined && outcome.decision === "allow" && outcome.answer === undefined) {
+                const liveFace = taskConfig.onQuestion ?? this.deps.onQuestion;
+                if (liveFace === undefined || liveFace === QUESTION_AWAITS_RESUME) {
+                    throw new CheckpointError("checkpoint.invalid_outcome", "resume approved a content-ask (the reserved question tool) without an `answer`, and this resume has no live answering face — " +
+                        'executing the question against nothing would hand the model a fabricated "no human is available" default while consuming the approval; ' +
+                        "re-resume with the operator's answer on the outcome (or deny it), the checkpoint stays pending", { field: "answer" });
+                }
+            }
         }
         if (checkpointVersionOf(cp) > MAX_SUPPORTED_CHECKPOINT_VERSION) {
             throw new CheckpointError("checkpoint.unsupported_version", `checkpoint version ${checkpointVersionOf(cp)} is newer than this worker supports (max ${MAX_SUPPORTED_CHECKPOINT_VERSION})`);
@@ -3279,12 +3333,16 @@ export class Runner {
             await internals.afterCheckpointResolve();
             consumeFlipDone = true;
         }
+        const answerFace = outcome.gate === "policy_ask" && outcome.answer !== undefined
+            ? answerFaceForRedeemedCall(outcome.answer, outcome.boundCallId, taskConfig.onQuestion ?? this.deps.onQuestion)
+            : undefined;
         const spec = {
             ...taskConfig,
             objective: "",
             sessionId: cp.sessionId,
             requireExistingSession: true,
             preemptSignal: taskConfig.preemptSignal?.aborted ? undefined : taskConfig.preemptSignal,
+            ...(answerFace !== undefined ? { onQuestion: answerFace } : {}),
         };
         const reopenFn = store.reopen?.bind(store);
         const onEnvRestoreFailed = reopenFn

package/dist/core/secret-env.d.ts

@@ -6,5 +6,7 @@ export interface SecretEnvFinding {
     confidence: RedactionConfidence;
     source: RedactionSource;
 }
+export type ExactEnvNameVerdict = "credential" | "exempt" | "unknown";
+export declare function classifyExactEnvName(key: string, credentialNames: ReadonlySet<string>, exemptNames: ReadonlySet<string>): ExactEnvNameVerdict;
 export declare function isSecretEnvKey(key: string): boolean;
 export declare function scrubSecretEnv(env: NodeJS.ProcessEnv, findings?: SecretEnvFinding[]): NodeJS.ProcessEnv;

package/dist/core/secret-env.js

@@ -4,16 +4,28 @@ const SECRET_ENV_EXACT_NAMES = new Set([
     "PGPASSWORD", "MYSQL_PWD", "SSHPASS", "GPG_PASSPHRASE", "GH_PAT", "GITHUB_PAT",
     "NPM_CONFIG__AUTH", "NPM_CONFIG__AUTHTOKEN",
 ]);
+const NON_SECRET_ENV_EXACT_NAMES = new Set([
+    "PARTITION_KEY", "SORT_KEY", "RANGE_KEY", "IDEMPOTENCY_KEY", "CACHE_KEY", "ROUTING_KEY",
+]);
 const SECRET_ENV_KIND_CONFIDENCE = {
     "exact-name": "high",
     "suffix-rule": "medium",
 };
+export function classifyExactEnvName(key, credentialNames, exemptNames) {
+    const upper = key.toUpperCase();
+    if (credentialNames.has(upper))
+        return "credential";
+    if (exemptNames.has(upper))
+        return "exempt";
+    return "unknown";
+}
 function classifySecretEnvKey(key) {
-    if (SECRET_ENV_RE.test(key))
-        return "suffix-rule";
-    if (SECRET_ENV_EXACT_NAMES.has(key.toUpperCase()))
+    const byExactName = classifyExactEnvName(key, SECRET_ENV_EXACT_NAMES, NON_SECRET_ENV_EXACT_NAMES);
+    if (byExactName === "credential")
         return "exact-name";
-    return undefined;
+    if (byExactName === "exempt")
+        return undefined;
+    return SECRET_ENV_RE.test(key) ? "suffix-rule" : undefined;
 }
 export function isSecretEnvKey(key) {
     return classifySecretEnvKey(key) !== undefined;

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

@@ -45,6 +45,7 @@ export declare function renderTaskNotificationXml(n: TaskNotificationPayload): s
 export declare const MAX_PENDING_EVENTS_PER_TASK = 50;
 export declare const MAX_PENDING_EVENTS_PER_SESSION = 200;
 export declare const MAX_PENDING_SESSIONS = 100;
+export declare function isDelegatedAgentTerminal(n: Pick<TaskNotificationPayload, "task_type" | "status">): boolean;
 export interface DrainedPendingNotifications {
     items: TaskNotificationPayload[];
     dropped: Map<string, {

package/dist/core/task-notification.js

@@ -83,6 +83,9 @@ export const MAX_PENDING_EVENTS_PER_SESSION = 200;
 export const MAX_PENDING_SESSIONS = 100;
 const MAX_TOMBSTONES = 5_000;
 const TERMINAL_STATUSES = new Set(["completed", "failed", "killed", "cancelled"]);
+export function isDelegatedAgentTerminal(n) {
+    return n.task_type === "background_agent" && TERMINAL_STATUSES.has(n.status);
+}
 export class PendingSessionNotifications {
     sessions = new Map();
     droppedSessions = 0;

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

@@ -1,6 +1,6 @@
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
-import { sha256, resolveKey, violationText, violationDetails, hasBinaryExtension, isBinaryContent, fileArgPath, imageMimeForRead, imageMagicMatches, } from "./safety.js";
+import { sha256, resolveKey, violationText, violationDetails, binaryMagicFormat, hasBinaryExtension, isBinaryContent, fileArgPath, imageMimeForRead, imageMagicMatches, } from "./safety.js";
 import { decodeTextBytes } from "./encoding.js";
 import { isNotebookPath, parseNotebookCells, renderNotebookCells, stripNotebookImageData, NOTEBOOK_IMAGE_BASE64_BUDGET } from "./notebook.js";
 import { MCP_IMAGE_MAX_BASE64, IMAGE_TARGET_RAW_SIZE } from "../../core/mcp.js";
@@ -166,6 +166,11 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
             if (pdfMagicMatches(readBin.value)) {
                 return pdfResultToToolReturn(await readPdfFile(env, path, r.key, pages, ctx.signal, imageDownsampler, cwdRef?.current ?? rootCanonical, readBin.value, pdfCapabilities));
             }
+            const magicFormat = binaryMagicFormat(readBin.value);
+            if (magicFormat !== undefined) {
+                return errorResult(`Error (Read): "${path}" appears to be a binary file (${magicFormat}, identified by its file signature — whatever its extension says); ` +
+                    `this tool reads UTF-8 and BOM-marked UTF-16LE text only. Inspect or convert it with bash instead.`);
+            }
             const decoded = decodeTextBytes(readBin.value);
             if (decoded.malformed) {
                 return errorResult(`Error (Read): "${path}" has a UTF-16 BOM but a truncated (odd-length) body — the file is corrupt or mis-labelled; repair/convert it with bash (e.g. \`iconv\`) first.`);

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

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
-import { sha256, resolveKey, violationText, violationDetails, requireRead, checkStale, checkEditMatch, checkNoChange, fileArgPath, resolveQuoteMatch, adaptNewStringQuotes, resolveEscapeMatch, adaptNewStringEscapes, escapeMatchWasAttempted, ESCAPE_MATCH_MISS_NOTE, deletionOldString, countOccurrences, WRITE_ENCODING_DEADLOCK_ESCAPE_HINT, } from "./safety.js";
+import { sha256, resolveKey, violationText, violationDetails, requireRead, checkStale, checkEditMatch, checkNoChange, fileArgPath, resolveQuoteMatch, adaptNewStringQuotes, resolveEscapeMatch, adaptNewStringEscapes, escapeMatchWasAttempted, ESCAPE_MATCH_MISS_NOTE, deletionOldString, countOccurrences, READ_REFUSED_ESCAPE_HINT, } from "./safety.js";
 import { decodeTextBytes, encodeTextForFile, normalizeEditText, normalizeFileText } from "./encoding.js";
 import { MAX_EDIT_BYTES, formatByteSize, decodeEditBytes, persistedTextOf, notReadRefusalText, enoentMessage, FILE_STATE_TRAILER, FILE_PATH_PARAMS, ipynbRedirect, countLines, } from "./fs-shared.js";
 async function gateToolWrite(hook, tool, path, key, content) {
@@ -136,7 +136,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
                 return errorResult(ipynb);
             const notRead = requireRead(state, r.key);
             if (notRead)
-                return errorResult(await notReadRefusalText(env, "Edit", r.key, notRead, ctx.signal));
+                return errorResult(await notReadRefusalText(env, "Edit", r.key, notRead, ctx.signal, READ_REFUSED_ESCAPE_HINT));
             const readBin = await env.readBinaryFile(r.key, ctx.signal);
             if (!readBin.ok)
                 return errorResult(`Error (Edit): cannot read "${path}": ${readBin.error.message}`);
@@ -249,7 +249,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
             if (exists.value) {
                 const notRead = requireRead(state, r.key);
                 if (notRead) {
-                    return errorResult(await notReadRefusalText(env, "Write", r.key, notRead, ctx.signal, WRITE_ENCODING_DEADLOCK_ESCAPE_HINT));
+                    return errorResult(await notReadRefusalText(env, "Write", r.key, notRead, ctx.signal, READ_REFUSED_ESCAPE_HINT));
                 }
                 const readBin = await env.readBinaryFile(r.key, ctx.signal);
                 if (!readBin.ok)
@@ -334,7 +334,7 @@ export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additi
                 return errorResult(violationText("NotebookEdit", r.violation), violationDetails(r.violation));
             const notRead = requireRead(state, r.key);
             if (notRead)
-                return errorResult(await notReadRefusalText(env, "NotebookEdit", r.key, notRead, ctx.signal));
+                return errorResult(await notReadRefusalText(env, "NotebookEdit", r.key, notRead, ctx.signal, READ_REFUSED_ESCAPE_HINT));
             const readBin = await env.readBinaryFile(r.key, ctx.signal);
             if (!readBin.ok)
                 return errorResult(`Error (NotebookEdit): cannot read "${notebook_path}": ${readBin.error.message}`);

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

@@ -30,6 +30,16 @@ export declare function foldRedundantPathSegments(p: string): string;
 export declare function hasBinaryExtension(path: string): boolean;
 export declare function imageMimeForRead(path: string): string | undefined;
 export declare function imageMagicMatches(bytes: Uint8Array, mimeType: string): boolean;
+export interface BinaryMagicSegment {
+    readonly offset: number;
+    readonly bytes: readonly number[];
+}
+export interface BinaryMagicSignature {
+    readonly format: string;
+    readonly segments: readonly BinaryMagicSegment[];
+}
+export declare const BINARY_MAGIC_SIGNATURES: readonly BinaryMagicSignature[];
+export declare function binaryMagicFormat(bytes: Uint8Array): string | undefined;
 export declare function isBinaryContent(sample: string): boolean;
 export declare function isUncPath(path: string): boolean;
 export declare function resolveKey(env: ExecutionEnv, rootCanonical: string, path: string, signal?: AbortSignal, baseCwd?: string, additionalRootsCanonical?: readonly string[], exactFileReadExemption?: (canonicalKey: string) => boolean): Promise<{
@@ -59,7 +69,7 @@ export declare const PATH_NOT_IN_ROOT_ESCAPE_HINT = "(This boundary applies to t
 export declare function requireRead(state: ReadFileState, key: string): FsViolation | undefined;
 export declare const OVERSIZE_READ_ESCAPE_HINT = "(This file is over the Read tool's whole-file byte cap, so a default Read is refused \u2014 read it in slices with explicit offset/limit to satisfy the read-first rule, or inspect/transform it with bash (e.g. `sed -n`, `grep`) instead.)";
 export declare const PARTIAL_VIEW_READ_ESCAPE_HINT = "(Your last Read of this file returned only a PARTIAL view \u2014 the output token cap paginated it, so a default Read will keep returning the same page. Re-read it with explicit offset/limit (start from the page marker's next-page hint) until you have seen the part you are about to change; an explicit slice that fits satisfies the read-first rule. Or inspect/transform it with bash (e.g. `sed -n`, `grep`) instead.)";
-export declare const WRITE_ENCODING_DEADLOCK_ESCAPE_HINT = "(If the Read tool refuses this file (binary/unknown encoding), overwrite or convert it with bash instead \u2014 e.g. `rm` + rewrite, or `iconv`.)";
+export declare const READ_REFUSED_ESCAPE_HINT = "(If the Read tool refuses this file (binary/unknown encoding), overwrite or convert it with bash instead \u2014 e.g. `rm` + rewrite, or `iconv`.)";
 export declare function checkNoChange(oldString: string, newString: string): FsViolation | undefined;
 export declare function checkStale(entry: ReadEntry | undefined, currentHash: string): FsViolation | undefined;
 export declare function countOccurrences(haystack: string, needle: string): number;

package/dist/tools/fs/safety.js

@@ -150,6 +150,89 @@ export function imageMagicMatches(bytes, mimeType) {
             return false;
     }
 }
+const asciiBytes = (s) => Array.from(s, (c) => c.charCodeAt(0));
+export const BINARY_MAGIC_SIGNATURES = [
+    { format: "ZIP archive", segments: [{ offset: 0, bytes: [0x50, 0x4b, 0x03, 0x04] }] },
+    { format: "ZIP archive", segments: [{ offset: 0, bytes: [0x50, 0x4b, 0x05, 0x06] }] },
+    { format: "ZIP archive", segments: [{ offset: 0, bytes: [0x50, 0x4b, 0x07, 0x08] }] },
+    { format: "gzip archive", segments: [{ offset: 0, bytes: [0x1f, 0x8b, 0x08] }] },
+    ...[0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39].map((level) => ({
+        format: "bzip2 archive",
+        segments: [{ offset: 0, bytes: [0x42, 0x5a, 0x68, level] }],
+    })),
+    { format: "xz archive", segments: [{ offset: 0, bytes: [0xfd, 0x37, 0x7a, 0x58, 0x5a, 0x00] }] },
+    { format: "zstd archive", segments: [{ offset: 0, bytes: [0x28, 0xb5, 0x2f, 0xfd] }] },
+    { format: "lz4 archive", segments: [{ offset: 0, bytes: [0x04, 0x22, 0x4d, 0x18] }] },
+    { format: "compress archive", segments: [{ offset: 0, bytes: [0x1f, 0x9d] }] },
+    { format: "7-Zip archive", segments: [{ offset: 0, bytes: [0x37, 0x7a, 0xbc, 0xaf, 0x27, 0x1c] }] },
+    { format: "RAR archive", segments: [{ offset: 0, bytes: [0x52, 0x61, 0x72, 0x21, 0x1a, 0x07, 0x00] }] },
+    { format: "RAR archive", segments: [{ offset: 0, bytes: [0x52, 0x61, 0x72, 0x21, 0x1a, 0x07, 0x01, 0x00] }] },
+    { format: "tar archive", segments: [{ offset: 257, bytes: asciiBytes("ustar") }] },
+    { format: "ar archive (static library or Debian package)", segments: [{ offset: 0, bytes: asciiBytes("!<arch>\n") }] },
+    { format: "RPM package", segments: [{ offset: 0, bytes: [0xed, 0xab, 0xee, 0xdb] }] },
+    { format: "ISO 9660 disc image", segments: [{ offset: 32769, bytes: asciiBytes("CD001") }] },
+    { format: "PNG image", segments: [{ offset: 0, bytes: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] }] },
+    { format: "JPEG image", segments: [{ offset: 0, bytes: [0xff, 0xd8, 0xff] }] },
+    { format: "GIF image", segments: [{ offset: 0, bytes: asciiBytes("GIF87a") }] },
+    { format: "GIF image", segments: [{ offset: 0, bytes: asciiBytes("GIF89a") }] },
+    { format: "TIFF image", segments: [{ offset: 0, bytes: [0x49, 0x49, 0x2a, 0x00] }] },
+    { format: "TIFF image", segments: [{ offset: 0, bytes: [0x4d, 0x4d, 0x00, 0x2a] }] },
+    { format: "BMP image", segments: [{ offset: 0, bytes: asciiBytes("BM") }, { offset: 6, bytes: [0x00, 0x00, 0x00, 0x00] }] },
+    { format: "ICO image", segments: [{ offset: 0, bytes: [0x00, 0x00, 0x01, 0x00] }] },
+    { format: "Photoshop document", segments: [{ offset: 0, bytes: asciiBytes("8BPS") }] },
+    { format: "WebP image", segments: [{ offset: 0, bytes: asciiBytes("RIFF") }, { offset: 8, bytes: asciiBytes("WEBP") }] },
+    { format: "RIFF audio (WAV)", segments: [{ offset: 0, bytes: asciiBytes("RIFF") }, { offset: 8, bytes: asciiBytes("WAVE") }] },
+    { format: "RIFF video (AVI)", segments: [{ offset: 0, bytes: asciiBytes("RIFF") }, { offset: 8, bytes: asciiBytes("AVI ") }] },
+    { format: "AIFF audio", segments: [{ offset: 0, bytes: asciiBytes("FORM") }, { offset: 8, bytes: asciiBytes("AIFF") }] },
+    { format: "Ogg container", segments: [{ offset: 0, bytes: asciiBytes("OggS") }, { offset: 4, bytes: [0x00] }] },
+    { format: "FLAC audio", segments: [{ offset: 0, bytes: asciiBytes("fLaC") }] },
+    ...[0x02, 0x03, 0x04].map((major) => ({
+        format: "MP3 audio (ID3 tag)",
+        segments: [{ offset: 0, bytes: [0x49, 0x44, 0x33, major] }],
+    })),
+    { format: "ISO base media container (MP4/MOV/HEIC)", segments: [{ offset: 4, bytes: asciiBytes("ftyp") }] },
+    { format: "Matroska/WebM container", segments: [{ offset: 0, bytes: [0x1a, 0x45, 0xdf, 0xa3] }] },
+    { format: "ASF container (WMV/WMA)", segments: [{ offset: 0, bytes: [0x30, 0x26, 0xb2, 0x75, 0x8e, 0x66, 0xcf, 0x11, 0xa6, 0xd9, 0x00, 0xaa, 0x00, 0x62, 0xce, 0x6c] }] },
+    { format: "FLV video", segments: [{ offset: 0, bytes: [0x46, 0x4c, 0x56, 0x01] }] },
+    { format: "MPEG program stream", segments: [{ offset: 0, bytes: [0x00, 0x00, 0x01, 0xba] }] },
+    { format: "MPEG video stream", segments: [{ offset: 0, bytes: [0x00, 0x00, 0x01, 0xb3] }] },
+    { format: "ELF binary", segments: [{ offset: 0, bytes: [0x7f, 0x45, 0x4c, 0x46] }] },
+    { format: "Mach-O binary", segments: [{ offset: 0, bytes: [0xfe, 0xed, 0xfa, 0xce] }] },
+    { format: "Mach-O binary", segments: [{ offset: 0, bytes: [0xfe, 0xed, 0xfa, 0xcf] }] },
+    { format: "Mach-O binary", segments: [{ offset: 0, bytes: [0xce, 0xfa, 0xed, 0xfe] }] },
+    { format: "Mach-O binary", segments: [{ offset: 0, bytes: [0xcf, 0xfa, 0xed, 0xfe] }] },
+    { format: "Java class file or Mach-O universal binary", segments: [{ offset: 0, bytes: [0xca, 0xfe, 0xba, 0xbe] }] },
+    { format: "WebAssembly module", segments: [{ offset: 0, bytes: [0x00, 0x61, 0x73, 0x6d] }] },
+    { format: "OLE compound document (Office 97-2003 or MSI)", segments: [{ offset: 0, bytes: [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1] }] },
+    { format: "SQLite database", segments: [{ offset: 0, bytes: [...asciiBytes("SQLite format 3"), 0x00] }] },
+    { format: "WOFF font", segments: [{ offset: 0, bytes: asciiBytes("wOFF") }] },
+    { format: "WOFF2 font", segments: [{ offset: 0, bytes: asciiBytes("wOF2") }] },
+    { format: "OpenType font", segments: [{ offset: 0, bytes: asciiBytes("OTTO") }] },
+    { format: "TrueType font", segments: [{ offset: 0, bytes: [0x00, 0x01, 0x00, 0x00] }] },
+    { format: "TrueType font collection", segments: [{ offset: 0, bytes: asciiBytes("ttcf") }] },
+];
+export function binaryMagicFormat(bytes) {
+    for (const signature of BINARY_MAGIC_SIGNATURES) {
+        let matched = true;
+        for (const segment of signature.segments) {
+            if (bytes.length < segment.offset + segment.bytes.length) {
+                matched = false;
+                break;
+            }
+            for (let i = 0; i < segment.bytes.length; i++) {
+                if (bytes[segment.offset + i] !== segment.bytes[i]) {
+                    matched = false;
+                    break;
+                }
+            }
+            if (!matched)
+                break;
+        }
+        if (matched)
+            return signature.format;
+    }
+    return undefined;
+}
 export function isBinaryContent(sample) {
     if (sample.length === 0)
         return false;
@@ -297,7 +380,7 @@ export function requireRead(state, key) {
 }
 export const OVERSIZE_READ_ESCAPE_HINT = "(This file is over the Read tool's whole-file byte cap, so a default Read is refused — read it in slices with explicit offset/limit to satisfy the read-first rule, or inspect/transform it with bash (e.g. `sed -n`, `grep`) instead.)";
 export const PARTIAL_VIEW_READ_ESCAPE_HINT = "(Your last Read of this file returned only a PARTIAL view — the output token cap paginated it, so a default Read will keep returning the same page. Re-read it with explicit offset/limit (start from the page marker's next-page hint) until you have seen the part you are about to change; an explicit slice that fits satisfies the read-first rule. Or inspect/transform it with bash (e.g. `sed -n`, `grep`) instead.)";
-export const WRITE_ENCODING_DEADLOCK_ESCAPE_HINT = "(If the Read tool refuses this file (binary/unknown encoding), overwrite or convert it with bash instead — e.g. `rm` + rewrite, or `iconv`.)";
+export const READ_REFUSED_ESCAPE_HINT = "(If the Read tool refuses this file (binary/unknown encoding), overwrite or convert it with bash instead — e.g. `rm` + rewrite, or `iconv`.)";
 export function checkNoChange(oldString, newString) {
     if (oldString === newString) {
         return { code: "invalid", message: "No changes to make: old_string and new_string are exactly the same." };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.5.0",
+  "version": "5.7.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",
@@ -67,7 +67,7 @@
     "gate:single-mint": "node scripts/verify-single-mint.mjs"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.29.0",
+    "@modelcontextprotocol/sdk": "1.30.0",
     "typebox": "1.1.39"
   },
   "optionalDependencies": {