@sema-agent/core 5.18.0 → 5.18.1

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 5.18.1 — 2026-08-10
+
+> The 5.18.0 post-release verification round, folded back in. Every surface below was
+> two-way-verified against the 5.18.0 artifact by the evaluation line before this release
+> (pre-release criteria [3095], green-lit [3103]).
+
+### BREAKING (vs 5.18.0; both APIs are new in 5.18.0 and cli has not consumed them yet)
+
+- **`confirmRuleApproval` returns `{ ok: true } | { ok: false, reason }`** instead of a bare
+  boolean — seven-member closed reason set (`record_not_found` deliberately covers the
+  foreign-principal arm so record existence does not leak, `selection_missing`,
+  `selection_invalid`, `selection_mismatch`, `batch_takes_no_selection`, `not_pending`,
+  `conflict`). `selectedCandidate` is an integer index.
+- **`prepareCardApproval` refuses caller-supplied `candidates` loudly**
+  (`config.invalid_argument`) instead of silently ignoring them — card options are
+  engine-minted, and a dropped supply attempt is the same silent-narrowing shape this
+  release family removes elsewhere.
+
+### Added
+
+- **`settledBy` on approval settlements** (`"human" | "timeout" | "aborted"`): an optional
+  field on the durable resume outcome's `policy_ask` arm, carried onto the settled call's
+  `tool_end` (top-level key). Out-of-vocabulary values are refused pre-CAS
+  (`checkpoint.invalid_outcome`, `detail.field: "settledBy"` — the row stays pending);
+  `decision: "allow"` accepts only `"human"` or omission (a contradictory record must not
+  become an execution). Core's own arms fill it (elapsed window = `timeout`; abort /
+  unclonable / out-of-contract = `aborted`; human answers = `"human"`); posture arms
+  (headless auto-deny, blanket modes) leave it absent. Absence = an older caller — consumers
+  must not infer semantics from a missing key. New exports: `ApprovalSettledBy`,
+  `APPROVAL_SETTLED_BY_VALUES`, `isApprovalSettledBy`.
+
+### Fixed
+
+- **An elapsed approval window says nobody answered** — the live-deadline refusal no longer
+  borrows the sentence a person's refusal uses; human-refusal and no-provenance wordings are
+  byte-for-byte unchanged (269 existing approval strings verified untouched).
+- **`createAllowDenyPolicy` screens malformed `mcp__` names** (empty segment: `mcp__`,
+  `mcp__a__`) alongside the content form; `mcp__server` / `mcp__server__tool` and the
+  conditionally-retired `Task` spelling stay accepted. The constructor-level retired-name
+  screen added briefly after 5.18.0 was withdrawn — the roster-aware prepare-time audit
+  (`config.legacy_tool_name`, all three kinds) already owns that refusal.
+
 ## 5.18.0 — 2026-08-10
 
 > Two mainline features land together: design/178 personal-assistant memory v1 (the retrieval pair

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

@@ -95,6 +95,7 @@ export type ResumeOutcome = {
     updatedInput?: unknown;
     reason?: string;
     answer?: QuestionAnswer;
+    settledBy?: import("./tool-policy.js").ApprovalSettledBy;
 } | {
     gate: "resource_limit";
     decision: "continue";
@@ -277,10 +278,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.walltime_axis_retired" | "checkpoint.reopen_revote" | "checkpoint.reopened_concurrently" | "checkpoint.reopen_failed" | "steering.invalid_content" | "steering.queue_full" | "steering.duplicate_input_id" | "wake.gate_pending" | "wake.nothing_to_deliver" | "resume.parent_constraint_missing" | "resume.parent_constraint_mismatch";
     readonly detail?: {
-        field?: "boundCallId" | "boundInputHash" | "answer";
+        field?: "boundCallId" | "boundInputHash" | "answer" | "settledBy";
     } | 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.walltime_axis_retired" | "checkpoint.reopen_revote" | "checkpoint.reopened_concurrently" | "checkpoint.reopen_failed" | "steering.invalid_content" | "steering.queue_full" | "steering.duplicate_input_id" | "wake.gate_pending" | "wake.nothing_to_deliver" | "resume.parent_constraint_missing" | "resume.parent_constraint_mismatch", message: string, detail?: {
-        field?: "boundCallId" | "boundInputHash" | "answer";
+        field?: "boundCallId" | "boundInputHash" | "answer" | "settledBy";
     } | undefined);
 }
 export type StoreDurability = "durable" | "process-local";

package/dist/core/hooks.d.ts

