@sema-agent/core 5.6.0 → 5.7.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 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._

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/package.json

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