@@ -104,6 +104,7 @@ export declare function formatHookFeedback(text: string): string;
 export interface ToolGateResult {
     block?: boolean;
     reason?: string;
+    settledBy?: import("./tool-policy.js").ApprovalSettledBy;
     updatedInput?: unknown;
     suspend?: {
         token: import("./checkpoint-store.js").CheckpointToken;

package/dist/core/hooks.js

@@ -411,9 +411,11 @@ export async function runToolGate(input) {
         if (input.permissionDenied) {
             await notifier.notifyAsync(() => input.permissionDenied?.({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason: denyReason, source: denySource }), "toolGate.permissionDenied");
         }
+        const denySettledBy = decision.settledBy;
         return {
             block: true,
             reason: formatHookFeedback(denyReason),
+            ...(denySettledBy !== undefined ? { settledBy: denySettledBy } : {}),
             preToolContext,
         };
     }
@@ -422,8 +424,10 @@ export async function runToolGate(input) {
         if (rw !== undefined)
             currentInput = rw;
     }
+    const allowSettledBy = decision.action === "allow" ? decision.settledBy : undefined;
     return {
         updatedInput: currentInput === event.input ? undefined : currentInput,
+        ...(allowSettledBy !== undefined ? { settledBy: allowSettledBy } : {}),
         preToolContext,
     };
 }

package/dist/core/permission-rule-consent.d.ts

@@ -56,7 +56,14 @@ export declare function confirmRuleApproval(opts: {
     principal: string;
     selectedCandidate?: number;
     deps: RuleConsentDeps;
-}): Promise<boolean>;
+}): Promise<ConfirmResult>;
+export type ConfirmRefusalReason = "record_not_found" | "selection_missing" | "selection_invalid" | "selection_mismatch" | "batch_takes_no_selection" | "not_pending" | "conflict";
+export type ConfirmResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: ConfirmRefusalReason;
+};
 export type RedeemResult = {
     status: "redeemed";
     rule: string;

package/dist/core/permission-rule-consent.js

@@ -47,6 +47,11 @@ function parseRuleTicket(ticket) {
 }
 export async function prepareCardApproval(opts) {
     const principal = requirePrincipal(opts.principal, "prepareCardApproval");
+    if ("candidates" in opts) {
+        const e = new Error("prepareCardApproval does not accept caller candidates — card options are minted by the engine from the adjudicated command");
+        e.code = "config.invalid_argument";
+        throw e;
+    }
     if (opts.toolName !== CARD_RULE_TOOL)
         return undefined;
     const scope = opts.scope ?? { kind: "global" };
@@ -70,24 +75,30 @@ export async function prepareCardApproval(opts) {
 const CARD_RULE_TOOL = "Bash";
 export async function confirmRuleApproval(opts) {
     const principal = requirePrincipal(opts.principal, "confirmRuleApproval");
+    const no = (reason) => ({ ok: false, reason });
     const rec = await opts.deps.approvals.get(opts.approvalId);
     if (rec === undefined || rec.principal !== principal)
-        return false;
+        return no("record_not_found");
     if (rec.kind === "card") {
         const chosen = opts.selectedCandidate;
-        if (chosen === undefined || !Number.isInteger(chosen) || rec.candidates[chosen] === undefined)
-            return false;
-        if (rec.state === "approved" || rec.state === "redeemed")
-            return rec.selectedCandidate === chosen;
-        return await opts.deps.approvals.cas(rec.id, rec.rev, { ...rec, rev: rec.rev + 1, state: "approved", selectedCandidate: chosen });
+        if (chosen === undefined)
+            return no("selection_missing");
+        if (!Number.isInteger(chosen) || rec.candidates[chosen] === undefined)
+            return no("selection_invalid");
+        if (rec.state === "approved" || rec.state === "redeemed") {
+            return rec.selectedCandidate === chosen ? { ok: true } : no("selection_mismatch");
+        }
+        const won = await opts.deps.approvals.cas(rec.id, rec.rev, { ...rec, rev: rec.rev + 1, state: "approved", selectedCandidate: chosen });
+        return won ? { ok: true } : no("conflict");
     }
     if (opts.selectedCandidate !== undefined)
-        return false;
+        return no("batch_takes_no_selection");
     if (rec.state === "approved")
-        return true;
+        return { ok: true };
     if (rec.state !== "pending")
-        return false;
-    return await opts.deps.approvals.cas(rec.id, rec.rev, { ...rec, rev: rec.rev + 1, state: "approved" });
+        return no("not_pending");
+    const won = await opts.deps.approvals.cas(rec.id, rec.rev, { ...rec, rev: rec.rev + 1, state: "approved" });
+    return won ? { ok: true } : no("conflict");
 }
 export async function redeemRuleTicket(opts) {
     const principal = requirePrincipal(opts.principal, "redeemRuleTicket");

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

@@ -64,6 +64,7 @@ export interface Prepared {
         hit: boolean;
     };
     blockedToolCalls: Set<string>;
+    approvalSettledBy: Map<string, import("../tool-policy.js").ApprovalSettledBy>;
     nestedStats: NestedUsageAccum;
     rewindNotes?: NonNullable<TaskResult["rewindNotes"]>;
     cwdRef?: CwdRef;

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

@@ -20,7 +20,7 @@ import { createSubagentWorktreeHelper, forkGovernanceDenial } from "../../agents
 import { createAgentTranscriptTool, AGENT_TRANSCRIPT_TOOL_NAME } from "../../agents/agent-transcript-tool.js";
 import { createSendMessageTool, SEND_MESSAGE_TOOL_NAME } from "../../agents/send-message-tool.js";
 import { SubagentRetainLedger } from "../../agents/retain-ledger.js";
-import { askApproverIdentity, combinePolicies, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, describeThrown, refuseOutOfContractDecision, resolveAsk, toolPolicyNameSets, tryCloneArgs } from "../tool-policy.js";
+import { askApproverIdentity, combinePolicies, isApprovalSettledBy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, describeThrown, refuseOutOfContractDecision, resolveAsk, toolPolicyNameSets, tryCloneArgs } from "../tool-policy.js";
 const PERSISTED_RULE_TOOL = "Bash";
 import { findAdmittingRule, suggestRulesForCommand } from "../permission-rule-model.js";
 import { ActiveSkillScope, createActiveSkillScopePolicy } from "./active-skill-scope.js";
@@ -3304,6 +3304,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         }
         const preToolContexts = new Map();
         const blockedToolCalls = new Set();
+        const approvalSettledBy = new Map();
         const blockedTracked = Boolean(hooks?.postToolUse || hooks?.preToolUse || hooks?.postToolUseFailure || hooks?.postToolBatch);
         const restoreSurfaceGap = ownedEnv !== undefined && isRemoteExecutionEnv(ownedEnv) && ownedEnv.capabilities.suspendable ? missingRestoreSurface(ownedEnv) : [];
         const incompleteSuspendAdapter = restoreSurfaceGap.length > 0 ? restoreSurfaceGap : undefined;
@@ -4156,6 +4157,17 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     if (blockedTracked && (result.block || result.suspend)) {
                         blockedToolCalls.add(e.toolCallId);
                     }
+                    const reported = result.settledBy;
+                    if (reported !== undefined) {
+                        const settling = result.block === true;
+                        if (!isApprovalSettledBy(reported) || (!settling && reported !== "human")) {
+                            deps.onError?.(new Error(`a tool-gate settlement reported settledBy "${String(reported)}" on ${settling ? "a blocked" : "an executing"} call — ` +
+                                `it is one of "human" / "timeout" / "aborted", and only "human" can be the source of a call that runs; the frame carries no source`), { phase: "config", sessionId });
+                        }
+                        else {
+                            approvalSettledBy.set(e.toolCallId, reported);
+                        }
+                    }
                     return result.block
                         ? { block: true, reason: result.reason }
                         : result.updatedInput !== undefined
@@ -4444,7 +4456,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, settleContentAskBindings, cacheBreakDetector, cacheFingerprint, wiringManifest, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, deferDirectCall, ...(staticFaceForRef.current !== undefined ? { staticFaceFor: staticFaceForRef.current } : {}), ownedEnv, suspendRef, suspendProgressRef, reviewRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
+        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath, model, thinking, compModel, mcp: mcp, ...(a2a !== undefined && a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, approvalSettledBy, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), releaseSignal, settleContentAskBindings, cacheBreakDetector, cacheFingerprint, wiringManifest, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, deferDirectCall, ...(staticFaceForRef.current !== undefined ? { staticFaceFor: staticFaceForRef.current } : {}), ownedEnv, suspendRef, suspendProgressRef, reviewRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
         const prepared = buildPrepared();
         preparedHolder.current = prepared;
         return prepared;

package/dist/core/runner/runtask.d.ts

@@ -5,6 +5,7 @@ import { type TaskOutcome } from "../task-outcome.js";
 import { type SideQuerySpec, type SideQueryResult } from "../side-query.js";
 import type { SessionStore } from "../session.js";
 import { type RecoveredOrphan } from "../session-reconcile.js";
+import { type ApprovalSettledBy } from "../tool-policy.js";
 import type { AgentDefinition, RunnerDeps, TaskEvent, TaskResult, TaskSpec, TaskStream } from "../types.js";
 export type ResumeTaskConfig = Omit<TaskSpec, "objective" | "sessionId">;
 interface ResumeRun {
@@ -17,12 +18,13 @@ interface ResumeRun {
     onEnvRestoreFailed?: (reason: ReopenReason) => Promise<void>;
     decisionDelivered?: boolean;
 }
-declare function toolEndBodyFrom(result: unknown, isError: boolean): {
+declare function toolEndBodyFrom(result: unknown, isError: boolean, settledBy?: ApprovalSettledBy): {
     output?: unknown;
     truncated?: boolean;
     totalChars?: number;
     structured?: unknown;
     errorCode?: string;
+    settledBy?: ApprovalSettledBy;
 };
 export declare function reconciledToolEndBody(orphan: Pick<RecoveredOrphan, "text" | "errorKind">): ReturnType<typeof toolEndBodyFrom>;
 export declare const GOVERNANCE_READ_STALLED: unique symbol;

package/dist/core/runner/runtask.js

@@ -38,7 +38,7 @@ import { delimitUntrusted, inlineUntrusted, sanitizeUntrustedText } from "../unt
 import { reconcileInterruptedSession } from "../session-reconcile.js";
 import { RunnerSharedToolResultStore } from "../tool-result-store.js";
 import { formatDiagnosticsBlock } from "../lsp-diagnostics.js";
-import { refuseOutOfContractDecision, toolPolicyNameSets } from "../tool-policy.js";
+import { isApprovalSettledBy, refuseOutOfContractDecision, toolPolicyNameSets } from "../tool-policy.js";
 import { defaultTaskRegistry } from "../task-registry.js";
 import { discloseDroppedPending, isDelegatedAgentTerminal, PendingSessionNotifications, renderTaskNotificationXml, SystemInjectionQueue, taskNotificationDedupKey } from "../task-notification.js";
 import { ToolDetachHub } from "../tool-detach.js";
@@ -126,7 +126,7 @@ function resumeDecisionWasNegative(resume) {
 }
 const DEFERRED_REISSUE = "[DEFERRED] This tool call shared a batch with a call that suspended for durable approval, so it was " +
     "NOT executed on resume. If you still need it, issue it again now.";
-function toolEndBodyFrom(result, isError) {
+function toolEndBodyFrom(result, isError, settledBy) {
     const o = toolOutputFrom(result);
     const st = structuredFrom(result);
     const code = isError ? result?.details?.code : undefined;
@@ -134,6 +134,7 @@ function toolEndBodyFrom(result, isError) {
         ...(o !== undefined ? { output: o.output, ...(o.truncated ? { truncated: true } : {}), ...(o.totalChars !== undefined ? { totalChars: o.totalChars } : {}) } : {}),
         ...(st !== undefined ? { structured: st } : {}),
         ...(typeof code === "string" ? { errorCode: code } : {}),
+        ...(settledBy !== undefined ? { settledBy } : {}),
     };
 }
 export function reconciledToolEndBody(orphan) {
@@ -1202,13 +1203,16 @@ function makeHarnessHandlers(prepared, stats, rs, deps) {
                     prepared.lspDiagnostics.nudge(p);
             }
         }
+        const settledBy = prepared.approvalSettledBy.get(event.toolCallId);
+        if (settledBy !== undefined)
+            prepared.approvalSettledBy.delete(event.toolCallId);
         pushContent({
             type: "tool_end",
             toolCallId: event.toolCallId,
             toolName: event.toolName,
             ...(toolLabels.get(event.toolName) !== undefined ? { label: toolLabels.get(event.toolName) } : {}),
             isError: event.isError,
-            ...toolEndBodyFrom(event.result, event.isError),
+            ...toolEndBodyFrom(event.result, event.isError, settledBy),
             ...ident(),
         });
         announceWorkspaceMove();
@@ -3617,6 +3621,14 @@ export class Runner {
             if (decision !== "allow" && decision !== "deny") {
                 throw new CheckpointError("checkpoint.invalid_outcome", `resume decision "${describeSuppliedValue(decision)}" is outside the policy_ask domain — a decide is exactly "allow" or "deny"; refusing pre-CAS, the checkpoint stays pending`);
             }
+            const settledBy = decide.settledBy;
+            if (settledBy !== undefined && !isApprovalSettledBy(settledBy)) {
+                throw new CheckpointError("checkpoint.invalid_outcome", `resume settledBy "${describeSuppliedValue(settledBy)}" is outside the settlement vocabulary — it is exactly "human", "timeout" or "aborted" (or omitted); refusing pre-CAS, the checkpoint stays pending`, { field: "settledBy" });
+            }
+            if (settledBy !== undefined && settledBy !== "human" && decision === "allow") {
+                throw new CheckpointError("checkpoint.invalid_outcome", `resume carries decision "allow" with settledBy "${settledBy}" — a non-human settlement is a fail-closed end (nobody answered), so it cannot be the source of an approval that EXECUTES; ` +
+                    "supply \"human\", or omit the field if the allow came from configuration rather than a person; refusing pre-CAS, the checkpoint stays pending", { field: "settledBy" });
+            }
             const reason = decide.reason;
             assertOutcomeText(reason, "reason");
             plainPolicyOutcome = {
@@ -3627,6 +3639,7 @@ export class Runner {
                 ...(updatedInput !== undefined ? { updatedInput } : {}),
                 ...(reason !== undefined ? { reason } : {}),
                 ...(redeemedAnswer !== undefined ? { answer: redeemedAnswer } : {}),
+                ...(settledBy !== undefined ? { settledBy } : {}),
             };
             if (plainPolicyOutcome.decision === "deny" && plainPolicyOutcome.reason && sanitizeUntrustedText(plainPolicyOutcome.reason) !== plainPolicyOutcome.reason) {
                 throw new CheckpointError("checkpoint.invalid_outcome", "resume deny/reject reason must not contain a </system-reminder> tag");
@@ -3823,9 +3836,14 @@ export class Runner {
         const resolvedArgs = pendingAction.toolName === ASK_USER_QUESTION_TOOL_NAME ? pendingAction.args : (outcome.updatedInput !== undefined ? outcome.updatedInput : pendingAction.args);
         const pendingLabel = (() => { const l = prepared.tools.find((t) => t.name === pendingAction.toolName)?.label; return l !== undefined && l !== pendingAction.toolName ? { label: l } : {}; })();
         emit({ type: "tool_start", toolCallId: pendingAction.toolCallId, toolName: pendingAction.toolName, ...pendingLabel, args: resolvedArgs });
-        const emitEnd = (isError, result) => emit({ type: "tool_end", toolCallId: pendingAction.toolCallId, toolName: pendingAction.toolName, ...pendingLabel, isError, ...toolEndBodyFrom(result, isError) });
+        const emitEnd = (isError, result) => emit({ type: "tool_end", toolCallId: pendingAction.toolCallId, toolName: pendingAction.toolName, ...pendingLabel, isError, ...toolEndBodyFrom(result, isError, outcome.settledBy) });
         if (outcome.decision === "deny") {
-            const reason = outcome.reason ? delimitUntrusted("reviewer note", outcome.reason) : `The pending tool call "${pendingAction.toolName}" was denied by an approver.`;
+            const defaultDenial = outcome.settledBy === "timeout"
+                ? `No one answered the approval request for the pending tool call "${pendingAction.toolName}" — the approval window elapsed with no answer, so it was not executed.`
+                : outcome.settledBy === "aborted"
+                    ? `The approval for the pending tool call "${pendingAction.toolName}" ended without anyone deciding it (it was cancelled or could not be delivered), so it was not executed.`
+                    : `The pending tool call "${pendingAction.toolName}" was denied by an approver.`;
+            const reason = outcome.reason ? delimitUntrusted("reviewer note", outcome.reason) : defaultDenial;
             emitEnd(true, { content: formatHookFeedback(reason) });
             const eid = await prepared.session.appendMessage(toolResultMsg(pendingAction.toolCallId, pendingAction.toolName, formatHookFeedback(reason), true));
             emitCommitted(eid, "toolResult", pendingAction.toolCallId);

package/dist/core/tool-policy.d.ts

@@ -9,11 +9,15 @@ export interface ToolCallRequest {
     };
 }
 export type DecisionReason = "rule" | "mode" | "hook" | "safety" | "classifier" | "persisted_rule";
+export type ApprovalSettledBy = "human" | "timeout" | "aborted";
+export declare const APPROVAL_SETTLED_BY_VALUES: readonly ApprovalSettledBy[];
+export declare function isApprovalSettledBy(v: unknown): v is ApprovalSettledBy;
 export type PermissionResult = {
     action: "allow";
     updatedInput?: unknown;
     message?: string;
     decisionReason?: DecisionReason;
+    settledBy?: Extract<ApprovalSettledBy, "human">;
 } | {
     action: "ask";
     updatedInput?: unknown;
@@ -25,6 +29,7 @@ export type PermissionResult = {
     updatedInput?: unknown;
     message?: string;
     decisionReason?: DecisionReason;
+    settledBy?: ApprovalSettledBy;
 };
 export declare function decisionText(d: PermissionResult): string | undefined;
 export interface ToolPolicy {

package/dist/core/tool-policy.js

@@ -5,6 +5,10 @@ import { boundInputHashOf } from "./canonical-json.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 import { parsePermissionRule } from "./permission-rules.js";
 import { writeTargetPath } from "../tools/fs/safety.js";
+export const APPROVAL_SETTLED_BY_VALUES = ["human", "timeout", "aborted"];
+export function isApprovalSettledBy(v) {
+    return typeof v === "string" && APPROVAL_SETTLED_BY_VALUES.includes(v);
+}
 export function decisionText(d) {
     return d.message;
 }
@@ -19,6 +23,7 @@ export function refuseOutOfContractDecision(d) {
         return d;
     return { action: "deny", message: RETIRED_TEXT_FIELD_DENY_MESSAGE, decisionReason: "rule" };
 }
+const DEADLINE_ELAPSED = Symbol("approval.deadline_elapsed");
 function withTimeout(p, ms, onTimeout) {
     if (ms === undefined) {
         return p;
@@ -51,6 +56,18 @@ export function createAllowDenyPolicy(opts) {
             return undefined;
         const kept = [];
         for (const entry of entries) {
+            if (entry.startsWith("mcp__")) {
+                const segments = entry.slice("mcp__".length).split("__");
+                if (segments.some((seg) => seg.length === 0)) {
+                    invalid.push({
+                        entry,
+                        list,
+                        message: `"${entry}" is a malformed MCP tool name (empty segment) — it can never match any mounted tool. ` +
+                            `Use \`mcp__<server>\` for every tool of a server, or \`mcp__<server>__<tool>\` for one tool.`,
+                    });
+                    continue;
+                }
+            }
             if (parsePermissionRule(entry).ruleContent === undefined) {
                 kept.push(entry);
                 continue;
@@ -118,25 +135,37 @@ export function createApprovalPolicy(opts) {
             }
             if (need.has(toolName)) {
                 if (signal?.aborted) {
-                    return { action: "deny", message: `approval aborted for "${req.toolName}" (task ended)` };
+                    return { action: "deny", message: `approval aborted for "${req.toolName}" (task ended)`, settledBy: "aborted" };
                 }
                 let ok;
                 try {
-                    ok = await withTimeout(Promise.resolve(opts.approve(req, signal)), opts.approvalTimeoutMs, () => false);
+                    ok = await withTimeout(Promise.resolve(opts.approve(req, signal)), opts.approvalTimeoutMs, () => DEADLINE_ELAPSED);
                 }
                 catch (err) {
                     return {
                         action: "deny",
                         message: `approval errored for "${req.toolName}": ${describeThrown(err)}`,
+                        settledBy: "aborted",
+                    };
+                }
+                if (ok === DEADLINE_ELAPSED) {
+                    return {
+                        action: "deny",
+                        message: `no one answered the approval request for "${req.toolName}" — the approval window elapsed ` +
+                            `(${opts.approvalTimeoutMs}ms) with no answer; denied fail-closed`,
+                        settledBy: "timeout",
                     };
                 }
+                if (signal?.aborted) {
+                    return { action: "deny", message: `approval aborted for "${req.toolName}" (task ended)`, settledBy: "aborted" };
+                }
                 const okRaw = ok;
                 if (okRaw === true)
-                    return ALLOW;
+                    return { action: "allow", settledBy: "human" };
                 if (okRaw !== false) {
-                    return { action: "deny", message: `approval callback for "${req.toolName}" returned an out-of-contract value (${typeof ok}) — denied fail-closed (this policy's \`approve\` returns a boolean: return true or false)` };
+                    return { action: "deny", message: `approval callback for "${req.toolName}" returned an out-of-contract value (${typeof ok}) — denied fail-closed (this policy's \`approve\` returns a boolean: return true or false)`, settledBy: "aborted" };
                 }
-                return { action: "deny", message: `approval denied for "${req.toolName}"` };
+                return { action: "deny", message: `approval denied for "${req.toolName}"`, settledBy: "human" };
             }
             if (opts.denyByDefault && !auto.has(toolName)) {
                 return { action: "deny", message: `tool "${req.toolName}" requires explicit allow` };
@@ -153,6 +182,7 @@ export function combinePolicies(...policies) {
             let asked;
             let current = req;
             let rewrite;
+            let settled;
             for (const p of policies) {
                 const d = refuseOutOfContractDecision(await p.check(current, signal));
                 if (d.action === "deny") {
@@ -162,6 +192,11 @@ export function combinePolicies(...policies) {
                     current = { ...current, args: d.updatedInput };
                     rewrite = d;
                 }
+                if (d.action === "allow") {
+                    const supplied = d.settledBy;
+                    if (supplied !== undefined)
+                        settled = supplied;
+                }
                 if (d.action === "ask" && (asked === undefined || (d.requiresRealApproval === true && asked.requiresRealApproval !== true))) {
                     asked = d;
                 }
@@ -170,7 +205,8 @@ export function combinePolicies(...policies) {
                 const merged = rewrite?.updatedInput;
                 return merged !== undefined ? { ...asked, updatedInput: merged } : asked;
             }
-            return rewrite ?? ALLOW;
+            const allowed = rewrite ?? ALLOW;
+            return settled !== undefined ? { ...allowed, settledBy: settled } : allowed;
         },
     };
 }
@@ -643,7 +679,7 @@ export async function resolveAsk(req, onAsk, signal) {
         };
     }
     if (signal?.aborted) {
-        return { action: "deny", message: `approval aborted for "${req.toolName}" (task ended)`, decisionReason: "mode" };
+        return { action: "deny", message: `approval aborted for "${req.toolName}" (task ended)`, decisionReason: "mode", settledBy: "aborted" };
     }
     const presented = tryCloneArgs(req.args);
     if (!presented.ok) {
@@ -651,6 +687,7 @@ export async function resolveAsk(req, onAsk, signal) {
             action: "deny",
             message: `approval for "${req.toolName}" could not present the args safely (unclonable value: ${presented.reason}) — denied fail-closed`,
             decisionReason: "mode",
+            settledBy: "aborted",
         };
     }
     let ok;
@@ -661,6 +698,7 @@ export async function resolveAsk(req, onAsk, signal) {
                 action: "deny",
                 message: `approval for "${req.toolName}" could not present the args safely (unclonable value: ${approverView.reason}) — denied fail-closed`,
                 decisionReason: "mode",
+                settledBy: "aborted",
             };
         }
         ok = await onAsk({ ...req, boundInputHash: boundInputHashOf(presented.value), args: approverView.value }, signal);
@@ -670,42 +708,49 @@ export async function resolveAsk(req, onAsk, signal) {
             action: "deny",
             message: `approval errored for "${req.toolName}": ${describeThrown(err)}`,
             decisionReason: "mode",
+            settledBy: "aborted",
         };
     }
+    if (signal?.aborted) {
+        return { action: "deny", message: `approval aborted for "${req.toolName}" (task ended)`, decisionReason: "mode", settledBy: "aborted" };
+    }
     if (ok === "unavailable") {
         return {
             action: "deny",
             message: `approval required for "${req.toolName}" but the approver reported unavailable (no reachable ` +
                 `operator for this ask) and no durable approval gate is armed — denied fail-closed: ${req.message}`,
             decisionReason: "mode",
+            settledBy: "aborted",
             approverUnavailable: true,
         };
     }
     if (typeof ok === "object" && ok !== null) {
         if (ok.allow !== true) {
-            return { action: "deny", message: `approval denied for "${req.toolName}": ${req.message}`, decisionReason: "mode" };
+            return { action: "deny", message: `approval denied for "${req.toolName}": ${req.message}`, decisionReason: "mode", settledBy: "human" };
         }
         if (ok.updatedInput === undefined)
-            return { action: "allow", decisionReason: "mode", presentedInput: presented.value };
+            return { action: "allow", decisionReason: "mode", presentedInput: presented.value, settledBy: "human" };
         const edit = tryCloneArgs(ok.updatedInput);
         if (!edit.ok) {
             return {
                 action: "deny",
                 message: `the approved edit for "${req.toolName}" is not safely clonable (${edit.reason}) — denied fail-closed`,
                 decisionReason: "mode",
+                settledBy: "aborted",
             };
         }
-        return { action: "allow", updatedInput: edit.value, decisionReason: "mode" };
+        return { action: "allow", updatedInput: edit.value, decisionReason: "mode", settledBy: "human" };
     }
     const okRaw = ok;
     if (okRaw === true)
-        return { action: "allow", decisionReason: "mode", presentedInput: presented.value };
+        return { action: "allow", decisionReason: "mode", presentedInput: presented.value, settledBy: "human" };
     if (okRaw !== false) {
         return {
             action: "deny",
             message: `the approver for "${req.toolName}" returned an out-of-contract value (${typeof ok}) — denied fail-closed (return true, false, "unavailable", or the {allow} object)`,
             decisionReason: "mode",
+            settledBy: "aborted",
         };
     }
-    return { action: "deny", message: `approval denied for "${req.toolName}": ${req.message}`, decisionReason: "mode" };
+    return { action: "deny", message: `approval denied for "${req.toolName}": ${req.message}`, decisionReason: "mode", settledBy: "human" };
 }

package/dist/core/types.d.ts

@@ -568,6 +568,7 @@ export type TaskEvent = ({
     output?: unknown;
     structured?: unknown;
     errorCode?: string;
+    settledBy?: import("./tool-policy.js").ApprovalSettledBy;
     truncated?: boolean;
     totalChars?: number;
 } & TaskEventIdentity) | ({

package/dist/index.d.ts

@@ -122,14 +122,14 @@ export type { SchedulerCapability, SchedulerErrorCode, ScheduledIntent, Schedule
 export { createSchedulerTools, type SchedulerToolContext, SCHEDULE_WAKEUP_TOOL_NAME, AUTONOMOUS_LOOP_SENTINEL, AUTONOMOUS_LOOP_DYNAMIC_SENTINEL, } from "./tools/scheduler-tools.js";
 export { resolveAutonomousLoopPrompt, AUTONOMOUS_LOOP_PREAMBLE, AUTONOMOUS_LOOP_PREAMBLE_PERSISTENT, type AutonomousLoopPromptOptions, } from "./tools/loop-tick.js";
 export { tightenTaskSpec, TaskSpecTightenError } from "./core/tighten-task-spec.js";
-export { createAllowDenyPolicy, createApprovalPolicy, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, decisionText, resolveAsk, toolPolicyNameSets, type ToolPolicyNameSets, type NamedToolPolicy, type ToolPolicy, type ToolCallRequest, type PermissionResult, type DecisionReason, type OnAsk, type AskOutcome, type ResolvedAsk, type AskRequest, type AskDelegationProvenance, } from "./core/tool-policy.js";
+export { createAllowDenyPolicy, createApprovalPolicy, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, decisionText, resolveAsk, toolPolicyNameSets, type ToolPolicyNameSets, type NamedToolPolicy, type ToolPolicy, type ToolCallRequest, type PermissionResult, type DecisionReason, type ApprovalSettledBy, APPROVAL_SETTLED_BY_VALUES, isApprovalSettledBy, type OnAsk, type AskOutcome, type ResolvedAsk, type AskRequest, type AskDelegationProvenance, } from "./core/tool-policy.js";
 export { parseAutoModeResponse, createAutoModeDecider, type AutoModeVerdict, type AutoModeDecider, type AutoModeDeciderOptions, type AutoModeClassifyFn, type AutoModeClassifyInput, } from "./core/auto-mode.js";
 export { buildAutoModePrompt, renderAutoModeWindow, renderAutoModeAction, AUTO_MODE_DEFAULTS_SENTINEL, type AutoModeRules, type BuildAutoModePromptOptions, type AutoModeWindowOptions, } from "./core/auto-mode-prompt.js";
 export { AUTO_MODE_BASE_PROMPT, AUTO_MODE_PERMISSIONS_EXTERNAL } from "./core/auto-mode-prompt-assets.js";
 export { createPermissionRulePolicy, validatePermissionRules, parsePermissionRule, wildcardMatch, type PermissionRule, type ParsedPermissionRule, type PermissionRuleIssue, type PermissionRuleCaps, type PermissionRulePolicyOptions, } from "./core/permission-rules.js";
 export { parseAllowRuleText, formatAllowRuleText, ruleAdmitsCommand, findAdmittingRule, suggestRulesForCommand, scopeCoversCwd, pathWithinRoot, isRuleLive, BARE_INTERPRETER_NAMES, MAX_RULE_TEXT_CHARS, type PersistedAllowRule, type RuleTombstone, type RuleScope, type RuleDot, type RuleAdd, type RuleAddOrigin, type RuleSuggestion, type RuleReject, type RuleRejectCode, type ParsedAllowRule, type PersistedRuleTool, type PersistedRuleMatch, } from "./core/permission-rule-model.js";
 export { removePersistedRule, applyTombstones, sameScope, InMemoryPermissionRuleStore, EMPTY_RULE_STORE, type PermissionRuleStore, type PermissionRuleStoreProvider, type StoredAllowRules, type RemoveResult, type PutResult, } from "./core/permission-rule-store.js";
-export { prepareCardApproval, confirmRuleApproval, redeemRuleTicket, redeemRuleBatch, prepareCcImport, prepareStarterBatch, mintRuleTicket, STARTER_RULES, InMemoryRuleApprovalRecordStore, type RuleTicket, type RuleCandidate, type RuleApprovalKind, type RuleApprovalRecord, type RuleApprovalRecordStore, type RuleConsentDeps, type RedeemResult, type CcImportLayer, type ImportedSettingsLayer, type ImportPreview, type ImportResult, } from "./core/permission-rule-consent.js";
+export { prepareCardApproval, confirmRuleApproval, type ConfirmResult, type ConfirmRefusalReason, redeemRuleTicket, redeemRuleBatch, prepareCcImport, prepareStarterBatch, mintRuleTicket, STARTER_RULES, InMemoryRuleApprovalRecordStore, type RuleTicket, type RuleCandidate, type RuleApprovalKind, type RuleApprovalRecord, type RuleApprovalRecordStore, type RuleConsentDeps, type RedeemResult, type CcImportLayer, type ImportedSettingsLayer, type ImportPreview, type ImportResult, } from "./core/permission-rule-consent.js";
 export { FilePermissionRuleStoreProvider } from "./stores/file/permission-rule-store.js";
 export { formatHookFeedback, runToolGate, createHookEnvCapabilities, type Hooks, type HookToolContext, type HookEnvCapabilities, type HookToolOutput, type PreToolUseResult, type PostToolUseResult, type UserPromptSubmitResult, type HookToolFailure, type PostToolUseFailureResult, type PostToolBatchCall, type PostToolBatchResult, type PreCompactContext, type PreCompactResult, type PostCompactContext, type StopFailureContext, type PermissionDeniedPayload, type PermissionDeniedSource, } from "./core/hooks.js";
 export { InMemoryMemoryStore, composeMemoryBlock, composeLayeredMemoryBlock, normalizeMemorySpec, type NormalizedMemorySpec, type MemorySpecInput, supportsConsolidation, supportsPeriodicConsolidation, firstSentence, expandLexicalTerms, lexicalSearchMatch, type Embedder, classifyPromotable, enforcePromotableWriteGate, guardedMemoryStore, MemoryGateError, detectSecret, enforceSecretWriteGate, enforceStructuredNoteSecretGate, type UtilityGate, type MemoryStore, type MemoryVectorMode, type ScoredMemory, type MemoryNoteHeader, type MemoryNoteRecord, type MemoryNoteType, type StructuredNoteInput, } from "./core/memory.js";

package/dist/index.js

@@ -107,7 +107,7 @@ export { hasScheduler, isValidCronExpr, SchedulerError } from "./core/scheduler.
 export { createSchedulerTools, SCHEDULE_WAKEUP_TOOL_NAME, AUTONOMOUS_LOOP_SENTINEL, AUTONOMOUS_LOOP_DYNAMIC_SENTINEL, } from "./tools/scheduler-tools.js";
 export { resolveAutonomousLoopPrompt, AUTONOMOUS_LOOP_PREAMBLE, AUTONOMOUS_LOOP_PREAMBLE_PERSISTENT, } from "./tools/loop-tick.js";
 export { tightenTaskSpec, TaskSpecTightenError } from "./core/tighten-task-spec.js";
-export { createAllowDenyPolicy, createApprovalPolicy, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, decisionText, resolveAsk, toolPolicyNameSets, } from "./core/tool-policy.js";
+export { createAllowDenyPolicy, createApprovalPolicy, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, decisionText, resolveAsk, toolPolicyNameSets, APPROVAL_SETTLED_BY_VALUES, isApprovalSettledBy, } from "./core/tool-policy.js";
 export { parseAutoModeResponse, createAutoModeDecider, } from "./core/auto-mode.js";
 export { buildAutoModePrompt, renderAutoModeWindow, renderAutoModeAction, AUTO_MODE_DEFAULTS_SENTINEL, } from "./core/auto-mode-prompt.js";
 export { AUTO_MODE_BASE_PROMPT, AUTO_MODE_PERMISSIONS_EXTERNAL } from "./core/auto-mode-prompt-assets.js";

package/package.json

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